From 06c9ebe94acc099c3eaa319595c4955618d01525 Mon Sep 17 00:00:00 2001 From: Christopher Hogan Date: Wed, 24 Feb 2021 21:54:19 -0600 Subject: [PATCH] Add doxygen comments in H5Ppublic.h (#375) * Add doxygen comments in H5Ppublic.h * H5Pset_meta_block_size * H5Pset_metadata_read_attempts * H5Pset_multi_type * H5Pset_object_flush_cb * H5Pset_sieve_buf_size * H5Pset_small_data_block_size * H5Pset_all_coll_metadata_ops * H5Pget_all_coll_metadata_ops * Add DOXYGEN_EXAMPLES_DIR to src/CMakeLists.txt * Fix clang-format errors * Fix filenames in doxygen/examples --- MANIFEST | 3 + configure.ac | 2 + doxygen/Doxyfile.in | 4 +- doxygen/aliases | 7 + doxygen/dox/maybe_metadata_reads.dox | 82 +++++ .../examples/H5Pset_metadata_read_attempts.c | 59 ++++ doxygen/examples/H5Pset_object_flush_cb.c | 41 +++ src/CMakeLists.txt | 1 + src/H5Pmodule.h | 2 + src/H5Ppublic.h | 329 ++++++++++++++++++ 10 files changed, 528 insertions(+), 2 deletions(-) create mode 100644 doxygen/dox/maybe_metadata_reads.dox create mode 100644 doxygen/examples/H5Pset_metadata_read_attempts.c create mode 100644 doxygen/examples/H5Pset_object_flush_cb.c diff --git a/MANIFEST b/MANIFEST index 36b2808e873..07b0cbf5b42 100644 --- a/MANIFEST +++ b/MANIFEST @@ -224,9 +224,12 @@ ./doxygen/dox/H5Ovisit.dox ./doxygen/dox/H5Sencode.dox ./doxygen/dox/mainpage.dox +./doxygen/dox/maybe_metadata_reads.dox ./doxygen/dox/rm-template.dox ./doxygen/examples/H5Fclose.c ./doxygen/examples/H5Fcreate.c +./doxygen/examples/H5Pset_metadata_read_attempts.c +./doxygen/examples/H5Pset_object_flush_cb.c ./doxygen/examples/hello_hdf5.c ./doxygen/img/HDFG-logo.png diff --git a/configure.ac b/configure.ac index 131bd27a257..8b71be331dd 100644 --- a/configure.ac +++ b/configure.ac @@ -1116,6 +1116,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then AC_SUBST([DOXYGEN_OPTIMIZE_OUTPUT_FOR_C]) AC_SUBST([DOXYGEN_MACRO_EXPANSION]) AC_SUBST([DOXYGEN_OUTPUT_DIRECTORY]) + AC_SUBST([DOXYGEN_EXAMPLES_DIRECTORY]) DOXYGEN_PACKAGE=${PACKAGE_NAME} DOXYGEN_VERSION_STRING=${PACKAGE_VERSION} @@ -1126,6 +1127,7 @@ if test "X$HDF5_DOXYGEN" = "Xyes"; then DOXYGEN_OPTIMIZE_OUTPUT_FOR_C=YES DOXYGEN_MACRO_EXPANSION=YES DOXYGEN_OUTPUT_DIRECTORY=hdf5lib_docs + DOXYGEN_EXAMPLES_DIRECTORY='$(SRCDIR)/doxygen/examples' DX_INIT_DOXYGEN([HDF5], [../doxygen/Doxyfile], [hdf5lib_docs]) diff --git a/doxygen/Doxyfile.in b/doxygen/Doxyfile.in index 041be659fc0..e4054e2a3d1 100644 --- a/doxygen/Doxyfile.in +++ b/doxygen/Doxyfile.in @@ -915,7 +915,7 @@ EXCLUDE_SYMBOLS = # that contain example code fragments that are included (see the \include # command). -EXAMPLE_PATH = ../src ../examples ../test examples +EXAMPLE_PATH = ../src ../examples ../test @DOXYGEN_EXAMPLES_DIRECTORY@ # If the value of the EXAMPLE_PATH tag contains directories, you can use the # EXAMPLE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp and @@ -2175,7 +2175,7 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = +PREDEFINED = H5_HAVE_PARALLEL # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/doxygen/aliases b/doxygen/aliases index 66899ab72c4..cc08f5fe03d 100644 --- a/doxygen/aliases +++ b/doxygen/aliases @@ -35,6 +35,9 @@ ALIASES += op{1}="\param[in] \1 Callback function" ALIASES += op_data="\param[in,out] op_data User-defined callback function context" ALIASES += op_data{1}="\param[in,out] \1 User-defined callback function context" +ALIASES += op_data_in="\param[in] op_data User-defined callback function context" +ALIASES += op_data_in{1}="\param[in] \1 User-defined callback function context" + ################################################################################ # Attributes ################################################################################ @@ -128,6 +131,9 @@ ALIASES += dcpl_id{1}="\param[in] \1 Dataset creation property list identifier" ALIASES += dxpl_id="\param[in] dxpl_id Dataset transfer property list identifier" ALIASES += dxpl_id{1}="\param[in] \1 Dataset transfer property list identifier" +ALIASES += gacpl_id="\param[in] plist_id File, group, dataset, datatype, link, or attribute access property list identifier" +ALIASES += gacpl_id{1}="\param[in] \1 File, group, dataset, datatype, link, or attribute access property list identifier" + ALIASES += gapl_id="\param[in] gapl_id Group access property list identifier" ALIASES += gapl_id{1}="\param[in] \1 Group access property list identifier" @@ -189,6 +195,7 @@ ALIASES += es_id="\param[in] es_id The event set ID to add this asynchronous ope ALIASES += estack_id="\param[in] estack_id Error stack identifier" ALIASES += estack_id{1}="\param[in] \1 Error stack identifier" ALIASES += cpp_c_api_note="\note \Bold{C++ Developers using HDF5 C-API functions beware:}\n If a C routine that takes a function pointer as an argument is called from within C++ code, the C routine should be returned from normally. Examples of this kind of routine include callbacks such as H5Pset_elink_cb() and H5Pset_type_conv_cb() and functions such as H5Tconvert() and H5Ewalk2().\n Exiting the routine in its normal fashion allows the HDF5 C library to clean up its work properly. In other words, if the C++ application jumps out of the routine back to the C++ \c catch statement, the library is not given the opportunity to close any temporary data structures that were set up when the routine was called. The C++ application should save some state as the routine is started so that any problem that occurs might be diagnosed." +ALIASES += sa_metadata_ops="\sa \li H5Pget_all_coll_metadata_ops() \li H5Pget_coll_metadata_write() \li H5Pset_all_coll_metadata_ops() \li H5Pset_coll_metadata_write() \li \ref maybe_metadata_reads" ################################################################################ # The Usual Suspects diff --git a/doxygen/dox/maybe_metadata_reads.dox b/doxygen/dox/maybe_metadata_reads.dox new file mode 100644 index 00000000000..25c905fdfb7 --- /dev/null +++ b/doxygen/dox/maybe_metadata_reads.dox @@ -0,0 +1,82 @@ +/** + * \page maybe_metadata_reads Functions with No Access Property List Parameter that May Generate Metadata Reads + * + * \ingroup GACPL + * + * Currently there are several operations in HDF5 that can issue metadata reads + * from the metadata cache, but that take no property list. It is therefore not + * possible to set a collective requirement individually for those operations. The + * only solution with the HDF5 1.10.0 release is to set the collective requirement + * globally on H5Fopen() or H5Fcreate() for all metadata operations to be + * collective. + * + * The following is a list of those functions in the HDF5 library. This list is + * integral to the discussion in the H5Pset_all_coll_metadata_ops() entry: + * + * 
+ *
+ * H5Awrite()
+ * H5Aread()
+ * H5Arename()
+ * H5Aiterate2()
+ * H5Adelete()
+ * H5Aexists()
+ *
+ * H5Dget_space_status()
+ * H5Dget_storage_size()
+ * H5Dset_extent()
+ * H5Ddebug()
+ * H5Dclose()
+ * H5Dget_create_plist()
+ * H5Dget_space()   (when dataset is a virtual dataset)
+ *
+ * H5Gget_create_plist()
+ * H5Gget_info()
+ * H5Gclose()
+ *
+ * H5Literate()
+ * H5Lvisit()
+ *
+ * H5Rcreate()
+ * H5Rdereference2()   (when reference is an object reference)
+ * H5Rget_region()
+ * H5Rget_obj_type2()
+ * H5Rget_name()
+ *
+ * H5Ocopy()
+ * H5Oopen_by_addr()
+ * H5Oincr_refcount()
+ * H5Odecr_refcount()
+ * H5Oget_info()
+ * H5Oset_comment()
+ * H5Ovisit()
+ *
+ * H5Fis_hdf5()
+ * H5Fflush()
+ * H5Fclose()
+ * H5Fget_file_image()
+ * H5Freopen()
+ * H5Fget_freespace()
+ * H5Fget_info2()
+ * H5Fget_free_sections()
+ * H5Fmount()
+ * H5Funmount()
+ *
+ * H5Iget_name()
+ *
+ * H5Tget_create_plist()
+ * H5Tclose()
+ *
+ * H5Zunregister()
+ *
+ * + * In addition, \b most deprecated functions fall into this category. + * + * The HDF Group may address the above limitation in a future major release, but + * no decision has been made at this time. Such a change might, for example, + * include adding new versions of some or all the above functions with an extra + * property list parameter to allow an individual setting for the collective + * calling requirement. + * + * \sa_metadata_ops + */ diff --git a/doxygen/examples/H5Pset_metadata_read_attempts.c b/doxygen/examples/H5Pset_metadata_read_attempts.c new file mode 100644 index 00000000000..7c2f65d3208 --- /dev/null +++ b/doxygen/examples/H5Pset_metadata_read_attempts.c @@ -0,0 +1,59 @@ +//! [SWMR Access] +/* Create a copy of file access property list */ +fapl = H5Pcreate(H5P_FILE_ACCESS); + +/* Set the # of read attempts */ +H5Pset_metadata_read_attempts(fapl, 20); + +/* Open the file with SWMR access and the non-default file access property list */ +fid = H5Fopen(FILE, (H5F_ACC_RDONLY | H5F_ACC_SWMR_READ), fapl); + +/* Get the file's file access roperty list */ +file_fapl = H5Fget_access_plist(fid); + +/* Retrieve the # of read attempts from the file's file access property list */ +H5Pget_metadata_read_attempts(file_fapl, &attempts); + +/* + * The value returned in "attempts" will be 20. + * The library will use 20 as the number of read attempts + * when reading checksummed metadata in the file + */ + +/* Close the property list */ +H5Pclose(fapl); +H5Pclose(file_fapl); + +/* Close the file */ +H5Fclose(fid); +//! [SWMR Access] + +//! [non-SWMR Access] +/* Create a copy of file access property list */ +fapl = H5Pcreate(H5P_FILE_ACCESS); + +/* Set the # of read attempts */ +H5Pset_metadata_read_attempts(fapl, 20); + +/* Open the file with SWMR access and the non-default file access property list */ +fid = H5Fopen(FILE, H5F_ACC_RDONLY, fapl); + +/* Get the file's file access roperty list */ +file_fapl = H5Fget_access_plist(fid); + +/* Retrieve the # of read attempts from the file's file access property list */ +H5Pget_metadata_read_attempts(file_fapl, &attempts); + +/* + * The value returned in "attempts" will be 1 (default for non-SWMR access). + * The library will use 1 as the number of read attempts + * when reading checksummed metadata in the file + */ + +/* Close the property lists */ +H5Pclose(fapl); +H5Pclose(file_fapl); + +/* Close the file */ +H5Fclose(fid); +//! [non-SWMR Access] diff --git a/doxygen/examples/H5Pset_object_flush_cb.c b/doxygen/examples/H5Pset_object_flush_cb.c new file mode 100644 index 00000000000..1dfa90d7393 --- /dev/null +++ b/doxygen/examples/H5Pset_object_flush_cb.c @@ -0,0 +1,41 @@ +hid_t file_id, fapl_id; +hid_t dataset_id, dapl_id; +unsigned counter; + +/* Create a copy of the file access property list */ +fapl_id = H5Pcreate(H5P_FILE_ACCESS); + +/* Set up the object flush property values */ +/* flush_cb: callback function to invoke when an object flushes (see below) */ +/* counter: user data to pass along to the callback function */ +H5Pset_object_flush_cb(fapl_id, flush_cb, &counter); + +/* Open the file */ +file_id = H5Fopen(FILE, H5F_ACC_RDWR, H5P_DEFAULT); + +/* Create a group */ +gid = H5Gcreate2(fid, “group”, H5P_DEFAULT, H5P_DEFAULT_H5P_DEFAULT); + +/* Open a dataset */ +dataset_id = H5Dopen2(file_id, DATASET, H5P_DEFAULT); + +/* The flush will invoke flush_cb() with counter */ +H5Dflush(dataset_id); +/* counter will be equal to 1 */ + +/* ... */ + +/* The flush will invoke flush_cb() with counter */ +H5Gflush(gid); +/* counter will be equal to 2 */ + +/* ... */ + +/* The callback function for object flush property */ +static herr_t +flush_cb(hid_t obj_id, void *_udata) +{ + unsigned *flush_ct = (unsigned *)_udata; + ++(*flush_ct); + return 0; +} diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 610e905bb5e..42c90e067ea 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -1387,6 +1387,7 @@ if (DOXYGEN_FOUND) set (DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES) set (DOXYGEN_MACRO_EXPANSION YES) set (DOXYGEN_OUTPUT_DIRECTORY ${HDF5_BINARY_DIR}/hdf5lib_docs) + set (DOXYGEN_EXAMPLES_DIRECTORY ${HDF5_DOXYGEN_DIR}/examples) # Replace variables inside @@ with the current values configure_file(${HDF5_DOXYGEN_DIR}/Doxyfile.in Doxyfile @ONLY) diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index b9e11802e7d..6b22887c43a 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -70,6 +70,8 @@ * \ingroup H5P * \defgroup OCPPL Object Copy Properties * \ingroup H5P + * \defgroup GACPL General Access Properties + * \ingroup H5P */ #endif /* _H5Pmodule_H */ diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 23ad6b459fa..af9ed6ab38f 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -3939,11 +3939,253 @@ H5_DLL herr_t H5Pset_libver_bounds(hid_t plist_id, H5F_libver_t low, H5F_libver_ H5_DLL herr_t H5Pset_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr); H5_DLL herr_t H5Pset_mdc_log_options(hid_t plist_id, hbool_t is_enabled, const char *location, hbool_t start_on_access); +/** + * \ingroup FAPL + * + * \brief Sets the minimum metadata block size + * + * \fapl_id{fapl_id} + * \param[in] size Minimum size, in bytes, of metadata block allocations + * + * \return \herr_t + * + * \details H5Pset_meta_block_size() sets the minimum size, in bytes, of + * metadata block allocations when #H5FD_FEAT_AGGREGATE_METADATA is set by a VFL + * driver. + + * Each raw metadata block is initially allocated to be of the given size. + * Specific metadata objects (e.g., object headers, local heaps, B-trees) are then + * sub-allocated from this block. + * + * The default setting is 2048 bytes, meaning that the library will + * attempt to aggregate metadata in at least 2K blocks in the file. + * Setting the value to zero (\Code{0}) with this function will turn + * off metadata aggregation, even if the VFL driver attempts to use the + * metadata aggregation strategy. + * + * Metadata aggregation reduces the number of small data objects in the file that + * would otherwise be required for metadata. The aggregated block of metadata is + * usually written in a single write action and always in a contiguous block, + * potentially significantly improving library and application performance. + * + * \since 1.4.0 + */ H5_DLL herr_t H5Pset_meta_block_size(hid_t fapl_id, hsize_t size); +/** + * \ingroup FAPL + * + * \brief Sets the number of read attempts in a file access property list + * + * \fapl_id{plist_id} + * \param[in] attempts The number of read attempts. Must be a value greater than \Code{0} + * + * \return \herr_t + * + * \return Failure Modes: + * - When the user sets the number of read attempts to \Code{0}. + * - When the input property list is not a file access property list. + * - When the library is unable to set the number of read attempts in the file access property list. + * + * \details H5Pset_metadata_read_attempts() sets the number of reads that the + * library will try when reading checksummed metadata in an HDF5 file opened + * with SWMR access. When reading such metadata, the library will compare the + * checksum computed for the metadata just read with the checksum stored within + * the piece of checksum. When performing SWMR operations on a file, the + * checksum check might fail when the library reads data on a system that is not + * atomic. To remedy such situations, the library will repeatedly read the piece + * of metadata until the check passes or finally fails the read when the allowed + * number of attempts is reached. + * + * The number of read attempts used by the library will depend on how the file is + * opened and whether the user sets the number of read attempts via this routine: + + * - For a file opened with SWMR access: + * - If the user sets the number of attempts to \Code{N}, the library will use \Code{N}. + * - If the user does not set the number of attempts, the library will use the + * default for SWMR access (\Code{100}). + * - For a file opened with non-SWMR access, the library will always use the default + * for non-SWMR access (\Code{1}). The value set via this routine does not have any effect + * during non-SWMR access. + * + * \b Example: The first example illustrates the case in setting the number of read attempts for a file + * opened with SWMR access. + * + * \snippet H5Pset_metadata_read_attempts.c SWMR Access + * + * \b Example: The second example illustrates the case in setting the number of + * read attempts for a file opened with non-SWMR access. The value + * set in the file access property list does not have any effect. + * + * \snippet H5Pset_metadata_read_attempts.c non-SWMR Access + * + * \note \b Motivation: On a system that is not atomic, the library might + * possibly read inconsistent metadata with checksum when performing + * single-writer/multiple-reader (SWMR) operations for an HDF5 file. Upon + * encountering such situations, the library will try reading the metadata + * again to obtain consistent data. This routine provides the means to set + * the number of read attempts other than the library default. + * + * \since 1.10.0 + */ H5_DLL herr_t H5Pset_metadata_read_attempts(hid_t plist_id, unsigned attempts); +/** + * \ingroup FAPL + * + * \brief Specifies type of data to be accessed via the \Code{MULTI} driver, + * enabling more direct access + * + * \fapl_id{fapl_id} + * \param[in] type Type of data to be accessed + * + * \return \herr_t + * + * \details H5Pset_multi_type() sets the \Emph{type of data} property in the file + * access property list \p fapl_id. This setting enables a user + * application to specify the type of data the application wishes to + * access so that the application can retrieve a file handle for + * low-level access to the particular member of a set of \Code{MULTI} + * files in which that type of data is stored. The file handle is + * retrieved with a separate call to H5Fget_vfd_handle() (or, in special + * circumstances, to H5FDget_vfd_handle(); see \Emph{Virtual File Layer} and + * \Emph{List of VFL Functions} in \Emph{HDF5 Technical Notes}). + * + * \todo Link to Virtual File Layer and List of VFL Functions pages once HDF5 Technical + * Notes section is created + * + * The type of data specified in \p type may be one of the following: + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
#H5FD_MEM_SUPER Super block data
#H5FD_MEM_BTREE B-tree data
#H5FD_MEM_DRAW Dataset raw data
#H5FD_MEM_GHEAP Global heap data
#H5FD_MEM_LHEAP Local Heap data
#H5FD_MEM_OHDR Object header data
+ * + * This function is for use only when accessing an HDF5 file written as a set of + * files with the \Code{MULTI} file driver. + * + * \since 1.6.0 + */ H5_DLL herr_t H5Pset_multi_type(hid_t fapl_id, H5FD_mem_t type); +/** + * \ingroup FAPL + * + * \brief Sets a callback function to invoke when an object flush occurs in the file + * + * \fapl_id{plist_id} + * \op{func} + * \op_data_in{udata} + * + * \return \herr_t + * + * \details H5Pset_object_flush_cb() sets the callback function to invoke in the + * file access property list \p plist_id whenever an object flush occurs in + * the file. Library objects are group, dataset, and committed + * datatype. + * + * The callback function \p func must conform to the prototype defined below: + * \code + * typedef herr_t (*H5F_flush_cb_t)(hid_t object_id, void *user_data) + * \endcode + * + * The parameters of the callback function, per the above prototypes, are defined as follows: + * - \Code{object_id} is the identifier of the object which has just been flushed. + * - \Code{user_data} is the user-defined input data for the callback function. + * + * \b Example: The example below illustrates the usage of this routine to set + * the callback function to invoke when an object flush occurs. + * + * \include H5Pset_object_flush_cb.c + * + * \since 1.10.0 + */ H5_DLL herr_t H5Pset_object_flush_cb(hid_t plist_id, H5F_flush_cb_t func, void *udata); +/** + * \ingroup FAPL + * + * \brief Sets the maximum size of the data sieve buffer + * + * \fapl_id{fapl_id} + * \param[in] size Maximum size, in bytes, of data sieve buffer + * + * \return \herr_t + * + * \details H5Pset_sieve_buf_size() sets \p size, the maximum size in bytes of the + * data sieve buffer, which is used by file drivers that are capable of + * using data sieving. + * + * The data sieve buffer is used when performing I/O on datasets in the + * file. Using a buffer which is large enough to hold several pieces of + * the dataset being read in for hyperslab selections boosts + * performance by quite a bit. + * + * The default value is set to 64KB, indicating that file I/O for raw + * data reads and writes will occur in at least 64KB blocks. Setting + * the value to zero (\Code{0}) with this API function will turn off + * the data sieving, even if the VFL driver attempts to use that + * strategy. + * + * Internally, the library checks the storage sizes of the datasets in + * the file. It picks the smaller one between the size from the file + * access property and the size of the dataset to allocate the sieve + * buffer for the dataset in order to save memory usage. + * + * \version 1.6.0 The \p size parameter has changed from type \Code{hsize_t} to \Code{size_t}. + * + * \since 1.4.0 + */ H5_DLL herr_t H5Pset_sieve_buf_size(hid_t fapl_id, size_t size); +/** + * \ingroup FAPL + * + * \brief Sets the size of a contiguous block reserved for small data + * + * \fapl_id{fapl_id} + * \param[in] size Maximum size, in bytes, of the small data block. + The default size is \Code{2048}. + * + * \return \herr_t + * + * \details H5Pset_small_data_block_size() reserves blocks of \p size bytes for the + * contiguous storage of the raw data portion of \Emph{small} datasets. The + * HDF5 library then writes the raw data from small datasets to this + * reserved space, thus reducing unnecessary discontinuities within + * blocks of meta data and improving I/O performance. + * + * A small data block is actually allocated the first time a qualifying + * small dataset is written to the file. Space for the raw data portion + * of this small dataset is suballocated within the small data block. + * The raw data from each subsequent small dataset is also written to + * the small data block until it is filled; additional small data + * blocks are allocated as required. + * + * The HDF5 library employs an algorithm that determines whether I/O + * performance is likely to benefit from the use of this mechanism with + * each dataset as storage space is allocated in the file. A larger + * \p size will result in this mechanism being employed with larger + * datasets. + * + * The small data block size is set as an allocation property in the + * file access property list identified by \p fapl_id. + * + * Setting \p size to zero (\Code{0}) disables the small data block mechanism. + * + * \since 1.4.4 + */ H5_DLL herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size); /** * \ingroup FAPL @@ -3966,7 +4208,94 @@ H5_DLL herr_t H5Pset_small_data_block_size(hid_t fapl_id, hsize_t size); H5_DLL herr_t H5Pset_vol(hid_t plist_id, hid_t new_vol_id, const void *new_vol_info); #ifdef H5_HAVE_PARALLEL +/** + * \ingroup GACPL + * + * \brief Sets metadata I/O mode for read operations to collective or independent (default) + * + * \gacpl_id + * \param[in] is_collective Boolean value indicating whether metadata reads are collective + * (\Code{1}) or independent (\Code{0}). + * Default mode: Independent (\Code{0}) + * + * \return \herr_t + * + * \details H5Pset_all_coll_metadata_ops() sets the metadata I/O mode for read + * operations in the access property list \p plist_id. + * + * When engaging in parallel I/O, all metadata write operations must be + * collective. If \p is_collective is \Code{1}, this property specifies + * that the HDF5 library will perform all metadata read operations + * collectively; if \p is_collective is \Code{0}, such operations may + * be performed independently. + * + * Users must be aware that several HDF5 operations can potentially + * issue metadata reads. These include opening a dataset, datatype, or + * group; reading an attribute; or issuing a \Emph{get info} call such + * as getting information for a group with H5Fget_info(). Collective + * I/O requirements must be kept in mind when issuing such calls in the + * context of parallel I/O. + * + * If this property is collective on a file access property list that + * is used in creating or opening a file, then the HDF5 library will + * assume that all metadata read operations issued on that file + * identifier will be issued collectively from all ranks irrespective + * of the individual setting of a particular operation. If this + * assumption is not adhered to, corruption will be introduced in the + * metadata cache and HDF5’s behavior will be undefined. + * + * Alternatively, a user may wish to avoid setting this property + * globally on the file access property list, and individually set it + * on particular object access property lists (dataset, group, link, + * datatype, attribute access property lists) for certain operations. + * This will indicate that only the operations issued with such an + * access property list will be called collectively and other + * operations may potentially be called independently. There are, + * however, several HDF5 operations that can issue metadata reads but + * have no property list in their function signatures to allow passing + * the collective requirement property. For those operations, the only + * option is to set the global collective requirement property on the + * file access property list; otherwise the metadata reads that can be + * triggered from those operations will be done independently by each + * process. + * + * Functions that do not accommodate an access property list but that + * might issue metadata reads are listed in \ref maybe_metadata_reads. + * + * \attention As noted above, corruption will be introduced into the metadata + * cache and HDF5 library behavior will be undefined when both of the following + * conditions exist: + * - A file is created or opened with a file access property list in which the + * collective metadata I/O property is set to \Code{1}. + * - Any function is called that triggers an independent metadata read while the + * file remains open with that file access property list. + * + * \attention An approach that avoids this corruption risk is described above. + * + * \sa_metadata_ops + * + * \since 1.10.0 + */ H5_DLL herr_t H5Pset_all_coll_metadata_ops(hid_t plist_id, hbool_t is_collective); +/** + * \ingroup GACPL + * + * \brief Retrieves metadata read mode setting + * + * \gacpl_id + * \param[out] is_collective Pointer to a buffer containing the Boolean value indicating whether metadata + * reads are collective (\Code{>0}) or independent (\Code{0}). + * Default mode: Independent (\Code{0}) + * + * \return \herr_t + * + * \details H5Pget_all_coll_metadata_ops() retrieves the collective metadata read setting from the access + * property list \p plist_id into \p is_collective. + * + * \sa_metadata_ops + * + * \since 1.10.0 + */ H5_DLL herr_t H5Pget_all_coll_metadata_ops(hid_t plist_id, hbool_t *is_collective); H5_DLL herr_t H5Pset_coll_metadata_write(hid_t plist_id, hbool_t is_collective); H5_DLL herr_t H5Pget_coll_metadata_write(hid_t plist_id, hbool_t *is_collective);