1 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * 2 * Copyright by The HDF Group. * 3 * Copyright by the Board of Trustees of the University of Illinois. * 4 * All rights reserved. * 5 * * 6 * This file is part of HDF5. The full HDF5 copyright notice, including * 7 * terms governing use, modification, and redistribution, is contained in * 8 * the COPYING file, which can be found at the root of the source code * 9 * distribution tree, or in https://www.hdfgroup.org/licenses. * 10 * If you do not have access to either file, you may request a copy from * 11 * help@hdfgroup.org. * 12 * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ 13 14 /* 15 * Programmer: Robb Matzke 16 * Monday, August 2, 1999 17 * 18 * Purpose: The public header file for the mpio driver. 19 */ 20 #ifndef H5FDmpio_H 21 #define H5FDmpio_H 22 23 /* Macros */ 24 25 #ifdef H5_HAVE_PARALLEL 26 #define H5FD_MPIO (H5FD_mpio_init()) 27 #else 28 #define H5FD_MPIO (H5I_INVALID_HID) 29 #endif /* H5_HAVE_PARALLEL */ 30 31 #ifdef H5_HAVE_PARALLEL 32 /*Turn on H5FDmpio_debug if H5F_DEBUG is on */ 33 #ifdef H5F_DEBUG 34 #ifndef H5FDmpio_DEBUG 35 #define H5FDmpio_DEBUG 36 #endif 37 #endif 38 39 /* Global var whose value comes from environment variable */ 40 /* (Defined in H5FDmpio.c) */ 41 H5_DLLVAR hbool_t H5FD_mpi_opt_types_g; 42 43 /* Function prototypes */ 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 H5_DLL hid_t H5FD_mpio_init(void); 48 49 /** 50 * \ingroup FAPL 51 * 52 * \brief Stores MPI IO communicator information to the file access property list 53 * 54 * \fapl_id 55 * \param[in] comm MPI-2 communicator 56 * \param[in] info MPI-2 info object 57 * \returns \herr_t 58 * 59 * \details H5Pset_fapl_mpio() stores the user-supplied MPI IO parameters \p 60 * comm, for communicator, and \p info, for information, in the file 61 * access property list \p fapl_id. That property list can then be used 62 * to create and/or open a file. 63 * 64 * H5Pset_fapl_mpio() is available only in the parallel HDF5 library 65 * and is not a collective function. 66 * 67 * \p comm is the MPI communicator to be used for file open, as defined 68 * in \c MPI_File_open of MPI-2. This function makes a duplicate of the 69 * communicator, so modifications to \p comm after this function call 70 * returns have no effect on the file access property list. 71 * 72 * \p info is the MPI Info object to be used for file open, as defined 73 * in MPI_File_open() of MPI-2. This function makes a duplicate copy of 74 * the Info object, so modifications to the Info object after this 75 * function call returns will have no effect on the file access 76 * property list. 77 * 78 * If the file access property list already contains previously-set 79 * communicator and Info values, those values will be replaced and the 80 * old communicator and Info object will be freed. 81 * 82 * \note Raw dataset chunk caching is not currently supported when using this 83 * file driver in read/write mode. All calls to H5Dread() and H5Dwrite() 84 * will access the disk directly, and H5Pset_cache() and 85 * H5Pset_chunk_cache() will have no effect on performance.\n 86 * Raw dataset chunk caching is supported when this driver is used in 87 * read-only mode. 88 * 89 * \version 1.4.5 Handling of the MPI Communicator and Info object changed at 90 * this release. A duplicate of each of these is now stored in the property 91 * list instead of pointers to each. 92 * \since 1.4.0 93 * 94 */ 95 H5_DLL herr_t H5Pset_fapl_mpio(hid_t fapl_id, MPI_Comm comm, MPI_Info info); 96 97 /** 98 * \ingroup FAPL 99 * 100 * \brief Returns MPI IO communicator information 101 * 102 * \fapl_id 103 * \param[out] comm MPI-2 communicator 104 * \param[out] info MPI-2 info object 105 * \returns \herr_t 106 * 107 * \details If the file access property list is set to the #H5FD_MPIO driver, 108 * H5Pget_fapl_mpio() returns duplicates of the stored MPI communicator 109 * and Info object through the \p comm and \p info pointers, if those 110 * values are non-null. 111 * 112 * Since the MPI communicator and Info object are duplicates of the 113 * stored information, future modifications to the access property list 114 * will not affect them. It is the responsibility of the application to 115 * free these objects. 116 * 117 * \version 1.4.5 Handling of the MPI Communicator and Info object changed at 118 * this release. A duplicate of each of these is now stored in the 119 * property list instead of pointers to each. 120 * \since 1.4.0 121 * 122 */ 123 H5_DLL herr_t H5Pget_fapl_mpio(hid_t fapl_id, MPI_Comm *comm /*out*/, MPI_Info *info /*out*/); 124 125 /** 126 * \ingroup DXPL 127 * 128 * \brief Sets data transfer mode 129 * 130 * \dxpl_id 131 * \param[in] xfer_mode Transfer mode 132 * \returns \herr_t 133 * 134 * \details H5Pset_dxpl_mpio() sets the data transfer property list \p dxpl_id 135 * to use transfer mode \p xfer_mode. The property list can then be 136 * used to control the I/O transfer mode during data I/O operations. 137 * 138 * Valid transfer modes are #H5FD_MPIO_INDEPENDENT (default) and 139 * #H5FD_MPIO_COLLECTIVE. 140 * 141 * \since 1.4.0 142 * 143 */ 144 H5_DLL herr_t H5Pset_dxpl_mpio(hid_t dxpl_id, H5FD_mpio_xfer_t xfer_mode); 145 146 /** 147 * \ingroup DXPL 148 * 149 * \brief Returns the data transfer mode 150 * 151 * \dxpl_id 152 * \param[out] xfer_mode Transfer mode 153 * \returns \herr_t 154 * 155 * \details H5Pget_dxpl_mpio() queries the data transfer mode currently set in 156 * the data transfer property list \p dxpl_id. 157 * 158 * Upon return, \p xfer_mode contains the data transfer mode, if it is 159 * non-null. 160 * 161 * H5Pget_dxpl_mpio() is not a collective function. 162 * 163 * \since 1.4.0 164 * 165 */ 166 H5_DLL herr_t H5Pget_dxpl_mpio(hid_t dxpl_id, H5FD_mpio_xfer_t *xfer_mode /*out*/); 167 168 /** 169 * \ingroup DXPL 170 * 171 * \brief Sets data transfer mode 172 * 173 * \dxpl_id 174 * \param[in] opt_mode Transfer mode 175 * \returns \herr_t 176 * 177 * \details H5Pset_dxpl_mpio() sets the data transfer property list \p dxpl_id 178 * to use transfer mode xfer_mode. The property list can then be used 179 * to control the I/O transfer mode during data I/O operations. 180 * 181 * Valid transfer modes are #H5FD_MPIO_INDEPENDENT (default) and 182 * #H5FD_MPIO_COLLECTIVE. 183 * 184 * \since 1.4.0 185 * 186 */ 187 H5_DLL herr_t H5Pset_dxpl_mpio_collective_opt(hid_t dxpl_id, H5FD_mpio_collective_opt_t opt_mode); 188 189 /** 190 * \ingroup DXPL 191 * 192 * \brief Sets a flag specifying linked-chunk I/O or multi-chunk I/O 193 * 194 * \dxpl_id 195 * \param[in] opt_mode Transfer mode 196 * \returns \herr_t 197 * 198 * \details H5Pset_dxpl_mpio_chunk_opt() specifies whether I/O is to be 199 * performed as linked-chunk I/O or as multi-chunk I/O. This function 200 * overrides the HDF5 library's internal algorithm for determining 201 * which mechanism to use. 202 * 203 * When an application uses collective I/O with chunked storage, the 204 * HDF5 library normally uses an internal algorithm to determine 205 * whether that I/O activity should be conducted as one linked-chunk 206 * I/O or as multi-chunk I/O. H5Pset_dxpl_mpio_chunk_opt() is provided 207 * so that an application can override the library's algorithm in 208 * circumstances where the library might lack the information needed to 209 * make an optimal decision. 210 * 211 * H5Pset_dxpl_mpio_chunk_opt() works by setting one of the following 212 * flags in the parameter \p opt_mode: 213 * - #H5FD_MPIO_CHUNK_ONE_IO - Do one-link chunked I/O 214 * - #H5FD_MPIO_CHUNK_MULTI_IO - Do multi-chunked I/O 215 * 216 * This function works by setting a corresponding property in the 217 * dataset transfer property list \p dxpl_id. 218 * 219 * The library performs I/O in the specified manner unless it 220 * determines that the low-level MPI IO package does not support the 221 * requested behavior; in such cases, the HDF5 library will internally 222 * use independent I/O. 223 * 224 * Use of this function is optional. 225 * 226 * \todo Add missing version information 227 * 228 */ 229 H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t opt_mode); 230 231 /** 232 * \ingroup DXPL 233 * 234 * \brief Sets a numeric threshold for linked-chunk I/O 235 * 236 * \dxpl_id 237 * \param[in] num_chunk_per_proc 238 * \returns \herr_t 239 * 240 * \details H5Pset_dxpl_mpio_chunk_opt_num() sets a numeric threshold for the 241 * use of linked-chunk I/O. 242 * 243 * The library will calculate the average number of chunks selected by 244 * each process when doing collective access with chunked storage. If 245 * the number is greater than the threshold set in \p 246 * num_chunk_per_proc, the library will use linked-chunk I/O; 247 * otherwise, a separate I/O process will be invoked for each chunk 248 * (multi-chunk I/O). 249 * 250 * \todo Add missing version information 251 * 252 */ 253 H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_per_proc); 254 255 /** 256 * \ingroup DXPL 257 * 258 * \brief Sets a ratio threshold for collective I/O 259 * 260 * \dxpl_id 261 * \param[in] percent_num_proc_per_chunk 262 * \returns \herr_t 263 * 264 * \details H5Pset_dxpl_mpio_chunk_opt_ratio() sets a threshold for the use of 265 * collective I/O based on the ratio of processes with collective 266 * access to a dataset with chunked storage. The decision whether to 267 * use collective I/O is made on a per-chunk basis. 268 * 269 * The library will calculate the percentage of the total number of 270 * processes, the ratio, that hold selections in each chunk. If that 271 * percentage is greater than the threshold set in \p 272 * percent_proc_per_chunk, the library will do collective I/O for this 273 * chunk; otherwise, independent I/O will be done for the chunk. 274 * 275 * \todo Add missing version information 276 * 277 */ 278 H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_ratio(hid_t dxpl_id, unsigned percent_num_proc_per_chunk); 279 #ifdef __cplusplus 280 } 281 #endif 282 283 #endif /* H5_HAVE_PARALLEL */ 284 285 #endif 286