/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 * Copyright by The HDF Group.                                               *
 * Copyright by the Board of Trustees of the University of Illinois.         *
 * All rights reserved.                                                      *
 *                                                                           *
 * This file is part of HDF5.  The full HDF5 copyright notice, including     *
 * terms governing use, modification, and redistribution, is contained in    *
 * the COPYING file, which can be found at the root of the source code       *
 * distribution tree, or in https://www.hdfgroup.org/licenses.               *
 * If you do not have access to either file, you may request a copy from     *
 * help@hdfgroup.org.                                                        *
 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */

/*
 * Programmer:  Robb Matzke
 *              Monday, August  2, 1999
 *
 * Purpose:	The public header file for the mpio driver.
 */
#ifndef H5FDmpio_H
#define H5FDmpio_H

/* Macros */

#ifdef H5_HAVE_PARALLEL
#define H5FD_MPIO (H5FD_mpio_init())
#else
#define H5FD_MPIO (H5I_INVALID_HID)
#endif /* H5_HAVE_PARALLEL */

#ifdef H5_HAVE_PARALLEL
/*Turn on H5FDmpio_debug if H5F_DEBUG is on */
#ifdef H5F_DEBUG
#ifndef H5FDmpio_DEBUG
#define H5FDmpio_DEBUG
#endif
#endif

/* Global var whose value comes from environment variable */
/* (Defined in H5FDmpio.c) */
H5_DLLVAR hbool_t H5FD_mpi_opt_types_g;

/* Function prototypes */
#ifdef __cplusplus
extern "C" {
#endif
H5_DLL hid_t H5FD_mpio_init(void);

/**
 * \ingroup FAPL
 *
 * \brief Stores MPI IO communicator information to the file access property list
 *
 * \fapl_id
 * \param[in] comm MPI-2 communicator
 * \param[in] info MPI-2 info object
 * \returns \herr_t
 *
 * \details H5Pset_fapl_mpio() stores the user-supplied MPI IO parameters \p
 *          comm, for communicator, and \p info, for information, in the file
 *          access property list \p fapl_id. That property list can then be used
 *          to create and/or open a file.
 *
 *          H5Pset_fapl_mpio() is available only in the parallel HDF5 library
 *          and is not a collective function.
 *
 *          \p comm is the MPI communicator to be used for file open, as defined
 *          in \c MPI_File_open of MPI-2. This function makes a duplicate of the
 *          communicator, so modifications to \p comm after this function call
 *          returns have no effect on the file access property list.
 *
 *          \p info is the MPI Info object to be used for file open, as defined
 *          in MPI_File_open() of MPI-2. This function makes a duplicate copy of
 *          the Info object, so modifications to the Info object after this
 *          function call returns will have no effect on the file access
 *          property list.
 *
 *          If the file access property list already contains previously-set
 *          communicator and Info values, those values will be replaced and the
 *          old communicator and Info object will be freed.
 *
 * \note Raw dataset chunk caching is not currently supported when using this
 *       file driver in read/write mode. All calls to H5Dread() and H5Dwrite()
 *       will access the disk directly, and H5Pset_cache() and
 *       H5Pset_chunk_cache() will have no effect on performance.\n
 *       Raw dataset chunk caching is supported when this driver is used in
 *       read-only mode.
 *
 * \version 1.4.5 Handling of the MPI Communicator and Info object changed at
 *          this release. A duplicate of each of these is now stored in the property
 *          list instead of pointers to each.
 * \since 1.4.0
 *
 */
H5_DLL herr_t H5Pset_fapl_mpio(hid_t fapl_id, MPI_Comm comm, MPI_Info info);

/**
 * \ingroup FAPL
 *
 * \brief Returns MPI IO communicator information
 *
 * \fapl_id
 * \param[out] comm MPI-2 communicator
 * \param[out] info MPI-2 info object
 * \returns \herr_t
 *
 * \details If the file access property list is set to the #H5FD_MPIO driver,
 *          H5Pget_fapl_mpio() returns duplicates of the stored MPI communicator
 *          and Info object through the \p comm and \p info pointers, if those
 *          values are non-null.
 *
 *          Since the MPI communicator and Info object are duplicates of the
 *          stored information, future modifications to the access property list
 *          will not affect them. It is the responsibility of the application to
 *          free these objects.
 *
 * \version 1.4.5 Handling of the MPI Communicator and Info object changed at
 *          this release. A duplicate of each of these is now stored in the
 *          property list instead of pointers to each.
 * \since 1.4.0
 *
 */
H5_DLL herr_t H5Pget_fapl_mpio(hid_t fapl_id, MPI_Comm *comm /*out*/, MPI_Info *info /*out*/);

/**
 * \ingroup DXPL
 *
 * \brief Sets data transfer mode
 *
 * \dxpl_id
 * \param[in] xfer_mode Transfer mode
 * \returns \herr_t
 *
 * \details H5Pset_dxpl_mpio() sets the data transfer property list \p dxpl_id
 *          to use transfer mode \p xfer_mode. The property list can then be
 *          used to control the I/O transfer mode during data I/O operations.
 *
 *          Valid transfer modes are #H5FD_MPIO_INDEPENDENT (default) and
 *          #H5FD_MPIO_COLLECTIVE.
 *
 * \since 1.4.0
 *
 */
H5_DLL herr_t H5Pset_dxpl_mpio(hid_t dxpl_id, H5FD_mpio_xfer_t xfer_mode);

/**
 * \ingroup DXPL
 *
 * \brief Returns the data transfer mode
 *
 * \dxpl_id
 * \param[out] xfer_mode Transfer mode
 * \returns \herr_t
 *
 * \details H5Pget_dxpl_mpio() queries the data transfer mode currently set in
 *          the data transfer property list \p dxpl_id.
 *
 *          Upon return, \p xfer_mode contains the data transfer mode, if it is
 *          non-null.
 *
 *          H5Pget_dxpl_mpio() is not a collective function.
 *
 * \since 1.4.0
 *
 */
H5_DLL herr_t H5Pget_dxpl_mpio(hid_t dxpl_id, H5FD_mpio_xfer_t *xfer_mode /*out*/);

/**
 * \ingroup DXPL
 *
 * \brief Sets data transfer mode
 *
 * \dxpl_id
 * \param[in] opt_mode Transfer mode
 * \returns \herr_t
 *
 * \details H5Pset_dxpl_mpio() sets the data transfer property list \p dxpl_id
 *          to use transfer mode xfer_mode. The property list can then be used
 *          to control the I/O transfer mode during data I/O operations.
 *
 *          Valid transfer modes are #H5FD_MPIO_INDEPENDENT (default) and
 *          #H5FD_MPIO_COLLECTIVE.
 *
 * \since 1.4.0
 *
 */
H5_DLL herr_t H5Pset_dxpl_mpio_collective_opt(hid_t dxpl_id, H5FD_mpio_collective_opt_t opt_mode);

/**
 * \ingroup DXPL
 *
 * \brief Sets a flag specifying linked-chunk I/O or multi-chunk I/O
 *
 * \dxpl_id
 * \param[in] opt_mode Transfer mode
 * \returns \herr_t
 *
 * \details H5Pset_dxpl_mpio_chunk_opt() specifies whether I/O is to be
 *          performed as linked-chunk I/O or as multi-chunk I/O. This function
 *          overrides the HDF5 library's internal algorithm for determining
 *          which mechanism to use.
 *
 *          When an application uses collective I/O with chunked storage, the
 *          HDF5 library normally uses an internal algorithm to determine
 *          whether that I/O activity should be conducted as one linked-chunk
 *          I/O or as multi-chunk I/O. H5Pset_dxpl_mpio_chunk_opt() is provided
 *          so that an application can override the library's algorithm in
 *          circumstances where the library might lack the information needed to
 *          make an optimal decision.
 *
 *          H5Pset_dxpl_mpio_chunk_opt() works by setting one of the following
 *          flags in the parameter \p opt_mode:
 *          - #H5FD_MPIO_CHUNK_ONE_IO -	Do one-link chunked I/O
 *          - #H5FD_MPIO_CHUNK_MULTI_IO - Do multi-chunked I/O
 *
 *          This function works by setting a corresponding property in the
 *          dataset transfer property list \p dxpl_id.
 *
 *          The library performs I/O in the specified manner unless it
 *          determines that the low-level MPI IO package does not support the
 *          requested behavior; in such cases, the HDF5 library will internally
 *          use independent I/O.
 *
 *          Use of this function is optional.
 *
 * \todo Add missing version information
 *
 */
H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t opt_mode);

/**
 * \ingroup DXPL
 *
 * \brief Sets a numeric threshold for linked-chunk I/O
 *
 * \dxpl_id
 * \param[in] num_chunk_per_proc
 * \returns \herr_t
 *
 * \details H5Pset_dxpl_mpio_chunk_opt_num() sets a numeric threshold for the
 *          use of linked-chunk I/O.
 *
 *          The library will calculate the average number of chunks selected by
 *          each process when doing collective access with chunked storage. If
 *          the number is greater than the threshold set in \p
 *          num_chunk_per_proc, the library will use linked-chunk I/O;
 *          otherwise, a separate I/O process will be invoked for each chunk
 *          (multi-chunk I/O).
 *
 * \todo Add missing version information
 *
 */
H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_per_proc);

/**
 * \ingroup DXPL
 *
 * \brief Sets a ratio threshold for collective I/O
 *
 * \dxpl_id
 * \param[in] percent_num_proc_per_chunk
 * \returns \herr_t
 *
 * \details H5Pset_dxpl_mpio_chunk_opt_ratio() sets a threshold for the use of
 *          collective I/O based on the ratio of processes with collective
 *          access to a dataset with chunked storage. The decision whether to
 *          use collective I/O is made on a per-chunk basis.
 *
 *          The library will calculate the percentage of the total number of
 *          processes, the ratio, that hold selections in each chunk. If that
 *          percentage is greater than the threshold set in \p
 *          percent_proc_per_chunk, the library will do collective I/O for this
 *          chunk; otherwise, independent I/O will be done for the chunk.
 *
 * \todo Add missing version information
 *
 */
H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_ratio(hid_t dxpl_id, unsigned percent_num_proc_per_chunk);
#ifdef __cplusplus
}
#endif

#endif /* H5_HAVE_PARALLEL */

#endif