diff options
| author | Gerd Heber <gheber@hdfgroup.org> | 2021-04-26 19:07:29 (GMT) |
|---|---|---|
| committer | GitHub <noreply@github.com> | 2021-04-26 19:07:29 (GMT) |
| commit | 1d680fe04c545d601678d876ad22dea7bfc31edd (patch) | |
| tree | f84a97c149df9ccf4409c5bfea04a7316c019e8a /src | |
| parent | 12082e728de7481144db7ea3cca6f38acf0a7cac (diff) | |
| download | hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.zip hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.tar.gz hdf5-1d680fe04c545d601678d876ad22dea7bfc31edd.tar.bz2 | |
Merge doxygen2 into develop (#553)
* Fixed warnings and started H5Epublic.h.
* Include H5FD* headers to correctly resolve references.
* Doxygen2 (#330)
* H5Eauto_is_v2.
* Added a few more calls.
* Added a few more H5E calls.
* First cut of H5E v2.
* Added the deprecated v1 calls.
* Updated spacing.
* Once more.
* Taking some inspiration from Eigen3.
* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pen… (#352)
* Add doxygen for the assigned functions: H5Pregister1,H5Pinsert1,H5Pencode1, H5Pget_filter_by_id1,H5Pget_version, H5Pset_file_space,H5Pget_file_space. Someone already adds H5Pget_filter1. Also fixs an extra parameter 'close' call back function for HPregister2.
* doxygen work. fixs format by using clang-format.
* doxgen work for H5Pregister1 etc. Addressed Barbara and Gerd's comments.
For Quincey's comments, since we are not supposed to change the source code.
I leave this to future improvements.
* added documentation for H5P APIs (#350)
* add documenation for H5Pget_buffer,H5Pget_data_transform,H5Pget_edc_check,H5Pget_hyper_vector_size,H5Pget_preserve,H5Pget_type_conv_cb,H5Pget_vlen_mem_manager,H5Pset_btree_ratios
* format corrections
* fixed grammer
* fixed herr_t
* Better name.
* A fresh look.
* add doxygen to H5Ppublic.h
* use attention instead of warning
* 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
* add doxygen to H5Ppublic.h (#378)
* add doxygen to H5Ppublic.h
* use attention instead of warning
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
* Revert "add doxygen to H5Ppublic.h (#378)"
This reverts commit 2ee1821b138a5c00b15ea57ce9e950367480f5f2.
* Updated Doxygen variables.
* I forgot to copy two images.
* Enable desktop search by default.
* Add my assigned Doxygen documentation.
* Remove whitespace at EOL. Appease clang-format.
* Addressed Chris' comments.
* Added an alias for asynchronous functions.
* One space is enough for all of us.
* Slightly restructured RM page.
* address some issues
* reformatting
* Style external links.
* reformatting
* reformatting
* Added "Metadata Caching in HDF5" as a technical note example.
* Revise this soon!
* Added specification examples.
* Fixed references.
* Added H5AC cache image stuff and file format study.
* Added older FMT versions. Where did 1.0 go?
* Updated C/C++ note and replaced ambiguous labels.
* Reformat source with clang v10.0.1.
* Added the VFL technical note.
* Added what I believe might be called version 1.0 of the format.
* Added the remaining specs.
* Added H5Z callback documentation and fixed a few mistakes.
* Added dox for deprecated H5G calls and fixed a few snippet blockIDs.
* clang-format happy?
* Ok?
* Bonus track: Deprecated H5D functions.
* Carry over the more detailed group description.
* Added documentation for the missing and deprecated H5R calls.
* Life is easier and less repetitive w/ snippets. Use them!
* Eliminate the snippet block ID artifacts in the HTML rendering.
* Fixed snippet HTML artifacts and added a few missing calls.
* Under 20 H5Ps to go!
* Almost complete!
* "This is a form of pedantry up with which I will not put." (Churchill)
* Let's not waste as much space on bulleted lists!
* First complete (?) draft of the Doxygen-based RM.
* Completeness check and minor fixes along the way.
* Pedantry.
* Adding missing H5FD calls checkpoint.
* Pedantry.
* More pedantry.
* Added H5Pset_fapl_log.
* First draft of H5ES.
* Fixed warnings.
* Prep. for map module.
* First cut of the map module.
* Pedantry.
* Possible H5F introduction.
* Fix the indentation.
* Pedantry.
* Ditto.
* Thanks to the reviewers for their comments.
* Added missing images.
* Line numbers are a distraction here.
* More examples, references, and clean-up. Don't repeat yourself!
* Clang pedantry.
* Ditto.
* More reviewer comments...
* Templatized references and cleaned up \todos.
* Committing clang-format changes
* Fixed MANIFEST.
* Addressed Quincey's comments. (OCPLs)
* Fixed a few more \todo items.
* Fixed more \todo items.
* Added attribute life cycle.
* Forgot the examples file.
* Committing clang-format changes
* Pedantry.
* Live and learn!
* Added a sample H5D life cycle.
* Committing clang-format changes
* Pedantry.
Co-authored-by: kyang2014 <kyang2014@users.noreply.github.com>
Co-authored-by: Scot Breitenfeld <brtnfld@hdfgroup.org>
Co-authored-by: Kimmy Mu <kmu@hdfgroup.org>
Co-authored-by: Christopher Hogan <ChristopherHogan@users.noreply.github.com>
Co-authored-by: jya-kmu <53388330+jya-kmu@users.noreply.github.com>
Co-authored-by: David Young <dyoung@hdfgroup.org>
Co-authored-by: Larry Knox <lrknox@hdfgroup.org>
Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>
Diffstat (limited to 'src')
49 files changed, 8034 insertions, 1636 deletions
diff --git a/src/CMakeLists.txt b/src/CMakeLists.txt index 0c92bb2..74fd71f 100644 --- a/src/CMakeLists.txt +++ b/src/CMakeLists.txt @@ -1378,6 +1378,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) # This configure and custom target work together # Replace variables inside @@ with the current values diff --git a/src/H5ACpublic.h b/src/H5ACpublic.h index e6cebff..f8f4f28 100644 --- a/src/H5ACpublic.h +++ b/src/H5ACpublic.h @@ -442,124 +442,347 @@ extern "C" { #define H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY 0 #define H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED 1 +/** + * H5AC_cache_config_t is a public structure intended for use in public APIs. + * At least in its initial incarnation, it is basically a copy of \c struct + * \c H5C_auto_size_ctl_t, minus the \c report_fcn field, and plus the + * \c dirty_bytes_threshold field. + * + * The \c report_fcn field is omitted, as including it would require us to make + * \c H5C_t structure public. + * + * The \c dirty_bytes_threshold field does not appear in \c H5C_auto_size_ctl_t, + * as synchronization between caches on different processes is handled at the \c + * H5AC level, not at the level of \c H5C. Note however that there is + * considerable interaction between this value and the other fields in this + * structure. + * + * Similarly, the \c open_trace_file, \c close_trace_file, and \c + * trace_file_name fields do not appear in \c H5C_auto_size_ctl_t, as most trace + * file issues are handled at the \c H5AC level. The one exception is storage + * of the pointer to the trace file, which is handled by \c H5C. + * + * The structure is in H5ACpublic.h as we may wish to allow different + * configuration options for metadata and raw data caches. + */ + +//! <!-- [H5AC_cache_config_t_snip] --> typedef struct H5AC_cache_config_t { /* general configuration fields: */ + //! <!-- [H5AC_cache_config_t_general_snip] --> int version; + /**< Integer field indicating the the version of the H5AC_cache_config_t + * in use. This field should be set to #H5AC__CURR_CACHE_CONFIG_VERSION + * (defined in H5ACpublic.h). */ hbool_t rpt_fcn_enabled; + /**< Boolean flag indicating whether the adaptive cache resize report + * function is enabled. This field should almost always be set to disabled + * (0). Since resize algorithm activity is reported via stdout, it MUST be + * set to disabled (0) on Windows machines.\n + * The report function is not supported code, and can be expected to change + * between versions of the library. Use it at your own risk. */ hbool_t open_trace_file; + /**< Boolean field indicating whether the + * \ref H5AC_cache_config_t.trace_file_name "trace_file_name" + * field should be used to open a trace file for the cache.\n + * The trace file is a debugging feature that allows the capture + * of top level metadata cache requests for purposes of debugging + * and/or optimization. This field should normally be set to 0, as + * trace file collection imposes considerable overhead.\n + * This field should only be set to 1 when the + * \ref H5AC_cache_config_t.trace_file_name "trace_file_name" + * contains the full path of the desired trace file, and either + * there is no open trace file on the cache, or the + * \ref H5AC_cache_config_t.close_trace_file "close_trace_file" + * field is also 1.\n + * The trace file feature is unsupported unless used at the + * direction of The HDF Group. It is intended to allow The HDF + * Group to collect a trace of cache activity in cases of occult + * failures and/or poor performance seen in the field, so as to aid + * in reproduction in the lab. If you use it absent the direction + * of The HDF Group, you are on your own. */ + hbool_t close_trace_file; - char trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1]; + /**< Boolean field indicating whether the current trace file + *(if any) should be closed.\n + * See the above comments on the \ref H5AC_cache_config_t.open_trace_file + * "open_trace_file" field. This field should be set to 0 unless there is + * an open trace file on the cache that you wish to close.\n + * The trace file feature is unsupported unless used at the direction of + * The HDF Group. It is intended to allow The HDF Group to collect a trace + * of cache activity in cases of occult failures and/or poor performance + * seen in the field, so as to aid in reproduction in the lab. If you use + * it absent the direction of The HDF Group, you are on your own. */ + + char trace_file_name[H5AC__MAX_TRACE_FILE_NAME_LEN + 1]; + /**< Full path of the trace file to be opened if the + * \ref H5AC_cache_config_t.open_trace_file "open_trace_file" field is set + * to 1.\n + * In the parallel case, an ascii representation of the MPI rank of the + * process will be appended to the file name to yield a unique trace file + * name for each process.\n + * The length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN + * characters.\n + * The trace file feature is unsupported unless used at the direction of + * The HDF Group. It is intended to allow The HDF Group to collect a trace + * of cache activity in cases of occult failures and/or poor performance + * seen in the field, so as to aid in reproduction in the lab. If you use + * it absent the direction of The HDF Group, you are on your own. */ hbool_t evictions_enabled; + /**< A boolean flag indicating whether evictions from the metadata cache + * are enabled. This flag is initially set to enabled (1).\n + * In rare circumstances, the raw data throughput quirements may be so high + * that the user wishes to postpone metadata writes so as to reserve I/O + * throughput for raw data. The \p evictions_enabled field exists to allow + * this. However, this is an extreme step, and you have no business doing + * it unless you have read the User Guide section on metadata caching, and + * have considered all other options carefully.\n + * The \p evictions_enabled field may not be set to disabled (0) + * unless all adaptive cache resizing code is disabled via the + * \ref H5AC_cache_config_t.incr_mode "incr_mode", + * \ref H5AC_cache_config_t.flash_incr_mode "flash_incr_mode", + * \ref H5AC_cache_config_t.decr_mode "decr_mode" fields.\n + * When this flag is set to disabled (\c 0), the metadata cache will not + * attempt to evict entries to make space for new entries, and thus will + * grow without bound.\n + * Evictions will be re-enabled when this field is set back to \c 1. + * This should be done as soon as possible. */ hbool_t set_initial_size; - size_t initial_size; + /**< Boolean flag indicating whether the cache should be created + * with a user specified initial size. */ + + size_t initial_size; + /**< If \ref H5AC_cache_config_t.set_initial_size "set_initial_size" + * is set to 1, \p initial_size must contain he desired initial size in + * bytes. This value must lie in the closed interval + * [ \p min_size, \p max_size ]. (see below) */ double min_clean_fraction; + /**< This field specifies the minimum fraction of the cache + * that must be kept either clean or empty.\n + * The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to + * start in the serial case. In the parallel case, a larger value is needed + * -- see the overview of the metadata cache in the + * “Metadata Caching in HDF5” section of the -- <em>HDF5 User’s Guide</em> + * for details. */ size_t max_size; + /**< Upper bound (in bytes) on the range of values that the + * adaptive cache resize code can select as the maximum cache size. */ + size_t min_size; + /**< Lower bound (in bytes) on the range of values that the + * adaptive cache resize code can select as the mininum cache * size. */ long int epoch_length; + /**< Number of cache accesses between runs of the adaptive cache resize + * code. 50,000 is a good starting number. */ + //! <!-- [H5AC_cache_config_t_general_snip] --> /* size increase control fields: */ + //! <!-- [H5AC_cache_config_t_incr_snip] --> enum H5C_cache_incr_mode incr_mode; + /**< Enumerated value indicating the operational mode of the automatic + * cache size increase code. At present, only two values listed in + * #H5C_cache_incr_mode are legal. */ double lower_hr_threshold; + /**< Hit rate threshold used by the hit rate threshold cache size + * increment algorithm.\n + * When the hit rate over an epoch is below this threshold and the cache + * is full, the maximum size of the cache is multiplied by increment + * (below), and then clipped as necessary to stay within \p max_size, and + * possibly \p max_increment.\n + * This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good + * place to start. */ double increment; + /**< Factor by which the hit rate threshold cache size increment + * algorithm multiplies the current cache max size to obtain a tentative + * new cache size.\n + * The actual cache size increase will be clipped to satisfy the \p max_size + * specified in the general configuration, and possibly max_increment + * below.\n + * The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable + * value.\n + * If you set it to 1.0, you will effectively disable cache size increases. + */ hbool_t apply_max_increment; - size_t max_increment; + /**< Boolean flag indicating whether an upper limit should be applied to + * the size of cache size increases. */ + + size_t max_increment; + /**< Maximum number of bytes by which cache size can be increased in a + * single step -- if applicable. */ enum H5C_cache_flash_incr_mode flash_incr_mode; - double flash_multiple; - double flash_threshold; + /**< Enumerated value indicating the operational mode of the flash cache + * size increase code. At present, only two listed values in + * #H5C_cache_flash_incr_mode are legal.*/ + + double flash_multiple; + /**< The factor by which the size of the triggering entry / entry size + * increase is multiplied to obtain the initial cache size increment. This + * increment may be reduced to reflect existing free space in the cache and + * the \p max_size field above.\n + * The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good + * place to start.\n + * At present, this field must lie in the range [0.1, 10.0]. */ + + double flash_threshold; + /**< The factor by which the current maximum cache size is multiplied to + * obtain the minimum size entry / entry size increase which may trigger a + * flash cache size increase. \n + * At present, this value must lie in the range [0.1, 1.0]. */ + //! <!-- [H5AC_cache_config_t_incr_snip] --> /* size decrease control fields: */ + //! <!-- [H5AC_cache_config_t_decr_snip] --> enum H5C_cache_decr_mode decr_mode; + /**< Enumerated value indicating the operational mode of the tomatic + * cache size decrease code. At present, the values listed in + * #H5C_cache_decr_mode are legal.*/ double upper_hr_threshold; + /**< Hit rate threshold for the hit rate threshold and ageout with hit + * rate threshold cache size decrement algorithms.\n + * When \p decr_mode is #H5C_decr__threshold, and the hit rate over a given + * epoch exceeds the supplied threshold, the current maximum cache + * size is multiplied by decrement to obtain a tentative new (and smaller) + * maximum cache size.\n + * When \p decr_mode is #H5C_decr__age_out_with_threshold, there is + * no attempt to find and evict aged out entries unless the hit rate in + * the previous epoch exceeded the supplied threshold.\n + * This field must lie in the interval [0.0, 1.0].\n + * For #H5C_incr__threshold, .9995 or .99995 is a good place to start.\n + * For #H5C_decr__age_out_with_threshold, .999 might be more useful.*/ double decrement; + /**< In the hit rate threshold cache size decrease algorithm, this + * parameter contains the factor by which the current max cache size is + * multiplied to produce a tentative new cache size.\n + * The actual cache size decrease will be clipped to satisfy the + * \ref H5AC_cache_config_t.min_size "min_size" specified in the general + * configuration, and possibly \ref H5AC_cache_config_t.max_decrement + * "max_decrement".\n + * The parameter must be be in the interval [0.0, 1.0].\n + * If you set it to 1.0, you will effectively + * disable cache size decreases. 0.9 is a reasonable starting point. */ hbool_t apply_max_decrement; - size_t max_decrement; + /**< Boolean flag indicating ether an upper limit should be applied to + * the size of cache size decreases. */ + + size_t max_decrement; + /**< Maximum number of bytes by which the maximum cache size can be + * decreased in any single step -- if applicable.*/ int epochs_before_eviction; + /**< In the ageout based cache size reduction algorithms, this field + * contains the minimum number of epochs an entry must remain unaccessed in + * cache before the cache size reduction algorithm tries to evict it. 3 is a + * reasonable value. */ hbool_t apply_empty_reserve; - double empty_reserve; + /**< Boolean flag indicating whether the ageout based decrement + * algorithms will maintain a empty reserve when decreasing cache size. */ + + double empty_reserve; + /**< Empty reserve as a fraction maximum cache size if applicable.\n When + * so directed, the ageout based algorithms will not decrease the maximum + * cache size unless the empty reserve can be met.\n The parameter must lie + * in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to start. */ + //! <!-- [H5AC_cache_config_t_decr_snip] --> /* parallel configuration fields: */ + //! <!-- [H5AC_cache_config_t_parallel_snip] --> size_t dirty_bytes_threshold; - int metadata_write_strategy; - + /**< Threshold number of bytes of dirty metadata generation for + * triggering synchronizations of the metadata caches serving the target + * file in the parallel case.\n Synchronization occurs whenever the number + * of bytes of dirty metadata created since the last synchronization exceeds + * this limit.\n This field only applies to the parallel case. While it is + * ignored elsewhere, it can still draw a value out of bounds error.\n It + * must be consistant across all caches on any given file.\n By default, + * this field is set to 256 KB. It shouldn't be more than half the current + * max cache size times the min clean fraction. */ + + int metadata_write_strategy; + /**< Desired metadata write strategy. The valid values for this field + * are:\n #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies tha only + * process zero is allowed to write dirty metadata to disk.\n + * #H5AC_METADATA_WRITE_STRATEGY__DISTRIBUTED: Specifies that process zero + * still makes the decisions as to what entries should be flushed, but the + * actual flushes are distributed across the processes in the computation to + * the extent possible.\n The src/H5ACpublic.h include file in the HDF5 + * library has detailed information on each strategy. */ + //! <!-- [H5AC_cache_config_t_parallel_snip] --> } H5AC_cache_config_t; - -/**************************************************************************** - * - * structure H5AC_cache_image_config_t - * - * H5AC_cache_image_ctl_t is a public structure intended for use in public - * APIs. At least in its initial incarnation, it is a copy of struct - * H5C_cache_image_ctl_t. - * - * The fields of the structure are discussed individually below: - * - * version: Integer field containing the version number of this version - * of the H5C_image_ctl_t structure. Any instance of - * H5C_image_ctl_t passed to the cache must have a known - * version number, or an error will be flagged. - * - * generate_image: Boolean flag indicating whether a cache image should - * be created on file close. - * - * save_resize_status: Boolean flag indicating whether the cache image - * should include the adaptive cache resize configuration and status. - * Note that this field is ignored at present. - * - * entry_ageout: Integer field indicating the maximum number of - * times a prefetched entry can appear in subsequent cache images. - * This field exists to allow the user to avoid the buildup of - * infrequently used entries in long sequences of cache images. - * - * The value of this field must lie in the range - * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE (-1) to - * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX (100). - * - * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE means that no limit - * is imposed on number of times a prefeteched entry can appear - * in subsequent cache images. - * - * A value of 0 prevents prefetched entries from being included - * in cache images. - * - * Positive integers restrict prefetched entries to the specified - * number of appearances. - * - * Note that the number of subsequent cache images that a prefetched - * entry has appeared in is tracked in an 8 bit field. Thus, while - * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX can be increased from its - * current value, any value in excess of 255 will be the functional - * equivalent of H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE. - * - ****************************************************************************/ +//! <!-- [H5AC_cache_config_t_snip] --> #define H5AC__CURR_CACHE_IMAGE_CONFIG_VERSION 1 #define H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE -1 #define H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX 100 +//! <!-- [H5AC_cache_image_config_t_snip] --> +/** + * H5AC_cache_image_config_t is a public structure intended for use in public + * APIs. At least in its initial incarnation, it is a copy of \c struct \c + * H5C_cache_image_ctl_t. + */ + typedef struct H5AC_cache_image_config_t { - int version; + int version; + /**< Integer field containing the version number of this version of the \c + * H5C_image_ctl_t structure. Any instance of \c H5C_image_ctl_t passed + * to the cache must have a known version number, or an error will be + * flagged. + */ hbool_t generate_image; + /**< Boolean flag indicating whether a cache image should be created on file + * close. + */ hbool_t save_resize_status; - int entry_ageout; + /**< Boolean flag indicating whether the cache image should include the + * adaptive cache resize configuration and status. Note that this field + * is ignored at present. + */ + int entry_ageout; + /**< Integer field indicating the maximum number of times a + * prefetched entry can appear in subsequent cache images. This field + * exists to allow the user to avoid the buildup of infrequently used + * entries in long sequences of cache images. + * + * The value of this field must lie in the range \ref + * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE (-1) to \ref + * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX (100). + * + * \ref H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE means that no limit is + * imposed on number of times a prefeteched entry can appear in subsequent + * cache images. + * + * A value of 0 prevents prefetched entries from being included in cache + * images. + * + * Positive integers restrict prefetched entries to the specified number + * of appearances. + * + * Note that the number of subsequent cache images that a prefetched entry + * has appeared in is tracked in an 8 bit field. Thus, while \ref + * H5AC__CACHE_IMAGE__ENTRY_AGEOUT__MAX can be increased from its current + * value, any value in excess of 255 will be the functional equivalent of + * \ref H5AC__CACHE_IMAGE__ENTRY_AGEOUT__NONE. + */ } H5AC_cache_image_config_t; +//! <!-- [H5AC_cache_image_config_t_snip] --> + #ifdef __cplusplus } #endif diff --git a/src/H5Amodule.h b/src/H5Amodule.h index 45172bf..c89c93f 100644 --- a/src/H5Amodule.h +++ b/src/H5Amodule.h @@ -30,19 +30,39 @@ #define H5_MY_PKG_INIT YES /**\defgroup H5A H5A - * \brief Attribute Interface * - * \details The Attribute Interface, H5A, provides a mechanism for attaching - * additional information to a dataset, group, or named datatype. + * Use the functions in this module to manage HDF5 attributes. * - * Attributes are accessed by opening the object that they are - * attached to and are not independent objects. Typically an - * attribute is small in size and contains user metadata about the - * object that it is attached to. + * The Attribute Interface, H5A, provides a mechanism for attaching additional + * information to a dataset, group, or named datatype. * - * Attributes look similar to HDF5 datasets in that they have a - * datatype and dataspace. However, they do not support partial - * I/O operations and cannot be compressed or extended. + * Attributes are accessed by opening the object that they are attached to and + * are not independent objects. Typically an attribute is small in size and + * contains user metadata about the object that it is attached to. + * + * Attributes look similar to HDF5 datasets in that they have a datatype and + * dataspace. However, they do not support partial I/O operations and cannot be + * compressed or extended. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet H5A_examples.c create + * </td> + * <td> + * \snippet H5A_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet H5A_examples.c update + * </td> + * <td> + * \snippet H5A_examples.c delete + * </td> + * </tr> + * </table> * */ diff --git a/src/H5Apublic.h b/src/H5Apublic.h index 68d8a8a..2d58cdf 100644 --- a/src/H5Apublic.h +++ b/src/H5Apublic.h @@ -22,19 +22,40 @@ #include "H5Opublic.h" /* Object Headers */ #include "H5Tpublic.h" /* Datatypes */ -/* Information struct for attribute (for H5Aget_info/H5Aget_info_by_idx) */ -//! [H5A_info_t_snip] +//! <!-- [H5A_info_t_snip] --> +/** + * Information struct for H5Aget_info() / H5Aget_info_by_idx() + */ typedef struct { - hbool_t corder_valid; /* Indicate if creation order is valid */ - H5O_msg_crt_idx_t corder; /* Creation order */ - H5T_cset_t cset; /* Character set of attribute name */ - hsize_t data_size; /* Size of raw data */ + hbool_t corder_valid; /**< Indicate if creation order is valid */ + H5O_msg_crt_idx_t corder; /**< Creation order */ + H5T_cset_t cset; /**< Character set of attribute name */ + hsize_t data_size; /**< Size of raw data */ } H5A_info_t; -//! [H5A_info_t_snip] +//! <!-- [H5A_info_t_snip] --> -/* Typedef for H5Aiterate2() callbacks */ +//! <!-- [H5A_operator2_t_snip] --> +/** + * Typedef for H5Aiterate2() / H5Aiterate_by_name() callbacks + * \param[in] location_id The identifier for the group, dataset + * or named datatype being iterated over + * \param[in] attr_name The name of the current object attribute + * \param[in] ainfo The attribute’s info struct + * \param[in,out] op_data A pointer to the operator data passed in to + * H5Aiterate2() or H5Aiterate_by_name() + * \returns The return values from an operator are: + * \li Zero causes the iterator to continue, returning zero when + * all attributes have been processed. + * \li Positive causes the iterator to immediately return that + * positive value, indicating short-circuit success. The + * iterator can be restarted at the next attribute. + * \li Negative causes the iterator to immediately return that value, + * indicating failure. The iterator can be restarted at the next + * attribute. + */ typedef herr_t (*H5A_operator2_t)(hid_t location_id /*in*/, const char *attr_name /*in*/, const H5A_info_t *ainfo /*in*/, void *op_data /*in,out*/); +//! <!-- [H5A_operator2_t_snip] --> /********************/ /* Public Variables */ @@ -105,8 +126,8 @@ H5_DLL herr_t H5Aclose(hid_t attr_id); * The attribute identifier returned by this function must be released * with H5Aclose() resource leaks will develop. * - * \note The \p acpl and \p aapl parameters are currently not used; specify - * #H5P_DEFAULT. + * \note The \p aapl parameter is currently not used; specify #H5P_DEFAULT. + * * \note If \p loc_id is a file identifier, the attribute will be attached * that file’s root group. * @@ -117,6 +138,11 @@ H5_DLL herr_t H5Aclose(hid_t attr_id); */ H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Acreate} + */ H5_DLL hid_t H5Acreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t es_id); @@ -659,30 +685,12 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); * the value returned identifies the parameter to be operated on * in the next step of the iteration. * - * The #H5A_operator2_t prototype for the \p op parameter is a - * user defined function where: - * The operation receives the location identifier for the group or - * dataset being iterated over, \p location_id; the name of the - * current object attribute, \p attr_name; the attribute’s info - * struct, \p ainfo; and a pointer to the operator data passed - * into H5Aiterate2(), \p op_data. - * - * Valid return values from an operator and the resulting - * H5Aiterate2() and \p op behavior are as follows: - * - * \li Zero causes the iterator to continue, returning zero when - * all attributes have been processed. - * \li A positive value causes the iterator to immediately return - * that positive value, indicating short-circuit success. The - * iterator can be restarted at the next attribute, as - * indicated by the return value of \p idx. - * \li A negative value causes the iterator to immediately return - * that value, indicating failure. The iterator can be - * restarted at the next attribute, as indicated by the return - * value of \p idx. + * \p op is a user-defined function whose prototype is defined + * as follows: + * \snippet this H5A_operator2_t_snip + * \click4more * * \note This function is also available through the H5Aiterate() macro. - * \todo Add snippet for H5A_operator2_t * * \since 1.8.0 * @@ -751,13 +759,10 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord * the value returned identifies the parameter to be operated on in * the next step of the iteration. * - * The #H5A_operator2_t prototype for the \p op parameter is a - * user defined function where: - * The operation receives the location identifier for the group or - * dataset being iterated over, \p location_id; the name of the - * current object attribute, \p attr_name; the attribute’s info - * struct, \p ainfo; and a pointer to the operator data passed - * into H5Aiterate_by_name(), \p op_data. + * \p op is a user-defined function whose prototype is defined + * as follows: + * \snippet this H5A_operator2_t_snip + * \click4more * * Valid return values from an operator and the resulting * H5Aiterate_by_name() and \p op behavior are as follows: @@ -777,17 +782,21 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord * information regarding the properties of links required to access * the object, \p obj_name. * - * \todo Add snippet to show H5Aoperator2_t. * \since 1.8.0 * */ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, H5A_operator2_t op, void *op_data, hid_t lapl_id); -H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func, unsigned app_line, - hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id, - hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id, - hid_t es_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Acreate_by_name} + */ +H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func, unsigned app_line, + hid_t loc_id, const char *obj_name, const char *attr_name, hid_t type_id, + hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t lapl_id, + hid_t es_id); /*--------------------------------------------------------------------------*/ /** * \ingroup H5A @@ -819,6 +828,11 @@ H5_DLL hid_t H5Acreate_by_name_async(const char *app_file, const char *app_func * \see H5Aclose(), H5Acreate() */ H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Aopen} + */ H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id, const char *attr_name, hid_t aapl_id, hid_t es_id); /*--------------------------------------------------------------------------*/ @@ -868,6 +882,11 @@ H5_DLL hid_t H5Aopen_async(const char *app_file, const char *app_func, unsigned */ H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t aapl_id, hid_t lapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Aopen_by_idx} + */ H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *obj_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t aapl_id, hid_t lapl_id, hid_t es_id); @@ -914,6 +933,11 @@ H5_DLL hid_t H5Aopen_by_idx_async(const char *app_file, const char *app_func, un */ H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, hid_t lapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Aopen_by_name} + */ H5_DLL hid_t H5Aopen_by_name_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, hid_t lapl_id, hid_t es_id); @@ -967,6 +991,11 @@ H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf); * */ H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Aread} + */ H5_DLL herr_t H5Aread_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id, hid_t dtype_id, void *buf, hid_t es_id); /*--------------------------------------------------------------------------*/ @@ -1001,15 +1030,40 @@ H5_DLL herr_t H5Aread_async(const char *app_file, const char *app_func, unsigned * */ H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Awrite} + */ H5_DLL herr_t H5Awrite_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id, hid_t type_id, const void *buf, hid_t es_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Arename} + */ H5_DLL herr_t H5Arename_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *old_name, const char *new_name, hid_t es_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Arename_by_name} + */ H5_DLL herr_t H5Arename_by_name_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *obj_name, const char *old_attr_name, const char *new_attr_name, hid_t lapl_id, hid_t es_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Aexists} + */ H5_DLL herr_t H5Aexists_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id, const char *attr_name, hbool_t *exists, hid_t es_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Aexists_by_name} + */ H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *obj_name, const char *attr_name, hbool_t *exists, hid_t lapl_id, hid_t es_id); @@ -1038,6 +1092,11 @@ H5_DLL herr_t H5Aexists_by_name_async(const char *app_file, const char *app_func */ H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char *old_attr_name, const char *new_attr_name, hid_t lapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Aclose} + */ H5_DLL herr_t H5Aclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t attr_id, hid_t es_id); @@ -1085,9 +1144,28 @@ H5_DLL herr_t H5Aclose_async(const char *app_file, const char *app_func, unsigne /* Typedefs */ -/* Typedef for H5Aiterate1() callbacks */ +//! <!-- [H5A_operator1_t_snip] --> +/** + * \brief Typedef for H5Aiterate1() callbacks + * + * \param[in] location_id The identifier for the group, dataset + * or named datatype being iterated over + * \param[in] attr_name The name of the current object attribute + * \param[in,out] operator_data A pointer to the operator data passed in to + * H5Aiterate1() + * \returns The return values from an operator are: + * \li Zero causes the iterator to continue, returning zero when + * all attributes have been processed. + * \li Positive causes the iterator to immediately return that + * positive value, indicating short-circuit success. The + * iterator can be restarted at the next attribute. + * \li Negative causes the iterator to immediately return that value, + * indicating failure. The iterator can be restarted at the next + * attribute. + */ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_name /*in*/, void *operator_data /*in,out*/); +//! <!-- [H5A_operator1_t_snip] --> /* Function prototypes */ /* --------------------------------------------------------------------------*/ @@ -1163,8 +1241,6 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id); * * \brief Calls a user’s function for each attribute on an object * - * \todo make prototype parameter match function (idx vs attr_num) - * * \loc_id * \param[in,out] idx Starting (in) and ending (out) attribute index * \param[in] op User's function to pass each attribute to @@ -1186,29 +1262,12 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id); * \p op, is returned in \p idx. If \p idx is the null pointer, * then all attributes are processed. * - * The prototype for #H5A_operator1_t is a user defined function - * where: - * The operation receives the identifier for the group, dataset - * or named datatype being iterated over, \p loc_id, the name of - * the current object attribute, \p attr_name, and the pointer to - * the operator data passed in to H5Aiterate1(), \p op_data. - * - * The return values from an operator are: - * - * \li Zero causes the iterator to continue, returning zero when - * all attributes have been processed. - * \li Positive causes the iterator to immediately return that - * positive value, indicating short-circuit success. The - * iterator can be restarted at the next attribute. - * \li Negative causes the iterator to immediately return that value, - * indicating failure. The iterator can be restarted at the next - * attribute. - * - * \todo Add snippet to show H5A_operator1_t. + * \p op is a user-defined function whose prototype is defined as follows: + * \snippet this H5A_operator1_t_snip + * \click4more * * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1() * and deprecated in this release. - * * \since 1.0.0 * */ diff --git a/src/H5Cpublic.h b/src/H5Cpublic.h index 0e6fb84..79ece10 100644 --- a/src/H5Cpublic.h +++ b/src/H5Cpublic.h @@ -31,15 +31,34 @@ extern "C" { #endif -enum H5C_cache_incr_mode { H5C_incr__off, H5C_incr__threshold }; +enum H5C_cache_incr_mode { + H5C_incr__off, + /**<Automatic cache size increase is disabled, and the remaining increment fields are ignored.*/ -enum H5C_cache_flash_incr_mode { H5C_flash_incr__off, H5C_flash_incr__add_space }; + H5C_incr__threshold + /**<Automatic cache size increase is enabled using the hit rate threshold algorithm.*/ +}; + +enum H5C_cache_flash_incr_mode { + H5C_flash_incr__off, + /**<Flash cache size increase is disabled.*/ + + H5C_flash_incr__add_space + /**<Flash cache size increase is enabled using the add space algorithm.*/ +}; enum H5C_cache_decr_mode { H5C_decr__off, + /**<Automatic cache size decrease is disabled.*/ + H5C_decr__threshold, + /**<Automatic cache size decrease is enabled using the hit rate threshold algorithm.*/ + H5C_decr__age_out, + /**<Automatic cache size decrease is enabled using the ageout algorithm. */ + H5C_decr__age_out_with_threshold + /**<Automatic cache size decrease is enabled using the ageout with hit rate threshold algorithm.*/ }; #ifdef __cplusplus diff --git a/src/H5Dmodule.h b/src/H5Dmodule.h index 292b624..595c714 100644 --- a/src/H5Dmodule.h +++ b/src/H5Dmodule.h @@ -29,15 +29,37 @@ #define H5_MY_PKG_ERR H5E_DATASET #define H5_MY_PKG_INIT YES -/** - * \defgroup H5D H5D - * \brief Group Interface - * \details The HDF5 Dataset Interface, H5D, provides a mechanism for managing - * HDF5 datasets, including the transfer of data between memory and - * disk and the description of dataset properties. +/**\defgroup H5D H5D + * + * Use the functions in this module to manage HDF5 datasets, including the + * transfer of data between memory and disk and the description of dataset + * properties. Datasets are used by other HDF5 APIs and referenced either by + * name or by a handle. Such handles can be obtained by either creating or + * opening the dataset. + * + * Typical stages in the HDF5 dataset life cycle are shown below in introductory + * examples. + * + * <table> + * <tr><th>Create</th><th>Read</th></tr> + * <tr valign="top"> + * <td> + * \snippet H5D_examples.c create + * </td> + * <td> + * \snippet H5D_examples.c read + * </td> + * <tr><th>Update</th><th>Delete</th></tr> + * <tr valign="top"> + * <td> + * \snippet H5D_examples.c update + * </td> + * <td> + * \snippet H5D_examples.c delete + * </td> + * </tr> + * </table> * - * A Dataset is used by other HDF5 APIs, either by name or by a handle, - * which is obtained by either creating or opening the dataset. */ #endif /* H5Dmodule_H */ diff --git a/src/H5Dpublic.h b/src/H5Dpublic.h index ce4ce84..608025a 100644 --- a/src/H5Dpublic.h +++ b/src/H5Dpublic.h @@ -39,30 +39,41 @@ /* Public Typedefs */ /*******************/ -/* Values for the H5D_LAYOUT property */ +//! <!-- [H5D_layout_t_snip] --> +/** + * Values for the H5D_LAYOUT property + */ typedef enum H5D_layout_t { H5D_LAYOUT_ERROR = -1, - H5D_COMPACT = 0, /*raw data is very small */ - H5D_CONTIGUOUS = 1, /*the default */ - H5D_CHUNKED = 2, /*slow and fancy */ - H5D_VIRTUAL = 3, /*actual data is stored in other datasets */ - H5D_NLAYOUTS = 4 /*this one must be last! */ + H5D_COMPACT = 0, /**< raw data is very small */ + H5D_CONTIGUOUS = 1, /**< the default */ + H5D_CHUNKED = 2, /**< slow and fancy */ + H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */ + H5D_NLAYOUTS = 4 /**< this one must be last! */ } H5D_layout_t; +//! <!-- [H5D_layout_t_snip] --> -/* Types of chunk index data structures */ +//! <!-- [H5D_chunk_index_t_snip] --> +/** + * Types of chunk index data structures + */ typedef enum H5D_chunk_index_t { - H5D_CHUNK_IDX_BTREE = 0, /* v1 B-tree index (default) */ + H5D_CHUNK_IDX_BTREE = 0, /**< v1 B-tree index (default) */ H5D_CHUNK_IDX_SINGLE = - 1, /* Single Chunk index (cur dims[]=max dims[]=chunk dims[]; filtered & non-filtered) */ - H5D_CHUNK_IDX_NONE = 2, /* Implicit: No Index (H5D_ALLOC_TIME_EARLY, non-filtered, fixed dims) */ - H5D_CHUNK_IDX_FARRAY = 3, /* Fixed array (for 0 unlimited dims) */ - H5D_CHUNK_IDX_EARRAY = 4, /* Extensible array (for 1 unlimited dim) */ - H5D_CHUNK_IDX_BT2 = 5, /* v2 B-tree index (for >1 unlimited dims) */ - H5D_CHUNK_IDX_NTYPES /* This one must be last! */ + 1, /**< Single Chunk index (cur dims[]=max dims[]=chunk dims[]; filtered & non-filtered) */ + H5D_CHUNK_IDX_NONE = 2, /**< Implicit: No Index (#H5D_ALLOC_TIME_EARLY, non-filtered, fixed dims) */ + H5D_CHUNK_IDX_FARRAY = 3, /**< Fixed array (for 0 unlimited dims) */ + H5D_CHUNK_IDX_EARRAY = 4, /**< Extensible array (for 1 unlimited dim) */ + H5D_CHUNK_IDX_BT2 = 5, /**< v2 B-tree index (for >1 unlimited dims) */ + H5D_CHUNK_IDX_NTYPES /**< This one must be last! */ } H5D_chunk_index_t; +//! <!-- [H5D_chunk_index_t_snip] --> -/* Values for the space allocation time property */ +//! <!-- [H5D_alloc_time_t_snip] --> +/** + * Values for the space allocation time property + */ typedef enum H5D_alloc_time_t { H5D_ALLOC_TIME_ERROR = -1, H5D_ALLOC_TIME_DEFAULT = 0, @@ -70,57 +81,84 @@ typedef enum H5D_alloc_time_t { H5D_ALLOC_TIME_LATE = 2, H5D_ALLOC_TIME_INCR = 3 } H5D_alloc_time_t; +//! <!-- [H5D_alloc_time_t_snip] --> -/* Values for the status of space allocation */ +//! <!-- [H5D_space_status_t_snip] --> +/** + * Values for the status of space allocation + */ typedef enum H5D_space_status_t { H5D_SPACE_STATUS_ERROR = -1, H5D_SPACE_STATUS_NOT_ALLOCATED = 0, H5D_SPACE_STATUS_PART_ALLOCATED = 1, H5D_SPACE_STATUS_ALLOCATED = 2 } H5D_space_status_t; +//! <!-- [H5D_space_status_t_snip] --> -/* Values for time of writing fill value property */ +//! <!-- [H5D_fill_time_t_snip] --> +/** + * Values for time of writing fill value property + */ typedef enum H5D_fill_time_t { H5D_FILL_TIME_ERROR = -1, H5D_FILL_TIME_ALLOC = 0, H5D_FILL_TIME_NEVER = 1, H5D_FILL_TIME_IFSET = 2 } H5D_fill_time_t; +//! <!-- [H5D_fill_time_t_snip] --> -/* Values for fill value status */ +//! <!-- [H5D_fill_value_t_snip] --> +/** + * Values for fill value status + */ typedef enum H5D_fill_value_t { H5D_FILL_VALUE_ERROR = -1, H5D_FILL_VALUE_UNDEFINED = 0, H5D_FILL_VALUE_DEFAULT = 1, H5D_FILL_VALUE_USER_DEFINED = 2 } H5D_fill_value_t; +//! <!-- [H5D_fill_value_t_snip] --> -/* Values for VDS bounds option */ +//! <!-- [H5D_vds_view_t_snip] --> +/** + * Values for VDS bounds option + */ typedef enum H5D_vds_view_t { H5D_VDS_ERROR = -1, H5D_VDS_FIRST_MISSING = 0, H5D_VDS_LAST_AVAILABLE = 1 } H5D_vds_view_t; +//! <!-- [H5D_vds_view_t_snip] --> -/* Callback for H5Pset_append_flush() in a dataset access property list */ +//! <!-- [H5D_append_cb_t_snip] --> +/** + * Callback for H5Pset_append_flush() in a dataset access property list + */ typedef herr_t (*H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *op_data); +//! <!-- [H5D_append_cb_t_snip] --> -/** Define the operator function pointer for H5Diterate() */ -//! [H5D_operator_t_snip] +//! <!-- [H5D_operator_t_snip] --> +/** + * Define the operator function pointer for H5Diterate() + */ typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const hsize_t *point, void *operator_data); -//! [H5D_operator_t_snip] +//! <!-- [H5D_operator_t_snip] --> -/** Define the operator function pointer for H5Dscatter() */ -//! [H5D_scatter_func_t_snip] +//! <!-- [H5D_scatter_func_t_snip] --> +/** + * Define the operator function pointer for H5Dscatter() + */ typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_buf_bytes_used /*out*/, void *op_data); -//! [H5D_scatter_func_t_snip] +//! <!-- [H5D_scatter_func_t_snip] --> -/** Define the operator function pointer for H5Dgather() */ -//! [H5D_gather_func_t_snip] +//! <!-- [H5D_gather_func_t_snip] --> +/** + * Define the operator function pointer for H5Dgather() + */ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_used, void *op_data); -//! [H5D_gather_func_t_snip] +//! <!-- [H5D_gather_func_t_snip] --> /********************/ /* Public Variables */ @@ -203,26 +241,8 @@ H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t spa /** * -------------------------------------------------------------------------- - * \ingroup H5D - * - * \brief Asynchronous version of H5Dcreate2() - * - * \app_file - * \app_func - * \app_line - * \fgdta_loc_id - * \param[in] name Name of the dataset to create - * \type_id - * \space_id - * \lcpl_id - * \dcpl_id - * \dapl_id - * \es_id - * - * \return \hid_t{dataset} - * - * \see H5Dcreate2() - * + * \ingroup ASYNC + * \async_variant_of{H5Dcreate} */ H5_DLL hid_t H5Dcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, hid_t dcpl_id, @@ -325,22 +345,8 @@ H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id); /** * -------------------------------------------------------------------------- - * \ingroup H5D - * - * \brief Asynchronous version of H5Dopen2() - * - * \app_file - * \app_func - * \app_line - * \fgdta_loc_id - * \param[in] name Name of the dataset to open - * \dapl_id - * \es_id - * - * \return \hid_t{dataset} - * - * \see H5Dopen2() - * + * \ingroup ASYNC + * \async_variant_of{H5Dopen} */ H5_DLL hid_t H5Dopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t dapl_id, hid_t es_id); @@ -370,24 +376,17 @@ H5_DLL hid_t H5Dget_space(hid_t dset_id); /** * -------------------------------------------------------------------------- - * \ingroup H5D - * - * \brief Asynchronous version of H5Dget_space() - * - * \app_file - * \app_func - * \app_line - * \dset_id - * \es_id - * - * \return \hid_t{dataspace} - * - * \see H5Dget_space() - * + * \ingroup ASYNC + * \async_variant_of{H5Dget_space} */ H5_DLL hid_t H5Dget_space_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, hid_t es_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * \todo Document this function! + */ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation); /** @@ -614,7 +613,7 @@ H5_DLL herr_t H5Dget_num_chunks(hid_t dset_id, hid_t fspace_id, hsize_t *nchunks * using the coordinates specified by \p offset. * * If the queried chunk does not exist in the file, \p size will - * be set to 0, \p addr to #HADDR_UNDEF, and the buffer \p + * be set to 0, \p addr to \c HADDR_UNDEF, and the buffer \p * filter_mask will not be modified. * * \p offset is a pointer to a one-dimensional array with a size @@ -649,7 +648,7 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u * specified by the index index. The chunk belongs to a set of * chunks in the selection specified by fspace_id. If the queried * chunk does not exist in the file, the size will be set to 0 and - * address to #HADDR_UNDEF. The value pointed to by filter_mask will + * address to \c HADDR_UNDEF. The value pointed to by filter_mask will * not be modified. NULL can be passed in for any \p out parameters. * * \p chk_idx is the chunk index in the selection. Index value @@ -684,7 +683,7 @@ H5_DLL herr_t H5Dget_chunk_info(hid_t dset_id, hid_t fspace_id, hsize_t chk_idx, * * \dset_id * - * \return Returns the offset in bytes; otherwise, returns #HADDR_UNDEF, + * \return Returns the offset in bytes; otherwise, returns \c HADDR_UNDEF, * a negative value. * * \details H5Dget_offset() returns the address in the file of @@ -795,25 +794,8 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_ /** * -------------------------------------------------------------------------- - * \ingroup H5D - * - * \brief Asynchronous version of H5Dread() - * - * \app_file - * \app_func - * \app_line - * \dset_id Identifier of the dataset to read from - * \param[in] mem_type_id Identifier of the memory datatype - * \param[in] mem_space_id Identifier of the memory dataspace - * \param[in] file_space_id Identifier of the dataset's dataspace in the file - * \param[in] dxpl_id Identifier of a transfer property list - * \param[out] buf Buffer to receive data read from file - * \es_id - * - * \return \herr_t - * - * \see H5Dread() - * + * \ingroup ASYNC + * \async_variant_of{H5Dread} */ H5_DLL herr_t H5Dread_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, @@ -932,25 +914,8 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid /** * -------------------------------------------------------------------------- - * \ingroup H5D - * - * \brief Asynchronous version of H5Dwrite() - * - * \app_file - * \app_func - * \app_line - * \param[in] dset_id Identifier of the dataset to read from - * \param[in] mem_type_id Identifier of the memory datatype - * \param[in] mem_space_id Identifier of the memory dataspace - * \param[in] file_space_id Identifier of the dataset's dataspace in the file - * \dxpl_id - * \param[out] buf Buffer with data to be written to the file - * \es_id - * - * \return \herr_t - * - * \see H5Dwrite() - * + * \ingroup ASYNC + * \async_variant_of{H5Dwrite} */ H5_DLL herr_t H5Dwrite_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, @@ -1292,22 +1257,8 @@ H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]); /** * -------------------------------------------------------------------------- - * \ingroup H5D - * - * \brief Asynchronous version of H5Dset_extent() - * - * \app_file - * \app_func - * \app_line - * \dset_id - * \param[in] size[] Array containing the new magnitude of each dimension - * of the dataset - * \es_id - * - * \return \herr_t - * - * \see H5Dset_extent() - * + * \ingroup ASYNC + * \async_variant_of{H5Dset_extent} */ H5_DLL herr_t H5Dset_extent_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, const hsize_t size[], hid_t es_id); @@ -1536,20 +1487,8 @@ H5_DLL herr_t H5Dclose(hid_t dset_id); /** * -------------------------------------------------------------------------- - * \ingroup H5D - * - * \brief Asynchronous version of H5Dclose() - * - * \app_file - * \app_func - * \app_line - * \dset_id - * \es_id - * - * \return \herr_t - * - * \see H5Dclose() - * + * \ingroup ASYNC + * \async_variant_of{H5Dclose} */ H5_DLL herr_t H5Dclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t dset_id, hid_t es_id); @@ -1608,9 +1547,181 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); /* Typedefs */ /* Function prototypes */ -H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id); -H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Creates a dataset at the specified location + * + * \fgdta_loc_id + * \param[in] name Name of the dataset to create + * \type_id + * \space_id + * \dcpl_id + * + * \return \hid_t{dataset} + * + * \deprecated This function is deprecated in favor of the function H5Dcreate2() + * or the macro H5Dcreate(). + * + * \details H5Dcreate1() creates a data set with a name, \p name, in the + * location specified by the identifier \p loc_id. \p loc_id may be a + * file, group, dataset, named datatype or attribute. If an attribute, + * dataset, or named datatype is specified for \p loc_id then the + * dataset will be created at the location where the attribute, + * dataset, or named datatype is attached. + * + * \p name can be a relative path based at \p loc_id or an absolute + * path from the root of the file. Use of this function requires that + * any intermediate groups specified in the path already exist. + * + * The dataset’s datatype and dataspace are specified by \p type_id and + * \p space_id, respectively. These are the datatype and dataspace of + * the dataset as it will exist in the file, which may differ from the + * datatype and dataspace in application memory. + * + * Names within a group are unique: H5Dcreate1() will return an error + * if a link with the name specified in name already exists at the + * location specified in \p loc_id. + * + * As is the case for any object in a group, the length of a dataset + * name is not limited. + * + * \p dcpl_id is an #H5P_DATASET_CREATE property list created with \p + * H5reate1() and initialized with various property list functions + * described in Property List Interface. + * + * H5Dcreate() and H5Dcreate_anon() return an error if the dataset’s + * datatype includes a variable-length (VL) datatype and the fill value + * is undefined, i.e., set to \c NULL in the dataset creation property + * list. Such a VL datatype may be directly included, indirectly + * included as part of a compound or array datatype, or indirectly + * included as part of a nested compound or array datatype. + * + * H5Dcreate() and H5Dcreate_anon() return a dataset identifier for + * success or a negative value for failure. The dataset identifier + * should eventually be closed by calling H5Dclose() to release + * resources it uses. + * + * See H5Dcreate_anon() for discussion of the differences between + * H5Dcreate() and H5Dcreate_anon(). + * + * The HDF5 library provides flexible means of specifying a fill value, + * of specifying when space will be allocated for a dataset, and of + * specifying when fill values will be written to a dataset. + * + * \version 1.8.0 Function H5Dcreate() renamed to H5Dcreate1() and deprecated in this release. + * \since 1.0.0 + * + * \see H5Dopen2(), H5Dclose(), H5Tset_size() + * + */ +H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t dcpl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Opens an existing dataset + * + * \fgdta_loc_id + * \param[in] name Name of the dataset to access + * + * \return \hid_t{dataset} + * + * \deprecated This function is deprecated in favor of the function H5Dopen2() + * or the macro H5Dopen(). + * + * \details H5Dopen1() opens an existing dataset for access at the location + * specified by \p loc_id. \p loc_id may be a file, group, dataset, + * named datatype or attribute. If an attribute, dataset, or named + * datatype is specified for loc_id then the dataset will be opened at + * the location where the attribute, dataset, or named datatype is + * attached. name is a dataset name and is used to identify the dataset + * in the file. + * + * A dataset opened with this function should be closed with H5Dclose() + * when the dataset is no longer needed so that resource leaks will not + * develop. + * + * \version 1.8.0 Function H5Dopen() renamed to H5Dopen1() and deprecated in this release. + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Extends a dataset + * + * \dset_id + * \param[in] size Array containing the new size of each dimension + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function H5Dset_extent(). + * + * \details H5Dextend() verifies that the dataset is at least of size \p size, + * extending it if necessary. The dimensionality of size is the same as + * that of the dataspace of the dataset being changed. + * + * This function can be applied to the following datasets: + * \li Any dataset with unlimited dimensions + * \li A dataset with fixed dimensions if the current dimension sizes + * are less than the maximum sizes set with \c maxdims + * (see H5Screate_simple()) + * + * Space on disk is immediately allocated for the new dataset extent if + * the dataset’s space allocation time is set to + * #H5D_ALLOC_TIME_EARLY. Fill values will be written to the dataset if + * the dataset’s fill time is set to #H5D_FILL_TIME_IFSET or + * #H5D_FILL_TIME_ALLOC. (See H5Pset_fill_time() and + * H5Pset_alloc_time().) + * + * This function ensures that the dataset dimensions are of at least + * the sizes specified in size. The function H5Dset_extent() must be + * used if the dataset dimension sizes are are to be reduced. + * + * \version 1.8.0 Function Function deprecated in this release. Parameter size + * syntax changed to \Code{const hsize_t size[]} in this release. + * + */ H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Reclaims variable-length (VL) datatype memory buffers + * + * \type_id + * \space_id + * \dxpl_id + * \param[in] buf Pointer to the buffer to be reclaimed + * + * \return \herr_t + * + * \deprecated This function has been deprecated in HDF5-1.12 in favor of the + * function H5Treclaim(). + * + * \details H5Dvlen_reclaim() reclaims memory buffers created to store VL + * datatypes. + * + * The \p type_id must be the datatype stored in the buffer. The \p + * space_id describes the selection for the memory buffer to free the + * VL datatypes within. The \p dxpl_id is the dataset transfer property + * list which was used for the I/O transfer to create the buffer. And + * \p buf is the pointer to the buffer to be reclaimed. + * + * The VL structures (\ref hvl_t) in the user's buffer are modified to + * zero out the VL information after the memory has been reclaimed. + * + * If nested VL datatypes were used to create the buffer, this routine + * frees them from the bottom up, releasing all the memory without + * creating memory leaks. + * + * \version 1.12.0 Routine was deprecated + * + */ H5_DLL herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5ESmodule.h b/src/H5ESmodule.h index ea9fd7a..cbc812e 100644 --- a/src/H5ESmodule.h +++ b/src/H5ESmodule.h @@ -29,4 +29,37 @@ #define H5_MY_PKG_ERR H5E_EVENTSET #define H5_MY_PKG_INIT YES +/** + * \defgroup H5ES H5ES + * \brief Event Set Interface + * + * \details \Bold{This interface can be only used with the HDF5 VOL connectors that + * enable the asynchronous feature in HDF5.} The native HDF5 library has + * only synchronous operations. + * + * HDF5 VOL connectors with support for asynchronous operations: + * - ASYNC + * - DAOS + * + * \par Example: + * \code + * fid = H5Fopen(..); + * gid = H5Gopen(fid, ..); //Starts when H5Fopen completes + * did = H5Dopen(gid, ..); //Starts when H5Gopen completes + * + * es_id = H5EScreate(); // Create event set for tracking async operations + * status = H5Dwrite_async(did, .., es_id); //Asynchronous, starts when H5Dopen completes, + * // may run concurrently with other H5Dwrite_async + * // in event set. + * status = H5Dwrite_async(did, .., es_id); //Asynchronous, starts when H5Dopen completes, + * // may run concurrently with other H5Dwrite_async + * // in event set.... + * <other user code> + * ... + * H5ESwait(es_id); // Wait for operations in event set to complete, buffers + * // used for H5Dwrite_async must only be changed after wait + * // returns. + * \endcode + */ + #endif /* H5ESmodule_H */ diff --git a/src/H5ESpublic.h b/src/H5ESpublic.h index 752218b..a7c2e58 100644 --- a/src/H5ESpublic.h +++ b/src/H5ESpublic.h @@ -47,20 +47,24 @@ typedef enum H5ES_status_t { H5ES_STATUS_FAIL /* An operation has completed, but failed */ } H5ES_status_t; -/* Information about failed operations in event set */ +//! <!-- [H5ES_err_info_t_snip] --> +/** + * Information about failed operations in event set + */ typedef struct H5ES_err_info_t { /* Operation info */ - char * api_name; /* Name of HDF5 API routine called */ - char * api_args; /* "Argument string" for arguments to HDF5 API routine called */ - char * app_file_name; /* Name of source file where the HDF5 API routine was called */ - char * app_func_name; /* Name of function where the HDF5 API routine was called */ - unsigned app_line_num; /* Line # of source file where the HDF5 API routine was called */ - uint64_t op_ins_count; /* Counter of operation's insertion into event set */ - uint64_t op_ins_ts; /* Timestamp for when the operation was inserted into the event set */ + char * api_name; /**< Name of HDF5 API routine called */ + char * api_args; /**< "Argument string" for arguments to HDF5 API routine called */ + char * app_file_name; /**< Name of source file where the HDF5 API routine was called */ + char * app_func_name; /**< Name of function where the HDF5 API routine was called */ + unsigned app_line_num; /**< Line # of source file where the HDF5 API routine was called */ + uint64_t op_ins_count; /**< Counter of operation's insertion into event set */ + uint64_t op_ins_ts; /**< Timestamp for when the operation was inserted into the event set */ /* Error info */ - hid_t err_stack_id; /* ID for error stack from failed operation */ + hid_t err_stack_id; /**< ID for error stack from failed operation */ } H5ES_err_info_t; +//! <!-- [H5ES_err_info_t_snip] --> /* H5ES_op_info_t: @@ -119,14 +123,157 @@ How to Trace Async Operations? extern "C" { #endif -H5_DLL hid_t H5EScreate(void); +/** + * \ingroup H5ES + * + * \brief Creates an event set + * + * \returns \hid_ti{event set} + * + * \details H5EScreate() creates a new event set and returns a corresponding + * event set identifier. + * + * \since 1.13.0 + * + */ +H5_DLL hid_t H5EScreate(void); + +/** + * \ingroup H5ES + * + * \brief Waits for operations in event set to complete + * + * \es_id + * \param[in] timeout Total time in nanoseconds to wait for all operations in + * the event set to complete + * \param[out] num_in_progress The number of operations still in progress + * \param[out] err_occurred Flag if an operation in the event set failed + * \returns \herr_t + * + * \details H5ESwait() waits for operations in an event set \p es_id to wait + * with \p timeout. + * + * Timeout value is in nanoseconds, and is for the H5ESwait() call and + * not for each individual operation in the event set. For example, if + * "10" is passed as a timeout value and the event set waited 4 + * nanoseconds for the first operation to complete, the remaining + * operations would be allowed to wait for at most 6 nanoseconds more, + * i.e., the timeout value used across all operations in the event set + * until it reaches 0, then any remaining operations are only checked + * for completion, not waited on. + * + * This call will stop waiting on operations and will return + * immediately if an operation fails. If a failure occurs, the value + * returned for the number of operations in progress may be inaccurate. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5ESwait(hid_t es_id, uint64_t timeout, size_t *num_in_progress, hbool_t *err_occurred); + +/** + * \ingroup H5ES + * + * \brief Retrieves number of events in an event set + * + * \es_id + * \param[out] count The number of events in the event set + * \returns \herr_t + * + * \details H5ESget_count() retrieves number of events in an event set specified + * by \p es_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5ESget_count(hid_t es_id, size_t *count); + +/** + * \ingroup H5ES + * + * \todo Fill in the blanks! + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5ESget_op_counter(hid_t es_id, uint64_t *counter); + +/** + * \ingroup H5ES + * + * \brief Checks for failed operations + * + * \es_id + * \param[out] err_occurred Status indicating if error is present in the event + * set + * \returns \herr_t + * + * \details H5ESget_err_status() checks if event set specified by es_id has + * failed operations. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5ESget_err_status(hid_t es_id, hbool_t *err_occurred); + +/** + * \ingroup H5ES + * + * \brief Retrieves the number of failed operations + * + * \es_id + * \param[out] num_errs Number of errors + * \returns \herr_t + * + * \details H5ESget_err_count() retrieves the number of failed operations in an + * event set specified by \p es_id. + * + * The function does not wait for active operations to complete, so + * count may not include all failures. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5ESget_err_count(hid_t es_id, size_t *num_errs); + +/** + * \ingroup H5ES + * + * \brief Retrieves information about failed operations + * + * \es_id + * \param[in] num_err_info The number of elements in \p err_info array + * \param[out] err_info Array of structures + * \param[out] err_cleared Number of cleared errors + * \returns \herr_t + * + * \details H5ESget_err_info() retrieves information about failed operations in + * an event set specified by \p es_id. The strings retrieved for each + * error info must be released by calling H5free_memory(). + * + * Below is the description of the \ref H5ES_err_info_t structure: + * \snippet this H5ES_err_info_t_snip + * \click4more + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5ESget_err_info(hid_t es_id, size_t num_err_info, H5ES_err_info_t err_info[], size_t *err_cleared); + +/** + * \ingroup H5ES + * + * \brief Terminates access to an event set + * + * \es_id + * \returns \herr_t + * + * \details H5ESclose() terminates access to an event set specified by \p es_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5ESclose(hid_t es_id); #ifdef __cplusplus diff --git a/src/H5Emodule.h b/src/H5Emodule.h index 1670c03..43d5d36 100644 --- a/src/H5Emodule.h +++ b/src/H5Emodule.h @@ -29,4 +29,33 @@ #define H5_MY_PKG_ERR H5E_ERROR #define H5_MY_PKG_INIT YES +/** + * \defgroup H5E H5E + * \brief Error Handling Interface + * + * \details The Error interface provides error handling in the form of a stack. + * The \Code{FUNC_ENTER} macro clears the error stack whenever an + * interface function is entered. When an error is detected, an entry + * is pushed onto the stack. As the functions unwind, additional + * entries are pushed onto the stack. The API function will return some + * indication that an error occurred and the application can print the + * error stack. + * + * Certain API functions in the \c H5E package, such as H5Eprint1(), do + * not clear the error stack. Otherwise, any function which does not + * have an underscore immediately after the package name will clear the + * error stack. For instance, H5Fopen() clears the error stack while + * \Code{H5F_open} does not. + * + * An error stack has a fixed maximum size. If this size is exceeded + * then the stack will be truncated and only the inner-most functions + * will have entries on the stack. This is expected to be a rare + * condition. + * + * Each thread has its own error stack, but since multi-threading has + * not been added to the library yet, this package maintains a single + * error stack. The error stack is statically allocated to reduce the + * complexity of handling errors within the \c H5E package. + */ + #endif /* H5Emodule_H */ diff --git a/src/H5Epublic.h b/src/H5Epublic.h index a2554d5..20a2107 100644 --- a/src/H5Epublic.h +++ b/src/H5Epublic.h @@ -26,18 +26,29 @@ /* Value for the default error stack */ #define H5E_DEFAULT (hid_t)0 -/* Different kinds of error information */ +/** + * Different kinds of error information + */ typedef enum H5E_type_t { H5E_MAJOR, H5E_MINOR } H5E_type_t; -/* Information about an error; element of error stack */ +/** + * Information about an error; element of error stack + */ typedef struct H5E_error2_t { - hid_t cls_id; /*class ID */ - hid_t maj_num; /*major error ID */ - hid_t min_num; /*minor error number */ - unsigned line; /*line in file where error occurs */ - const char *func_name; /*function in which error occurred */ - const char *file_name; /*file in which error occurred */ - const char *desc; /*optional supplied description */ + hid_t cls_id; + /**< Class ID */ + hid_t maj_num; + /**< Major error ID */ + hid_t min_num; + /**< Minor error number */ + unsigned line; + /**< Line in file where error occurs */ + const char *func_name; + /**< Function in which error occurred */ + const char *file_name; + /**< File in which error occurred */ + const char *desc; + /**< Optional supplied description */ } H5E_error2_t; /* When this header is included from a private header, don't make calls to H5open() */ @@ -138,10 +149,12 @@ H5_DLLVAR hid_t H5E_ERR_CLS_g; goto label; \ } -/* Error stack traversal direction */ +/** + * Error stack traversal direction + */ typedef enum H5E_direction_t { - H5E_WALK_UPWARD = 0, /*begin deep, end at API function */ - H5E_WALK_DOWNWARD = 1 /*begin at API function, end deep */ + H5E_WALK_UPWARD = 0, /**< begin w/ most specific error, end at API function */ + H5E_WALK_DOWNWARD = 1 /**< begin at API function, end w/ most specific error */ } H5E_direction_t; #ifdef __cplusplus @@ -149,30 +162,498 @@ extern "C" { #endif /* Error stack traversal callback function pointers */ +//! <!-- [H5E_walk2_t_snip] --> +/** + * \brief Callback function for H5Ewalk2() + * + * \param[in] n Indexed error position in the stack + * \param[in] err_desc Pointer to a data structure describing the error + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_walk2_t)(unsigned n, const H5E_error2_t *err_desc, void *client_data); +//! <!-- [H5E_walk2_t_snip] --> + +//! <!-- [H5E_auto2_t_snip] --> +/** + * \brief Callback function for H5Eset_auto2() + * + * \estack_id{estack} + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_auto2_t)(hid_t estack, void *client_data); +//! <!-- [H5E_auto2_t_snip] --> /* Public API functions */ -H5_DLL hid_t H5Eregister_class(const char *cls_name, const char *lib_name, const char *version); -H5_DLL herr_t H5Eunregister_class(hid_t class_id); -H5_DLL herr_t H5Eclose_msg(hid_t err_id); -H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg); -H5_DLL hid_t H5Ecreate_stack(void); -H5_DLL hid_t H5Eget_current_stack(void); -H5_DLL herr_t H5Eappend_stack(hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack); -H5_DLL herr_t H5Eclose_stack(hid_t stack_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Registers a client library or application program to the HDF5 error API + * + * \param[in] cls_name Name of the error class + * \param[in] lib_name Name of the client library or application to which the error class belongs + * \param[in] version Version of the client library or application to which the + error class belongs. Can be \c NULL. + * \return Returns a class identifier on success; otherwise returns H5I_INVALID_ID. + * + * \details H5Eregister_class() registers a client library or application + * program to the HDF5 error API so that the client library or + * application program can report errors together with the HDF5 + * library. It receives an identifier for this error class for further + * error operations. The library name and version number will be + * printed out in the error message as a preamble. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Eregister_class(const char *cls_name, const char *lib_name, const char *version); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Removes an error class + * + * \param[in] class_id Error class identifier. + * \return \herr_t + * + * \details H5Eunregister_class() removes the error class specified by \p + * class_id. All the major and minor errors in this class will also be + * closed. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eunregister_class(hid_t class_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Closes an error message + * + * \param[in] err_id An error message identifier + * \return \herr_t + * + * \details H5Eclose_msg() closes an error message identifier, which can be + * either a major or minor message. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eclose_msg(hid_t err_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Adds a major error message to an error class + * + * \param[in] cls An error class identifier + * \param[in] msg_type The type of the error message + * \param[in] msg Major error message + * \return \herr_t + * + * \details H5Ecreate_msg() adds an error message to an error class defined by + * client library or application program. The error message can be + * either major or minor as indicated by the parameter \p msg_type. + * + * Use H5Eclose_msg() to close the message identifier returned by this + * function. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Creates a new, empty error stack + * + * \return \hid_ti{error stack} + * + * \details H5Ecreate_stack() creates a new empty error stack and returns the + * new stack’s identifier. Use H5Eclose_stack() to close the error stack + * identifier returned by this function. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Ecreate_stack(void); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns a copy of the current error stack + * + * \return \hid_ti{error stack} + * + * \details H5Eget_current_stack() copies the current error stack and returns an + * error stack identifier for the new copy. + * + * \since 1.8.0 + */ +H5_DLL hid_t H5Eget_current_stack(void); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Appends one error stack to another, optionally closing the source + * stack. + * + * \estack_id{dst_stack_id} + * \estack_id{src_stack_id} + * \param[in] close_source_stack Flag to indicate whether to close the source stack + * \return \herr_t + * + * \details H5Eappend_stack() appends the messages from error stack + * \p src_stack_id to the error stack \p dst_stack_id. + * If \p close_source_stack is \c TRUE, the source error stack + * will be closed. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eappend_stack(hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Closes an error stack handle + * + * \estack_id{stack_id} + * + * \return \herr_t + * + * \details H5Eclose_stack() closes the error stack handle \p stack_id + * and releases its resources. #H5E_DEFAULT cannot be closed. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eclose_stack(hid_t stack_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Retrieves error class name + * + * \param[in] class_id Error class identifier + * \param[out] name Buffer for the error class name + * \param[in] size The maximum number of characters the class name to be returned + * by this function in\p name. + * \return Returns non-negative value as on success; otherwise returns negative value. + * + * \details H5Eget_class_name() retrieves the name of the error class specified + * by the class identifier. If non-NULL pointer is passed in for \p + * name and \p size is greater than zero, the class name of \p size + * long is returned. The length of the error class name is also + * returned. If NULL is passed in as \p name, only the length of class + * name is returned. If zero is returned, it means no name. The user is + * responsible for allocating sufficient buffer space for the name. + * + * \since 1.8.0 + */ H5_DLL ssize_t H5Eget_class_name(hid_t class_id, char *name, size_t size); -H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id); -H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id, - hid_t maj_id, hid_t min_id, const char *msg, ...); -H5_DLL herr_t H5Epop(hid_t err_stack, size_t count); -H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream); -H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data); -H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data); -H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data); -H5_DLL herr_t H5Eclear2(hid_t err_stack); -H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Replaces the current error stack + * + * \estack_id{err_stack_id} + * + * \return \herr_t + * + * \details H5Eset_current_stack() replaces the content of the current error + * stack with a copy of the content of the error stack specified by + * \p err_stack_id, and it closes the error stack specified by + * \p err_stack_id. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eset_current_stack(hid_t err_stack_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Pushes a new error record onto an error stack + * + * \estack_id{err_stack}. If the identifier is #H5E_DEFAULT, the error record + * will be pushed to the current stack. + * \param[in] file Name of the file in which the error was detected + * \param[in] func Name of the function in which the error was detected + * \param[in] line Line number in the file where the error was detected + * \param[in] cls_id Error class identifier + * \param[in] maj_id Major error identifier + * \param[in] min_id Minor error identifier + * \param[in] msg Error description string + * \return \herr_t + * + * \details H5Epush2() pushes a new error record onto the error stack specified + * by \p err_stack.\n + * The error record contains the error class identifier \p cls_id, the + * major and minor message identifiers \p maj_id and \p min_id, the + * function name \p func where the error was detected, the file name \p + * file and line number \p line in the file where the error was + * detected, and an error description \p msg.\n + * The major and minor errors must be in the same error class.\n + * The function name, filename, and error description strings must be + * statically allocated.\n + * \p msg can be a format control string with additional + * arguments. This design of appending additional arguments is similar + * to the system and C functions printf() and fprintf(). + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Epush2(hid_t err_stack, const char *file, const char *func, unsigned line, hid_t cls_id, + hid_t maj_id, hid_t min_id, const char *msg, ...); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Deletes specified number of error messages from the error stack + * + * \estack_id{err_stack} + * \param[in] count The number of error messages to be deleted from the top + * of error stack + * \return \herr_t + * + * \details H5Epop() deletes the number of error records specified in \p count + * from the top of the error stack specified by \p err_stack (including + * major, minor messages and description). The number of error messages + * to be deleted is specified by \p count. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Epop(hid_t err_stack, size_t count); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Prints the specified error stack in a default manner + * + * \estack_id{err_stack} + * \param[in] stream File pointer, or \c NULL for \c stderr + * \return \herr_t + * + * \details H5Eprint2() prints the error stack specified by \p err_stack on the + * specified stream, \p stream. Even if the error stack is empty, a + * one-line message of the following form will be printed: + * \code{.unparsed} + * HDF5-DIAG: Error detected in HDF5 library version: 1.5.62 thread 0. + * \endcode + * + * A similar line will appear before the error messages of each error + * class stating the library name, library version number, and thread + * identifier. + * + * If \p err_stack is #H5E_DEFAULT, the current error stack will be + * printed. + * + * H5Eprint2() is a convenience function for H5Ewalk2() with a function + * that prints error messages. Users are encouraged to write their own + * more specific error handlers. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eprint2(hid_t err_stack, FILE *stream); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Walks the specified error stack, calling the specified function + * + * \estack_id{err_stack} + * \param[in] direction Direction in which the error stack is to be walked + * \param[in] func Function to be called for each error encountered + * \param[in] client_data Data to be passed to \p func + * \return \herr_t + * + * \details H5Ewalk2() walks the error stack specified by err_stack for the + * current thread and calls the function specified in \p func for each + * error along the way. + * + * If the value of \p err_stack is #H5E_DEFAULT, then H5Ewalk2() walks + * the current error stack. + * + * \p direction specifies whether the stack is walked from the inside + * out or the outside in. A value of #H5E_WALK_UPWARD means to begin + * with the most specific error and end at the API; a value of + * #H5E_WALK_DOWNWARD means to start at the API and end at the + * innermost function where the error was first detected. + * + * \p func, a function conforming to the #H5E_walk2_t prototype, will + * be called for each error in the error stack. Its arguments will + * include an index number \c n (beginning at zero regardless of stack + * traversal direction), an error stack entry \c err_desc, and the \c + * client_data pointer passed to H5Eprint(). The #H5E_walk2_t prototype + * is as follows: + * \snippet this H5E_walk2_t_snip + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t func, void *client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns the settings for the automatic error stack traversal + * function and its data + * + * \estack_id + * \param[out] func The function currently set to be called upon an error condition + * \param[out] client_data Data currently set to be passed to the error function + * \return \herr_t + * + * \details H5Eget_auto2() returns the settings for the automatic error stack + * traversal function, \p func, and its data, \p client_data, that are + * associated with the error stack specified by \p estack_id. + * + * Either or both of the \p func and \p client_data arguments may be + * \c NULL, in which case the value is not returned. + * + * The library initializes its default error stack traversal functions + * to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns + * H5Eprint2() or the user-defined function passed in through + * H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the + * user-defined function passed in through H5Eset_auto1(). However, if + * the application passes in a user-defined function through + * H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal + * function. If the application passes in a user-defined function + * through H5Eset_auto2(), it should call H5Eget_auto2() to query the + * traversal function. + * + * Mixing the new style and the old style functions will cause a + * failure. For example, if the application sets a user-defined + * old-style traversal function through H5Eset_auto1(), a call to + * H5Eget_auto2() will fail and will indicate that the application has + * mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing + * H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if + * the traversal functions are the library’s default H5Eprint1() or + * H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing + * H5Eset_auto2() and H5Eget_auto1() does not fail. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eget_auto2(hid_t estack_id, H5E_auto2_t *func, void **client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Turns automatic error printing on or off + * + * \estack_id + * \param[in] func Function to be called upon an error condition + * \param[in] client_data Data passed to the error function + * \return \herr_t + * + * \details H5Eset_auto2() turns on or off automatic printing of errors for the + * error stack specified with \p estack_id. An \p estack_id value of + * #H5E_DEFAULT indicates the current stack. + * + * When automatic printing is turned on, by the use of a non-null \p func + * pointer, any API function which returns an error indication will + * first call \p func, passing it \p client_data as an argument. + * + * \p func, a function compliant with the #H5E_auto2_t prototype, is + * defined in the H5Epublic.h source code file as: + * \snippet this H5E_auto2_t_snip + * + * When the library is first initialized, the auto printing function is + * set to H5Eprint2() (cast appropriately) and \p client_data is the + * standard error stream pointer, \c stderr. + * + * Automatic stack traversal is always in the #H5E_WALK_DOWNWARD + * direction. + * + * Automatic error printing is turned off with a H5Eset_auto2() call + * with a \c NULL \p func pointer. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eset_auto2(hid_t estack_id, H5E_auto2_t func, void *client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Clears the specified error stack or the error stack for the current thread + * + * \estack_id{err_stack} + * \return \herr_t + * + * \details H5Eclear2() clears the error stack specified by \p err_stack, or, if + * \p err_stack is set to #H5E_DEFAULT, the error stack for the current + * thread. + * + * \p err_stack is an error stack identifier, such as that returned by + * H5Eget_current_stack(). + * + * The current error stack is also cleared whenever an API function is + * called, with certain exceptions (for instance, H5Eprint1() or + * H5Eprint2()). + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eclear2(hid_t err_stack); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Determines the type of error stack + * + * \estack_id{err_stack} + * \param[out] is_stack A flag indicating which error stack \c typedef the + * specified error stack conforms to + * + * \return \herr_t + * + * \details H5Eauto_is_v2() determines whether the error auto reporting function + * for an error stack conforms to the #H5E_auto2_t \c typedef or the + * #H5E_auto1_t \c typedef. + * + * The \p is_stack parameter is set to 1 if the error stack conforms to + * #H5E_auto2_t and 0 if it conforms to #H5E_auto1_t. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Eauto_is_v2(hid_t err_stack, unsigned *is_stack); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Retrieves an error message + * + * \param[in] msg_id Error message identifier + * \param[out] type The type of the error message Valid values are #H5E_MAJOR + * and #H5E_MINOR. + * \param[out] msg Error message buffer + * \param[in] size The length of error message to be returned by this function + * \return Returns the size of the error message in bytes on success; otherwise + * returns a negative value. + * + * \details H5Eget_msg() retrieves the error message including its length and + * type. The error message is specified by \p msg_id. The user is + * responsible for passing in sufficient buffer space for the + * message. If \p msg is not NULL and \p size is greater than zero, the + * error message of \p size long is returned. The length of the message + * is also returned. If NULL is passed in as \p msg, only the length + * and type of the message is returned. If the return value is zero, it + * means there is no message. + * + * \since 1.8.0 + */ H5_DLL ssize_t H5Eget_msg(hid_t msg_id, H5E_type_t *type, char *msg, size_t size); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Retrieves the number of error messages in an error stack + * + * \estack_id{error_stack_id} + * \return Returns a non-negative value on success; otherwise returns a negative value. + * + * \details H5Eget_num() retrieves the number of error records in the error + * stack specified by \p error_stack_id (including major, minor + * messages and description). + * + * \since 1.8.0 + */ H5_DLL ssize_t H5Eget_num(hid_t error_stack_id); /* Symbols defined for compatibility with previous versions of the HDF5 API. @@ -189,30 +670,259 @@ H5_DLL ssize_t H5Eget_num(hid_t error_stack_id); typedef hid_t H5E_major_t; typedef hid_t H5E_minor_t; -/* Information about an error element of error stack. */ +/** + * Information about an error element of error stack. + */ typedef struct H5E_error1_t { - H5E_major_t maj_num; /*major error number */ - H5E_minor_t min_num; /*minor error number */ - const char *func_name; /*function in which error occurred */ - const char *file_name; /*file in which error occurred */ - unsigned line; /*line in file where error occurs */ - const char *desc; /*optional supplied description */ + H5E_major_t maj_num; /**< major error number */ + H5E_minor_t min_num; /**< minor error number */ + const char *func_name; /**< function in which error occurred */ + const char *file_name; /**< file in which error occurred */ + unsigned line; /**< line in file where error occurs */ + const char *desc; /**< optional supplied description */ } H5E_error1_t; /* Error stack traversal callback function pointers */ +//! <!-- [H5E_walk1_t_snip] --> +/** + * \brief Callback function for H5Ewalk1() + * + * \param[in] n Indexed error position in the stack + * \param[in] err_desc Pointer to a data structure describing the error + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_walk1_t)(int n, H5E_error1_t *err_desc, void *client_data); +//! <!-- [H5E_walk1_t_snip] --> + +//! <!-- [H5E_auto1_t_snip] --> +/** + * \brief Callback function for H5Eset_auto1() + * + * \param[in] client_data Pointer to client data in the format expected by the + * user-defined function + * \return \herr_t + */ typedef herr_t (*H5E_auto1_t)(void *client_data); +//! <!-- [H5E_auto1_t_snip] --> /* Function prototypes */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Clears the error stack for the current thread + * + * \return \herr_t + * + * \details H5Eclear1() clears the error stack for the current thread.\n + * The stack is also cleared whenever an API function is called, with + * certain exceptions (for instance, H5Eprint1()). + * + * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated + * in this release. + */ H5_DLL herr_t H5Eclear1(void); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns the current settings for the automatic error stack traversal + * function and its data + * + * \param[out] func Current setting for the function to be called upon an error + * condition + * \param[out] client_data Current setting for the data passed to the error + * function + * \return \herr_t + * + * \details H5Eget_auto1() returns the current settings for the automatic error + * stack traversal function, \p func, and its data, + * \p client_data. Either or both arguments may be \c NULL, in which case the + * value is not returned. + * + * The library initializes its default error stack traversal functions + * to H5Eprint1() and H5Eprint2(). A call to H5Eget_auto2() returns + * H5Eprint2() or the user-defined function passed in through + * H5Eset_auto2(). A call to H5Eget_auto1() returns H5Eprint1() or the + * user-defined function passed in through H5Eset_auto1(). However, if + * the application passes in a user-defined function through + * H5Eset_auto1(), it should call H5Eget_auto1() to query the traversal + * function. If the application passes in a user-defined function + * through H5Eset_auto2(), it should call H5Eget_auto2() to query the + * traversal function. + * + * Mixing the new style and the old style functions will cause a + * failure. For example, if the application sets a user-defined + * old-style traversal function through H5Eset_auto1(), a call to + * H5Eget_auto2() will fail and will indicate that the application has + * mixed H5Eset_auto1() and H5Eget_auto2(). On the other hand, mixing + * H5Eset_auto2() and H5Eget_auto1() will also cause a failure. But if + * the traversal functions are the library’s default H5Eprint1() or + * H5Eprint2(), mixing H5Eset_auto1() and H5Eget_auto2() or mixing + * H5Eset_auto2() and H5Eget_auto1() does not fail. + * + * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and + * deprecated in this release. + */ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Pushes a new error record onto the error stack + * + * \param[in] file Name of the file in which the error was detected + * \param[in] func Name of the function in which the error was detected + * \param[in] line Line number in the file where the error was detected + * \param[in] maj Major error identifier + * \param[in] min Minor error identifier + * \param[in] str Error description string + * \return \herr_t + * + * \details H5Epush1() pushes a new error record onto the error stack for the + * current thread.\n + * The error has major and minor numbers \p maj_num + * and \p min_num, the function \p func where the error was detected, the + * name of the file \p file where the error was detected, the line \p line + * within that file, and an error description string \p str.\n + * The function name, filename, and error description strings must be statically + * allocated. + * + * \since 1.4.0 + * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and + * deprecated in this release. + */ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_major_t maj, H5E_minor_t min, const char *str); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Prints the current error stack in a default manner + * + * \param[in] stream File pointer, or \c NULL for \c stderr + * \return \herr_t + * + * \details H5Eprint1() prints prints the error stack for the current thread + * on the specified stream, \p stream. Even if the error stack is empty, a + * one-line message of the following form will be printed: + * \code{.unparsed} + * HDF5-DIAG: Error detected in thread 0. + * \endcode + * H5Eprint1() is a convenience function for H5Ewalk1() with a function + * that prints error messages. Users are encouraged to write their own + * more specific error handlers. + * + * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and + * deprecated in this release. + */ H5_DLL herr_t H5Eprint1(FILE *stream); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Turns automatic error printing on or off + * + * \param[in] func Function to be called upon an error condition + * \param[in] client_data Data passed to the error function + * \return \herr_t + * + * \details H5Eset_auto1() turns on or off automatic printing of errors. When + * turned on (non-null \p func pointer), any API function which returns + * an error indication will first call \p func, passing it \p + * client_data as an argument. + * + * \p func, a function conforming to the #H5E_auto1_t prototype, is + * defined in the H5Epublic.h source code file as: + * \snippet this H5E_auto1_t_snip + * + * When the library is first initialized, the auto printing function is + * set to H5Eprint1() (cast appropriately) and \p client_data is the + * standard error stream pointer, \c stderr. + * + * Automatic stack traversal is always in the #H5E_WALK_DOWNWARD + * direction. + * + * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and + * deprecated in this release. + */ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Walks the current error stack, calling the specified function + * + * \param[in] direction Direction in which the error stack is to be walked + * \param[in] func Function to be called for each error encountered + * \param[in] client_data Data to be passed to \p func + * \return \herr_t + * + * \details H5Ewalk1() walks the error stack for the current thread and calls + * the function specified in \p func for each error along the way. + * + * \p direction specifies whether the stack is walked from the inside + * out or the outside in. A value of #H5E_WALK_UPWARD means to begin + * with the most specific error and end at the API; a value of + * #H5E_WALK_DOWNWARD means to start at the API and end at the + * innermost function where the error was first detected. + * + * \p func, a function conforming to the #H5E_walk1_t prototype, will + * be called for each error in the error stack. Its arguments will + * include an index number \c n (beginning at zero regardless of stack + * traversal direction), an error stack entry \c err_desc, and the \c + * client_data pointer passed to H5Eprint(). The #H5E_walk1_t prototype + * is as follows: + * \snippet this H5E_walk1_t_snip + * + * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and + * deprecated in this release. + */ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client_data); -H5_DLL char * H5Eget_major(H5E_major_t maj); -H5_DLL char * H5Eget_minor(H5E_minor_t min); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns a character string describing an error specified by a major + * error number + * + * \param[in] maj Major error number + * \return \herr_t + * + * \details Given a major error number, H5Eget_major() returns a constant + * character string that describes the error. + * + * \attention This function returns a dynamically allocated string (\c char + * array). An application calling this function must free the memory + * associated with the return value to prevent a memory leak. + * + * \deprecated 1.8.0 Function deprecated in this release. + */ +H5_DLL char *H5Eget_major(H5E_major_t maj); +/** + * -------------------------------------------------------------------------- + * \ingroup H5E + * + * \brief Returns a character string describing an error specified by a minor + * error number + * + * \param[in] min Minor error number + * \return \herr_t + * + * \details Given a minor error number, H5Eget_minor() returns a constant + * character string that describes the error. + * + * \attention In the Release 1.8.x series, H5Eget_minor() returns a string of + * dynamic allocated \c char array. An application calling this + * function from an HDF5 library of Release 1.8.0 or later must free + * the memory associated with the return value to prevent a memory + * leak. This is a change from the 1.6.x release series. + * + * \deprecated 1.8.0 Function deprecated and return type changed in this release. + */ +H5_DLL char *H5Eget_minor(H5E_minor_t min); #endif /* H5_NO_DEPRECATED_SYMBOLS */ #ifdef __cplusplus diff --git a/src/H5FDcore.h b/src/H5FDcore.h index f8a516a..d456c3e 100644 --- a/src/H5FDcore.h +++ b/src/H5FDcore.h @@ -25,8 +25,70 @@ #ifdef __cplusplus extern "C" { #endif -H5_DLL hid_t H5FD_core_init(void); +H5_DLL hid_t H5FD_core_init(void); + +/** + * \ingroup FAPL + * + * \brief Modifies the file access property list to use the #H5FD_CORE driver + * + * \fapl_id + * \param[in] increment Size, in bytes, of memory increments + * \param[in] backing_store Boolean flag indicating whether to write the file + * contents to disk when the file is closed + * \returns \herr_t + * + * \details H5Pset_fapl_core() modifies the file access property list to use the + * #H5FD_CORE driver. + * + * The #H5FD_CORE driver enables an application to work with a file in + * memory, speeding reads and writes as no disk access is made. File + * contents are stored only in memory until the file is closed. The \p + * backing_store parameter determines whether file contents are ever + * written to disk. + * + * \p increment specifies the increment by which allocated memory is to + * be increased each time more memory is required. + * + * While using H5Fcreate() to create a core file, if the \p + * backing_store is set to 1 (TRUE), the file contents are flushed to a + * file with the same name as this core file when the file is closed or + * access to the file is terminated in memory. + * + * The application is allowed to open an existing file with #H5FD_CORE + * driver. While using H5Fopen() to open an existing file, if the \p + * backing_store is set to 1 (TRUE) and the \c flags for H5Fopen() is set to + * #H5F_ACC_RDWR, any change to the file contents are saved to the file + * when the file is closed. If \p backing_store is set to 0 (FALSE) and the \c + * flags for H5Fopen() is set to #H5F_ACC_RDWR, any change to the file + * contents will be lost when the file is closed. If the flags for + * H5Fopen() is set to #H5F_ACC_RDONLY, no change to the file is + * allowed either in memory or on file. + * + * \note Currently this driver cannot create or open family or multi files. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_core(hid_t fapl_id, size_t increment, hbool_t backing_store); + +/** + * \ingroup FAPL + * + * \brief Queries core file driver properties + * + * \fapl_id + * \param[out] increment Size, in bytes, of memory increments + * \param[out] backing_store Boolean flag indicating whether to write the file + * contents to disk when the file is closed + * \returns \herr_t + * + * \details H5Pget_fapl_core() queries the #H5FD_CORE driver properties as set + * by H5Pset_fapl_core(). + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pget_fapl_core(hid_t fapl_id, size_t *increment /*out*/, hbool_t *backing_store /*out*/); #ifdef __cplusplus } diff --git a/src/H5FDdirect.h b/src/H5FDdirect.h index eec10de..f06de7f 100644 --- a/src/H5FDdirect.h +++ b/src/H5FDdirect.h @@ -37,8 +37,69 @@ extern "C" { #define FBSIZE_DEF 4096 #define CBSIZE_DEF 16 * 1024 * 1024 -H5_DLL hid_t H5FD_direct_init(void); +H5_DLL hid_t H5FD_direct_init(void); + +/** + * \ingroup FAPL + * + * \brief Sets up use of the direct I/O driver + * + * \fapl_id + * \param[in] alignment Required memory alignment boundary + * \param[in] block_size File system block size + * \param[in] cbuf_size Copy buffer size + * \returns \herr_t + * + * \details H5Pset_fapl_direct() sets the file access property list, \p fapl_id, + * to use the direct I/O driver, #H5FD_DIRECT. With this driver, data + * is written to or read from the file synchronously without being + * cached by the system. + * + * File systems usually require the data address in memory, the file + * address, and the size of the data to be aligned. The HDF5 library’s + * direct I/O driver is able to handle unaligned data, though that will + * consume some additional memory resources and may slow + * performance. To get better performance, use the system function \p + * posix_memalign to align the data buffer in memory and the HDF5 + * function H5Pset_alignment() to align the data in the file. Be aware, + * however, that aligned data I/O may cause the HDF5 file to be bigger + * than the actual data size would otherwise require because the + * alignment may leave some holes in the file. + * + * \p alignment specifies the required alignment boundary in memory. + * + * \p block_size specifies the file system block size. A value of 0 + * (zero) means to use HDF5 library’s default value of 4KB. + * + * \p cbuf_size specifies the copy buffer size. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pset_fapl_direct(hid_t fapl_id, size_t alignment, size_t block_size, size_t cbuf_size); + +/** + * \ingroup FAPL + * + * \brief Retrieves direct I/O driver settings + * + * \fapl_id + * \param[out] boundary Required memory alignment boundary + * \param[out] block_size File system block size + * \param[out] cbuf_size Copy buffer size + * \returns \herr_t + * + * \details H5Pget_fapl_direct() retrieves the required memory alignment (\p + * alignment), file system block size (\p block_size), and copy buffer + * size (\p cbuf_size) settings for the direct I/O driver, #H5FD_DIRECT, + * from the file access property list \p fapl_id. + * + * See H5Pset_fapl_direct() for discussion of these values, + * requirements, and important considerations. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pget_fapl_direct(hid_t fapl_id, size_t *boundary /*out*/, size_t *block_size /*out*/, size_t *cbuf_size /*out*/); diff --git a/src/H5FDfamily.h b/src/H5FDfamily.h index f00836f..20ef532 100644 --- a/src/H5FDfamily.h +++ b/src/H5FDfamily.h @@ -26,8 +26,58 @@ extern "C" { #endif -H5_DLL hid_t H5FD_family_init(void); +H5_DLL hid_t H5FD_family_init(void); + +/** + * \ingroup FAPL + * + * \brief Sets the file access property list to use the family driver + * + * \fapl_id + * \param[in] memb_size Size in bytes of each file member + * \param[in] memb_fapl_id Identifier of file access property list for + * each family member + * \returns \herr_t + * + * \details H5Pset_fapl_family() sets the file access property list identifier, + * \p fapl_id, to use the family driver. + * + * \p memb_size is the size in bytes of each file member. This size + * will be saved in file when the property list \p fapl_id is used to + * create a new file. If \p fapl_id is used to open an existing file, + * \p memb_size has to be equal to the original size saved in file. A + * failure with an error message indicating the correct member size + * will be returned if \p memb_size does not match the size saved. If + * any user does not know the original size, #H5F_FAMILY_DEFAULT can be + * passed in. The library will retrieve the saved size. + * + * \p memb_fapl_id is the identifier of the file access property list + * to be used for each family member. + * + * \version 1.8.0 Behavior of the \p memb_size parameter was changed. + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_family(hid_t fapl_id, hsize_t memb_size, hid_t memb_fapl_id); + +/** + * \ingroup FAPL + * + * \brief Returns file access property list information + * + * \fapl_id + * \param[out] memb_size Size in bytes of each file member + * \param[out] memb_fapl_id Identifier of file access property list for + * each family member + * \returns \herr_t + * + * \details H5Pget_fapl_family() returns file access property list for use with + * the family driver. This information is returned through the output + * parameters. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pget_fapl_family(hid_t fapl_id, hsize_t *memb_size /*out*/, hid_t *memb_fapl_id /*out*/); #ifdef __cplusplus diff --git a/src/H5FDhdfs.h b/src/H5FDhdfs.h index abe7682..8d65ac7 100644 --- a/src/H5FDhdfs.h +++ b/src/H5FDhdfs.h @@ -112,8 +112,20 @@ typedef struct H5FD_hdfs_fapl_t { int32_t stream_buffer_size; } H5FD_hdfs_fapl_t; -H5_DLL hid_t H5FD_hdfs_init(void); +H5_DLL hid_t H5FD_hdfs_init(void); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pget_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa_out); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pset_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa); #ifdef __cplusplus diff --git a/src/H5FDlog.h b/src/H5FDlog.h index aa1f3cb..969c091 100644 --- a/src/H5FDlog.h +++ b/src/H5FDlog.h @@ -65,7 +65,410 @@ extern "C" { #endif -H5_DLL hid_t H5FD_log_init(void); +H5_DLL hid_t H5FD_log_init(void); + +/** + * \ingroup FAPL + * + * \brief Sets up the logging virtual file driver (#H5FD_LOG) for use + * + * \fapl_id + * \param[in] logfile Name of the log file + * \param[in] flags Flags specifying the types of logging activity + * \param[in] buf_size The size of the logging buffers, in bytes (see description) + * \returns \herr_t + * + * \details H5Pset_fapl_log() modifies the file access property list to use the + * logging driver, #H5FD_LOG. The logging virtual file driver (VFD) is + * a clone of the standard SEC2 (#H5FD_SEC2) driver with additional + * facilities for logging VFD metrics and activity to a file. + * + * \p logfile is the name of the file in which the logging entries are + * to be recorded. + * + * The actions to be logged are specified in the parameter \p flags + * using the pre-defined constants described in the following + * table. Multiple flags can be set through the use of a logical \c OR + * contained in parentheses. For example, logging read and write + * locations would be specified as + * \Code{(H5FD_LOG_LOC_READ|H5FD_LOG_LOC_WRITE)}. + * + * <table> + * <caption>Table1: Logging Flags</caption> + * <tr> + * <td> + * #H5FD_LOG_LOC_READ + * </td> + * <td rowspan="3"> + * Track the location and length of every read, write, or seek operation. + * </td> + * </tr> + * <tr><td>#H5FD_LOG_LOC_WRITE</td></tr> + * <tr><td>#H5FD_LOG_LOC_SEEK</td></tr> + * <tr> + * <td> + * #H5FD_LOG_LOC_IO + * </td> + * <td> + * Track all I/O locations and lengths. The logical equivalent of the following: + * \Code{(#H5FD_LOG_LOC_READ | #H5FD_LOG_LOC_WRITE | #H5FD_LOG_LOC_SEEK)} + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_FILE_READ + * </td> + * <td rowspan="2"> + * Track the number of times each byte is read or written. + * </td> + * </tr> + * <tr><td>#H5FD_LOG_FILE_WRITE</td></tr> + * <tr> + * <td> + * #H5FD_LOG_FILE_IO + * </td> + * <td> + * Track the number of times each byte is read and written. The logical + * equivalent of the following: + * \Code{(#H5FD_LOG_FILE_READ | #H5FD_LOG_FILE_WRITE)} + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_FLAVOR + * </td> + * <td> + * Track the type, or flavor, of information stored at each byte. + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_NUM_READ + * </td> + * <td rowspan="4"> + * Track the total number of read, write, seek, or truncate operations that occur. + * </td> + * </tr> + * <tr><td>#H5FD_LOG_NUM_WRITE</td></tr> + * <tr><td>#H5FD_LOG_NUM_SEEK</td></tr> + * <tr><td>#H5FD_LOG_NUM_TRUNCATE</td></tr> + * <tr> + * <td> + * #H5FD_LOG_NUM_IO + * </td> + * <td> + * Track the total number of all types of I/O operations. The logical equivalent + * of the following: + * \Code{(#H5FD_LOG_NUM_READ | #H5FD_LOG_NUM_WRITE | #H5FD_LOG_NUM_SEEK | #H5FD_LOG_NUM_TRUNCATE)} + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_TIME_OPEN + * </td> + * <td rowspan="6"> + * Track the time spent in open, stat, read, write, seek, or close operations. + * </td> + * </tr> + * <tr><td>#H5FD_LOG_TIME_STAT</td></tr> + * <tr><td>#H5FD_LOG_TIME_READ</td></tr> + * <tr><td>#H5FD_LOG_TIME_WRITE</td></tr> + * <tr><td>#H5FD_LOG_TIME_SEEK</td></tr> + * <tr><td>#H5FD_LOG_TIME_CLOSE</td></tr> + * <tr> + * <td> + * #H5FD_LOG_TIME_IO + * </td> + * <td> + * Track the time spent in each of the above operations. The logical equivalent + * of the following: + * \Code{(#H5FD_LOG_TIME_OPEN | #H5FD_LOG_TIME_STAT | #H5FD_LOG_TIME_READ | #H5FD_LOG_TIME_WRITE | + * #H5FD_LOG_TIME_SEEK | #H5FD_LOG_TIME_CLOSE)} + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_ALLOC + * </td> + * <td> + * Track the allocation of space in the file. + * </td> + * </tr> + * <tr> + * <td> + * #H5FD_LOG_ALL + * </td> + * <td> + * Track everything. The logical equivalent of the following: + * \Code{(#H5FD_LOG_ALLOC | #H5FD_LOG_TIME_IO | #H5FD_LOG_NUM_IO | #H5FD_LOG_FLAVOR | #H5FD_LOG_FILE_IO | + * #H5FD_LOG_LOC_IO)} + * </td> + * </tr> + * </table> + * The logging driver can track the number of times each byte in the file is + * read from or written to (using #H5FD_LOG_FILE_READ and #H5FD_LOG_FILE_WRITE) + * and what kind of data is at that location (e.g., metadata, raw data; using + * #H5FD_LOG_FLAVOR). This information is tracked in internal buffers of size + * buf_size, which must be at least the maximum size in bytes of the file to be + * logged while the log driver is in use.\n + * One buffer of size buf_size will be created for each of #H5FD_LOG_FILE_READ, + * #H5FD_LOG_FILE_WRITE and #H5FD_LOG_FLAVOR when those flags are set; these + * buffers will not grow as the file increases in size. + * + * \par Output: + * This section describes the logging driver (LOG VFD) output.\n + * The table, immediately below, describes output of the various logging driver + * flags and function calls. A list of valid flavor values, describing the type + * of data stored, follows the table. + * <table> + * <caption>Table2: Logging Output</caption> + * <tr> + * <th>Flag</th><th>VFD Call</th><th>Output and Comments</th> + * </th> + * </tr> + * <tr> + * <td>#H5FD_LOG_LOC_READ</td> + * <td>Read</td> + * <td> + * \Code{%10a-%10a (%10Zu bytes) (%s) Read}\n\n + * Start position\n + * End position\n + * Number of bytes\n + * Flavor of read\n\n + * Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_LOC_READ</td> + * <td>Read Error</td> + * <td> + * \Code{Error! Reading: %10a-%10a (%10Zu bytes)}\n\n + * Same parameters as non-error entry. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_LOC_WRITE</td> + * <td>Write</td> + * <td> + * \Code{%10a-%10a (%10Zu bytes) (%s) Written}\n\n + * Start position\n + * End position\n + * Number of bytes\n + * Flavor of write\n\n + * Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_LOC_WRITE</td> + * <td>Write Error</td> + * <td> + * \Code{Error! Writing: %10a-%10a (%10Zu bytes)}\n\n + * Same parameters as non-error entry. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_LOC_SEEK</td> + * <td>Read, Write</td> + * <td> + * \Code{Seek: From %10a-%10a}\n\n + * Start position\n + * End position\n\n + * Adds \Code{(\%f s)} and seek time if #H5FD_LOG_TIME_SEEK is also set. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_FILE_READ</td> + * <td>Close</td> + * <td> + * Begins with:\n + * Dumping read I/O information\n\n + * Then, for each range of identical values, there is this line:\n + * \Code{Addr %10-%10 (%10lu bytes) read from %3d times}\n\n + * Start address\n + * End address\n + * Number of bytes\n + * Number of times read\n\n + * Note: The data buffer is scanned and each range of identical values + * gets one entry in the log file to save space and make it easier to read. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_FILE_WRITE</td> + * <td>Close</td> + * <td> + * Begins with:\n + * Dumping read I/O information\n\n + * Then, for each range of identical values, there is this line:\n + * \Code{Addr %10-%10 (%10lu bytes) written to %3d times}\n\n + * Start address\n + * End address\n + * Number of bytes\n + * Number of times written\n\n + * Note: The data buffer is scanned and each range of identical values + * gets one entry in the log file to save space and make it easier to read. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_FLAVOR</td> + * <td>Close</td> + * <td> + * Begins with:\n + * Dumping I/O flavor information\n\n + * Then, for each range of identical values, there is this line:\n + * \Code{Addr %10-%10 (%10lu bytes) flavor is %s}\n\n + * Start address\n + * End address\n + * Number of bytes\n + * Flavor\n\n + * Note: The data buffer is scanned and each range of identical values + * gets one entry in the log file to save space and make it easier to read. + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_NUM_READ</td> + * <td>Close</td> + * <td> + * Total number of read operations: \Code{%11u} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_NUM_WRITE</td> + * <td>Close</td> + * <td> + * Total number of write operations: \Code{%11u} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_NUM_SEEK</td> + * <td>Close</td> + * <td> + * Total number of seek operations: \Code{%11u} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_NUM_TRUNCATE</td> + * <td>Close</td> + * <td> + * Total number of truncate operations: \Code{%11u} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_OPEN</td> + * <td>Open</td> + * <td> + * Open took: \Code{(\%f s)} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_READ</td> + * <td>Close, Read</td> + * <td> + * Total time in read operations: \Code{\%f s}\n\n + * See also: #H5FD_LOG_LOC_READ + * </td> + * </tr> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_WRITE</td> + * <td>Close, Write</td> + * <td> + * Total time in write operations: \Code{\%f s}\n\n + * See also: #H5FD_LOG_LOC_WRITE + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_SEEK</td> + * <td>Close, Read, Write</td> + * <td> + * Total time in write operations: \Code{\%f s}\n\n + * See also: #H5FD_LOG_LOC_SEEK or #H5FD_LOG_LOC_WRITE + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_CLOSE</td> + * <td>Close</td> + * <td> + * Close took: \Code{(\%f s)} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_TIME_STAT</td> + * <td>Open</td> + * <td> + * Stat took: \Code{(\%f s)} + * </td> + * </tr> + * <tr> + * <td>#H5FD_LOG_ALLOC</td> + * <td>Alloc</td> + * <td> + * \Code{%10-%10 (%10Hu bytes) (\%s) Allocated}\n\n + * Start of address space\n + * End of address space\n + * Total size allocation\n + * Flavor of allocation + * </td> + * </tr> + * </table> + * + * \par Flavors: + * The \Emph{flavor} describes the type of stored information. The following + * table lists the flavors that appear in log output and briefly describes each. + * These terms are provided here to aid in the construction of log message + * parsers; a full description is beyond the scope of this document. + * <table> + * <caption>Table3: Flavors of logged data</caption> + * <tr> + * <th>Flavor</th><th>Description</th> + * </th> + * </tr> + * <tr> + * <td>#H5FD_MEM_NOLIST</td> + * <td>Error value</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_DEFAULT</td> + * <td>Value not yet set.\n + * May also be a datatype set in a larger allocation that will be + * suballocated by the library.</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_SUPER</td> + * <td>Superblock data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_BTREE</td> + * <td>B-tree data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_DRAW</td> + * <td>Raw data (for example, contents of a dataset)</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_GHEAP</td> + * <td>Global heap data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_LHEAP</td> + * <td>Local heap data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_OHDR</td> + * <td>Object header data</td> + * </tr> + * </table> + * + * \version 1.8.7 The flags parameter has been changed from \Code{unsigned int} + * to \Code{unsigned long long}. + * The implementation of the #H5FD_LOG_TIME_OPEN, #H5FD_LOG_TIME_READ, + * #H5FD_LOG_TIME_WRITE, and #H5FD_LOG_TIME_SEEK flags has been finished. + * New flags were added: #H5FD_LOG_NUM_TRUNCATE and #H5FD_LOG_TIME_STAT. + * \version 1.6.0 The \c verbosity parameter has been removed. + * Two new parameters have been added: \p flags of type \Code{unsigned} and + * \p buf_size of type \Code{size_t}. + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_log(hid_t fapl_id, const char *logfile, unsigned long long flags, size_t buf_size); #ifdef __cplusplus diff --git a/src/H5FDmirror.h b/src/H5FDmirror.h index 8aef934..49e24c1 100644 --- a/src/H5FDmirror.h +++ b/src/H5FDmirror.h @@ -61,8 +61,20 @@ typedef struct H5FD_mirror_fapl_t { char remote_ip[H5FD_MIRROR_MAX_IP_LEN + 1]; } H5FD_mirror_fapl_t; -H5_DLL hid_t H5FD_mirror_init(void); +H5_DLL hid_t H5FD_mirror_init(void); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pget_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa_out); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pset_fapl_mirror(hid_t fapl_id, H5FD_mirror_fapl_t *fa); #ifdef __cplusplus diff --git a/src/H5FDmpi.h b/src/H5FDmpi.h index 3af5e41..cf49301 100644 --- a/src/H5FDmpi.h +++ b/src/H5FDmpi.h @@ -34,10 +34,12 @@ */ #define H5D_MULTI_CHUNK_IO_COL_THRESHOLD 60 -/* Type of I/O for data transfer properties */ +/** + * Type of I/O for data transfer properties + */ typedef enum H5FD_mpio_xfer_t { - H5FD_MPIO_INDEPENDENT = 0, /*zero is the default*/ - H5FD_MPIO_COLLECTIVE + H5FD_MPIO_INDEPENDENT = 0, /**< Use independent I/O access */ + H5FD_MPIO_COLLECTIVE /**< Use collective I/O access */ } H5FD_mpio_xfer_t; /* Type of chunked dataset I/O */ diff --git a/src/H5FDmpio.h b/src/H5FDmpio.h index 79b52c7..8caf11c 100644 --- a/src/H5FDmpio.h +++ b/src/H5FDmpio.h @@ -44,14 +44,237 @@ H5_DLLVAR hbool_t H5FD_mpi_opt_types_g; #ifdef __cplusplus extern "C" { #endif -H5_DLL hid_t H5FD_mpio_init(void); +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 } diff --git a/src/H5FDmulti.h b/src/H5FDmulti.h index 9e04d8d..62cc9c8 100644 --- a/src/H5FDmulti.h +++ b/src/H5FDmulti.h @@ -25,11 +25,228 @@ #ifdef __cplusplus extern "C" { #endif -H5_DLL hid_t H5FD_multi_init(void); +H5_DLL hid_t H5FD_multi_init(void); + +/** + * \ingroup FAPL + * + * \brief Sets up use of the multi-file driver + * + * \fapl_id + * \param[in] memb_map Maps memory usage types to other memory usage types + * \param[in] memb_fapl Property list for each memory usage type + * \param[in] memb_name Name generator for names of member files + * \param[in] memb_addr The offsets within the virtual address space, from 0 + * (zero) to #HADDR_MAX, at which each type of data storage begins + * \param[in] relax Allows read-only access to incomplete file sets when \c TRUE + * \returns \herr_t + * + * \details H5Pset_fapl_multi() sets the file access property list \p fapl_id to + * use the multi-file driver. + * + * The multi-file driver enables different types of HDF5 data and + * metadata to be written to separate files. These files are viewed by + * the HDF5 library and the application as a single virtual HDF5 file + * with a single HDF5 file address space. The types of data that can be + * broken out into separate files include raw data, the superblock, + * B-tree data, global heap data, local heap data, and object + * headers. At the programmer's discretion, two or more types of data + * can be written to the same file while other types of data are + * written to separate files. + * + * The array \p memb_map maps memory usage types to other memory usage + * types and is the mechanism that allows the caller to specify how + * many files are created. The array contains #H5FD_MEM_NTYPES entries, + * which are either the value #H5FD_MEM_DEFAULT or a memory usage + * type. The number of unique values determines the number of files + * that are opened. + * + * The array \p memb_fapl contains a property list for each memory + * usage type that will be associated with a file. + * + * The array \p memb_name should be a name generator (a + * \Code{printf}-style format with a \Code{%s} which will be replaced + * with the name passed to H5FDopen(), usually from H5Fcreate() or + * H5Fopen()). + * + * The array \p memb_addr specifies the offsets within the virtual + * address space, from 0 (zero) to #HADDR_MAX, at which each type of + * data storage begins. + * + * If \p relax is set to 1 (TRUE), then opening an existing file for + * read-only access will not fail if some file members are + * missing. This allows a file to be accessed in a limited sense if + * just the meta data is available. + * + * Default values for each of the optional arguments are as follows: + * <table> + * <tr> + * <td>\p memb_map</td> + * <td>The default member map contains the value #H5FD_MEM_DEFAULT for each element.</td> + * </tr> + * <tr> + * <td> + * \p memb_fapl + * </td> + * <td> + * The default value is #H5P_DEFAULT for each element. + * </td> + * </tr> + * <tr> + * <td> + * \p memb_name + * </td> + * <td> + * The default string is \Code{%s-X.h5} where \c X is one of the following letters: + * - \c s for #H5FD_MEM_SUPER + * - \c b for #H5FD_MEM_BTREE + * - \c r for #H5FD_MEM_DRAW + * - \c g for #H5FD_MEM_GHEAP + * - \c l for #H5FD_MEM_LHEAP + * - \c o for #H5FD_MEM_OHDR + * </td> + * </tr> + * <tr> + * <td> + * \p memb_addr + * </td> + * <td> + * The default setting is that the address space is equally divided + * among all of the elements: + * - #H5FD_MEM_SUPER \Code{-> 0 * (HADDR_MAX/6)} + * - #H5FD_MEM_BTREE \Code{-> 1 * (HADDR_MAX/6)} + * - #H5FD_MEM_DRAW \Code{-> 2 * (HADDR_MAX/6)} + * - #H5FD_MEM_GHEAP \Code{-> 3 * (HADDR_MAX/6)} + * - #H5FD_MEM_LHEAP \Code{-> 4 * (HADDR_MAX/6)} + * - #H5FD_MEM_OHDR \Code{-> 5 * (HADDR_MAX/6)} + * </td> + * </tr> + * </table> + * + * \par Example: + * The following code sample sets up a multi-file access property list that + * partitions data into meta and raw files, each being one-half of the address:\n + * \code + * H5FD_mem_t mt, memb_map[H5FD_MEM_NTYPES]; + * hid_t memb_fapl[H5FD_MEM_NTYPES]; + * const char *memb[H5FD_MEM_NTYPES]; + * haddr_t memb_addr[H5FD_MEM_NTYPES]; + * + * // The mapping... + * for (mt=0; mt<H5FD_MEM_NTYPES; mt++) { + * memb_map[mt] = H5FD_MEM_SUPER; + * } + * memb_map[H5FD_MEM_DRAW] = H5FD_MEM_DRAW; + * + * // Member information + * memb_fapl[H5FD_MEM_SUPER] = H5P_DEFAULT; + * memb_name[H5FD_MEM_SUPER] = "%s.meta"; + * memb_addr[H5FD_MEM_SUPER] = 0; + * + * memb_fapl[H5FD_MEM_DRAW] = H5P_DEFAULT; + * memb_name[H5FD_MEM_DRAW] = "%s.raw"; + * memb_addr[H5FD_MEM_DRAW] = HADDR_MAX/2; + * + * hid_t fapl = H5Pcreate(H5P_FILE_ACCESS); + * H5Pset_fapl_multi(fapl, memb_map, memb_fapl, + * memb_name, memb_addr, TRUE); + * \endcode + * + * \version 1.6.3 \p memb_name parameter type changed to \Code{const char* const*}. + * \since 1.4.0 + */ H5_DLL herr_t H5Pset_fapl_multi(hid_t fapl_id, const H5FD_mem_t *memb_map, const hid_t *memb_fapl, const char *const *memb_name, const haddr_t *memb_addr, hbool_t relax); + +/** + * \ingroup FAPL + * + * \brief Returns information about the multi-file access property list + * + * \fapl_id + * \param[out] memb_map Maps memory usage types to other memory usage types + * \param[out] memb_fapl Property list for each memory usage type + * \param[out] memb_name Name generator for names of member files + * \param[out] memb_addr The offsets within the virtual address space, from 0 + * (zero) to #HADDR_MAX, at which each type of data storage begins + * \param[out] relax Allows read-only access to incomplete file sets when \c TRUE + * \returns \herr_t + * + * \details H5Pget_fapl_multi() returns information about the multi-file access + * property list. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pget_fapl_multi(hid_t fapl_id, H5FD_mem_t *memb_map /*out*/, hid_t *memb_fapl /*out*/, char **memb_name /*out*/, haddr_t *memb_addr /*out*/, hbool_t *relax /*out*/); + +/** + * \ingroup FAPL + * + * \brief Emulates the old split file driver + * + * \fapl_id{fapl} + * \param[in] meta_ext Metadata filename extension + * \param[in] meta_plist_id File access property list identifier for the metadata file + * \param[in] raw_ext Raw data filename extension + * \param[in] raw_plist_id + * \returns \herr_t + * + * \details H5Pset_fapl_split() is a compatibility function that enables the + * multi-file driver to emulate the split driver from HDF5 Releases 1.0 + * and 1.2. The split file driver stored metadata and raw data in + * separate files but provided no mechanism for separating types of + * metadata. + * + * \p fapl is a file access property list identifier. + * + * \p meta_ext is the filename extension for the metadata file. The + * extension is appended to the name passed to H5FDopen(), usually from + * H5Fcreate() or H5Fopen(), to form the name of the metadata file. If + * the string \Code{%s} is used in the extension, it works like the + * name generator as in H5Pset_fapl_multi(). + * + * \p meta_plist_id is the file access property list identifier for the + * metadata file. + * + * \p raw_ext is the filename extension for the raw data file. The + * extension is appended to the name passed to H5FDopen(), usually from + * H5Fcreate() or H5Fopen(), to form the name of the raw data file. If + * the string \Code{%s} is used in the extension, it works like the + * name generator as in H5Pset_fapl_multi(). + * + * \p raw_plist_id is the file access property list identifier for the + * raw data file. + * + * If a user wishes to check to see whether this driver is in use, the + * user must call H5Pget_driver() and compare the returned value to the + * string #H5FD_MULTI. A positive match will confirm that the multi + * driver is in use; HDF5 provides no mechanism to determine whether it + * was called as the special case invoked by H5Pset_fapl_split(). + * + * \par Example: + * \code + * // Example 1: Both metadata and rawdata files are in the same + * // directory. Use Station1-m.h5 and Station1-r.h5 as + * // the metadata and rawdata files. + * hid_t fapl, fid; + * fapl = H5Pcreate(H5P_FILE_ACCESS); + * H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "-r.h5", H5P_DEFAULT); + * fid=H5Fcreate("Station1",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); + * + * // Example 2: metadata and rawdata files are in different + * // directories. Use PointA-m.h5 and /pfs/PointA-r.h5 as + * // the metadata and rawdata files. + * hid_t fapl, fid; + * fapl = H5Pcreate(H5P_FILE_ACCESS); + * H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT); + * fid=H5Fcreate("PointA",H5F_ACC_TRUNC,H5P_DEFAULT,fapl); + * \endcode + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_split(hid_t fapl, const char *meta_ext, hid_t meta_plist_id, const char *raw_ext, hid_t raw_plist_id); #ifdef __cplusplus diff --git a/src/H5FDpublic.h b/src/H5FDpublic.h index 0fcfcf3..7794f24 100644 --- a/src/H5FDpublic.h +++ b/src/H5FDpublic.h @@ -329,29 +329,113 @@ struct H5FD_t { hbool_t paged_aggr; /* Paged aggregation for file space is enabled or not */ }; -/* Define enum for the source of file image callbacks */ +/** + * Define enum for the source of file image callbacks + */ +//! <!-- [H5FD_file_image_op_t_snip] --> typedef enum { H5FD_FILE_IMAGE_OP_NO_OP, H5FD_FILE_IMAGE_OP_PROPERTY_LIST_SET, + /**< Passed to the \p image_malloc and \p image_memcpy callbacks when a + * file image buffer is to be copied while being set in a file access + * property list (FAPL)*/ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_COPY, + /**< Passed to the \p image_malloc and \p image_memcpy callbacks + * when a file image buffer is to be copied when a FAPL is copied*/ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_GET, + /**<Passed to the \p image_malloc and \p image_memcpy callbacks when + * a file image buffer is to be copied while being retrieved from a FAPL*/ H5FD_FILE_IMAGE_OP_PROPERTY_LIST_CLOSE, + /**<Passed to the \p image_free callback when a file image + * buffer is to be released during a FAPL close operation*/ H5FD_FILE_IMAGE_OP_FILE_OPEN, + /**<Passed to the \p image_malloc and + * \p image_memcpy callbackswhen a + * file image buffer is to be copied during a file open operation \n + * While the file image being opened will typically be copied from a + * FAPL, this need not always be the case. For example, the core file + * driver, also known as the memory file driver, takes its initial + * image from a file.*/ H5FD_FILE_IMAGE_OP_FILE_RESIZE, + /**<Passed to the \p image_realloc callback when a file driver needs + * to resize an image buffer*/ H5FD_FILE_IMAGE_OP_FILE_CLOSE + /**<Passed to the \p image_free callback when an image buffer is to + * be released during a file close operation*/ } H5FD_file_image_op_t; +//! <!-- [H5FD_file_image_op_t_snip] --> -/* Define structure to hold file image callbacks */ +/** + * Define structure to hold file image callbacks + */ +//! <!-- [H5FD_file_image_callbacks_t_snip] --> typedef struct { + /** + * \param[in] size Size in bytes of the file image buffer to allocate + * \param[in] file_image_op A value from H5FD_file_image_op_t indicating + * the operation being performed on the file image + * when this callback is invoked + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_malloc_snip] --> void *(*image_malloc)(size_t size, H5FD_file_image_op_t file_image_op, void *udata); + //! <!-- [image_malloc_snip] --> + /** + * \param[in] dest Address of the destination buffer + * \param[in] src Address of the source buffer + * \param[in] file_image_op A value from #H5FD_file_image_op_t indicating + * the operation being performed on the file image + * when this callback is invoked + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_memcpy_snip] --> void *(*image_memcpy)(void *dest, const void *src, size_t size, H5FD_file_image_op_t file_image_op, void *udata); + //! <!-- [image_memcpy_snip] --> + /** + * \param[in] ptr Pointer to the buffer being reallocated + * \param[in] file_image_op A value from #H5FD_file_image_op_t indicating + * the operation being performed on the file image + * when this callback is invoked + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_realloc_snip] --> void *(*image_realloc)(void *ptr, size_t size, H5FD_file_image_op_t file_image_op, void *udata); + //! <!-- [image_realloc_snip] --> + /** + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [image_free_snip] --> herr_t (*image_free)(void *ptr, H5FD_file_image_op_t file_image_op, void *udata); + //! <!-- [image_free_snip] --> + /** + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [udata_copy_snip] --> void *(*udata_copy)(void *udata); + //! <!-- [udata_copy_snip] --> + /** + * \param[in] udata Value passed in in the H5Pset_file_image_callbacks + * parameter \p udata + */ + //! <!-- [udata_free_snip] --> herr_t (*udata_free)(void *udata); + //! <!-- [udata_free_snip] --> + /** + * \brief The final field in the #H5FD_file_image_callbacks_t struct, + * provides a pointer to user-defined data. This pointer will be + * passed to the image_malloc, image_memcpy, image_realloc, and + * image_free callbacks. Define udata as NULL if no user-defined + * data is provided. + */ void *udata; } H5FD_file_image_callbacks_t; +//! <!-- [H5FD_file_image_callbacks_t_snip] --> #ifdef __cplusplus extern "C" { diff --git a/src/H5FDros3.h b/src/H5FDros3.h index 3ef6b8a..8e42ca2 100644 --- a/src/H5FDros3.h +++ b/src/H5FDros3.h @@ -89,8 +89,20 @@ typedef struct H5FD_ros3_fapl_t { extern "C" { #endif -H5_DLL hid_t H5FD_ros3_init(void); +H5_DLL hid_t H5FD_ros3_init(void); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pget_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa_out); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pset_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa); #ifdef __cplusplus diff --git a/src/H5FDsplitter.h b/src/H5FDsplitter.h index a201116..ee6e7c5 100644 --- a/src/H5FDsplitter.h +++ b/src/H5FDsplitter.h @@ -87,8 +87,20 @@ typedef struct H5FD_splitter_vfd_config_t { #ifdef __cplusplus extern "C" { #endif -H5_DLL hid_t H5FD_splitter_init(void); +H5_DLL hid_t H5FD_splitter_init(void); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pset_fapl_splitter(hid_t fapl_id, H5FD_splitter_vfd_config_t *config_ptr); + +/** + * \ingroup FAPL + * + * \todo Add missing documentation + */ H5_DLL herr_t H5Pget_fapl_splitter(hid_t fapl_id, H5FD_splitter_vfd_config_t *config_ptr); #ifdef __cplusplus diff --git a/src/H5FDstdio.h b/src/H5FDstdio.h index b3e06bb..9db92ed 100644 --- a/src/H5FDstdio.h +++ b/src/H5FDstdio.h @@ -28,7 +28,21 @@ extern "C" { #endif -H5_DLL hid_t H5FD_stdio_init(void); +H5_DLL hid_t H5FD_stdio_init(void); +/** + * \ingroup FAPL + * + * \brief Sets the standard I/O driver + * + * \fapl_id + * \returns \herr_t + * + * \details H5Pset_fapl_stdio() modifies the file access property list to use + * the standard I/O driver, H5FDstdio(). + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_stdio(hid_t fapl_id); #ifdef __cplusplus diff --git a/src/H5FDwindows.h b/src/H5FDwindows.h index c1c4654..79e73b6 100644 --- a/src/H5FDwindows.h +++ b/src/H5FDwindows.h @@ -27,6 +27,36 @@ extern "C" { #endif /* __cplusplus */ +/** + * \ingroup FAPL + * + * \brief Sets the Windows I/O driver + * + * \fapl_id + * \returns \herr_t + * + * \details H5Pset_fapl_windows() sets the default HDF5 Windows I/O driver on + * Windows systems. + * + * Since the HDF5 library uses this driver, #H5FD_WINDOWS, by default + * on Windows systems, it is not normally necessary for a user + * application to call H5Pset_fapl_windows(). While it is not + * recommended, there may be times when a user chooses to set a + * different HDF5 driver, such as the standard I/O driver (#H5FD_STDIO) + * or the sec2 driver (#H5FD_SEC2), in a Windows + * application. H5Pset_fapl_windows() is provided so that the + * application can return to the Windows I/O driver when the time + * comes. + * + * Only the Windows driver is tested on Windows systems; other drivers + * are used at the application’s and the user’s risk. + * + * Furthermore, the Windows driver is tested and available only on + * Windows systems; it is not available on non-Windows systems. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pset_fapl_windows(hid_t fapl_id); #ifdef __cplusplus diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h index 33c302a..7f0299a 100644 --- a/src/H5Fmodule.h +++ b/src/H5Fmodule.h @@ -31,8 +31,34 @@ /** * \defgroup H5F H5F - * \brief File Interface - * \todo Describe concisely what the functions in this module are about. + * + * Use the functions in this module to manage HDF5 files. + * + * In the code snippets below, we show the skeletal life cycle of an HDF5 file, + * when creating a new file (left) or when opening an existing file (right). + * File creation is essentially controlled through \ref FCPL, and file access to + * new and existing files is controlled through \ref FAPL. The file \c name and + * creation or access \c mode control the interaction with the underlying + * storage such as file systems. + * + * \Emph{Proper error handling is part of the life cycle.} + * <table> + * <tr><th>Create</th><th>Open</th></tr> + * <tr valign="top"> + * <td> + * \snippet H5F_examples.c life_cycle + * </td> + * <td> + * \snippet H5F_examples.c life_cycle_w_open + * </td> + * </tr> + * </table> + * + * In addition to general file management functions, there are three categories + * of functions that deal with advanced file management tasks and use cases: + * 1. The control of the HDF5 \ref MDC + * 2. The use of (MPI-) \ref PH5F HDF5 + * 3. The \ref SWMR pattern * * \defgroup MDC Metadata Cache * \ingroup H5F diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h index 24fe350..164b412 100644 --- a/src/H5Fpublic.h +++ b/src/H5Fpublic.h @@ -47,27 +47,23 @@ * We're assuming that these constants are used rather early in the hdf5 * session. */ -#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /**< absence of rdwr => rd-only */ -#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /**< open for read and write */ -#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /**< overwrite existing files */ -#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /**< fail if file already exists*/ +#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /**< Absence of RDWR: read-only */ +#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /**< Open for read and write */ +#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /**< Overwrite existing files */ +#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /**< Fail if file already exists*/ /* NOTE: 0x0008u was H5F_ACC_DEBUG, now deprecated */ -#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /**< create non-existing files */ +#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /**< Create non-existing files */ #define H5F_ACC_SWMR_WRITE \ - (H5CHECK 0x0020u) /**< indicate that this file is open for writing in a \ - single-writer/multi-reader (SWMR) scenario. \ - Note that the process(es) opening the file for reading must \ - open the file with RDONLY access, and use the special "SWMR_READ" \ - access flag. */ + (H5CHECK 0x0020u) /**< Indicate that this file is open for writing in a \ + * single-writer/multi-reader (SWMR) scenario. \ + * Note that the process(es) opening the file for reading \ + * must open the file with #H5F_ACC_RDONLY and use the \ + * #H5F_ACC_SWMR_READ access flag. */ #define H5F_ACC_SWMR_READ \ - (H5CHECK 0x0040u) /**< indicate that this file is \ - * open for reading in a \ - * single-writer/multi-reader (SWMR) \ - * scenario. Note that the \ - * process(es) opening the file \ - * for SWMR reading must also \ - * open the file with the RDONLY \ - * flag. */ + (H5CHECK 0x0040u) /**< Indicate that this file is open for reading in a \ + * single-writer/multi-reader (SWMR) scenario. Note that \ + * the process(es) opening the file for SWMR reading must \ + * also open the file with the #H5F_ACC_RDONLY flag. */ /** * Default property list identifier @@ -91,7 +87,7 @@ #define H5F_FAMILY_DEFAULT (hsize_t)0 #ifdef H5_HAVE_PARALLEL -/* +/** * Use this constant string as the MPI_Info key to set H5Fmpio debug flags. * To turn on H5Fmpio debug flags, set the MPI_Info value with this key to * have the value of a string consisting of the characters that turn on the @@ -101,11 +97,12 @@ #endif /* H5_HAVE_PARALLEL */ /** - * The difference between a single file and a set of mounted files + * The scope of an operation such as H5Fflush(), e.g., + * a single file vs. a set of mounted files */ typedef enum H5F_scope_t { - H5F_SCOPE_LOCAL = 0, /**< specified file handle only */ - H5F_SCOPE_GLOBAL = 1 /**< entire virtual file */ + H5F_SCOPE_LOCAL = 0, /**< The specified file handle only */ + H5F_SCOPE_GLOBAL = 1 /**< The entire virtual file */ } H5F_scope_t; /** @@ -117,16 +114,16 @@ typedef enum H5F_scope_t { * How does file close behave? */ typedef enum H5F_close_degree_t { - H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlining VFL */ + H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlying VFD */ H5F_CLOSE_WEAK = 1, /**< File closes only after all opened objects are closed */ - H5F_CLOSE_SEMI = 2, /**< If no opened objects, file is close; otherwise, file close fails */ + H5F_CLOSE_SEMI = 2, /**< If no opened objects, file is closed; otherwise, file close fails */ H5F_CLOSE_STRONG = 3 /**< If there are opened objects, close them first, then close file */ } H5F_close_degree_t; /** * Current "global" information about file */ -//! [H5F_info2_t_snip] +//! <!-- [H5F_info2_t_snip] --> typedef struct H5F_info2_t { struct { unsigned version; /**< Superblock version # */ @@ -144,7 +141,7 @@ typedef struct H5F_info2_t { H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */ } sohm; } H5F_info2_t; -//! [H5F_info2_t_snip] +//! <!-- [H5F_info2_t_snip] --> /** * Types of allocation requests. The values larger than #H5FD_MEM_DEFAULT @@ -176,12 +173,12 @@ typedef enum H5F_mem_t { /** * Free space section information */ -//! [H5F_sect_info_t_snip] +//! <!-- [H5F_sect_info_t_snip] --> typedef struct H5F_sect_info_t { haddr_t addr; /**< Address of free space section */ hsize_t size; /**< Size of free space section */ } H5F_sect_info_t; -//! [H5F_sect_info_t_snip] +//! <!-- [H5F_sect_info_t_snip] --> /** * Library's format versions @@ -193,7 +190,7 @@ typedef enum H5F_libver_t { H5F_LIBVER_V110 = 2, /**< Use the latest v110 format for storing objects */ H5F_LIBVER_V112 = 3, /**< Use the latest v112 format for storing objects */ H5F_LIBVER_V114 = 4, /**< Use the latest v114 format for storing objects */ - H5F_LIBVER_NBOUNDS + H5F_LIBVER_NBOUNDS /**< Sentinel */ } H5F_libver_t; #define H5F_LIBVER_LATEST H5F_LIBVER_V114 @@ -201,7 +198,7 @@ typedef enum H5F_libver_t { /** * File space handling strategy */ -//! [H5F_fspace_strategy_t_snip] +//! <!-- [H5F_fspace_strategy_t_snip] --> typedef enum H5F_fspace_strategy_t { H5F_FSPACE_STRATEGY_FSM_AGGR = 0, /**< Mechanisms: free-space managers, aggregators, and virtual file drivers This is the library default when not set */ @@ -211,7 +208,7 @@ typedef enum H5F_fspace_strategy_t { H5F_FSPACE_STRATEGY_NONE = 3, /**< Mechanisms: virtual file drivers */ H5F_FSPACE_STRATEGY_NTYPES /**< Sentinel */ } H5F_fspace_strategy_t; -//! [H5F_fspace_strategy_t_snip] +//! <!-- [H5F_fspace_strategy_t_snip] --> /** * File space handling strategy for release 1.10.0 @@ -228,7 +225,7 @@ typedef enum H5F_file_space_type_t { H5F_FILE_SPACE_NTYPES /**< Sentinel */ } H5F_file_space_type_t; -//! [H5F_retry_info_t_snip] +//! <!-- [H5F_retry_info_t_snip] --> #define H5F_NUM_METADATA_READ_RETRY_TYPES 21 /** @@ -239,7 +236,7 @@ typedef struct H5F_retry_info_t { unsigned nbins; uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES]; } H5F_retry_info_t; -//! [H5F_retry_info_t_snip] +//! <!-- [H5F_retry_info_t_snip] --> /** * Callback for H5Pset_object_flush_cb() in a file access property list @@ -277,11 +274,6 @@ extern "C" { */ H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id); /** - * \example H5Fcreate.c - * After creating an HDF5 file with H5Fcreate(), we close it with - * H5Fclose(). - */ -/** * \ingroup H5F * * \brief Creates an HDF5 file @@ -321,7 +313,8 @@ H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id); * this file identifier should be closed by calling H5Fclose() when * it is no longer needed. * - * \include H5Fcreate.c + * \par Example + * \snippet H5F_examples.c minimal * * \note #H5F_ACC_TRUNC and #H5F_ACC_EXCL are mutually exclusive; use * exactly one. @@ -359,6 +352,11 @@ H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id); * */ H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Fcreate} + */ H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigned app_line, const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t es_id); /** @@ -408,6 +406,9 @@ H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigne * identifier should be closed by calling H5Fclose() when it is no * longer needed. * + * \par Example + * \snippet H5F_examples.c open + * * \note #H5F_ACC_RDWR and #H5F_ACC_RDONLY are mutually exclusive; use * exactly one. * @@ -451,6 +452,11 @@ H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigne * */ H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Fopen} + */ H5_DLL hid_t H5Fopen_async(const char *app_file, const char *app_func, unsigned app_line, const char *filename, unsigned flags, hid_t access_plist, hid_t es_id); /** @@ -479,6 +485,11 @@ H5_DLL hid_t H5Fopen_async(const char *app_file, const char *app_func, unsigned * */ H5_DLL hid_t H5Freopen(hid_t file_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Freopen} + */ H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t file_id, hid_t es_id); /** @@ -503,6 +514,9 @@ H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigne * global or local. Valid values are as follows: * \scopes * + * \par Example + * \snippet H5F_examples.c flush + * * \attention HDF5 does not possess full control over buffering. H5Fflush() * flushes the internal HDF5 buffers then asks the operating system * (the OS) to flush the system buffers for the open files. After @@ -511,13 +525,13 @@ H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigne * */ H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope); -H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigned app_line, hid_t object_id, - H5F_scope_t scope, hid_t es_id); /** - * \example H5Fclose.c - * After creating an HDF5 file with H5Fcreate(), we close it with - * H5Fclose(). + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Fflush} */ +H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigned app_line, hid_t object_id, + H5F_scope_t scope, hid_t es_id); /** * \ingroup H5F * @@ -534,8 +548,8 @@ H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigne * identifier, or shared datatype identifier), the file will be fully * closed and access will end. * - * Use H5Fclose() as shown in the following example: - * \include H5Fclose.c + * \par Example + * \snippet H5F_examples.c minimal * * \note \Bold{Delayed close:} Note the following deviation from the * above-described behavior. If H5Fclose() is called for a file but one @@ -562,6 +576,11 @@ H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigne * */ H5_DLL herr_t H5Fclose(hid_t file_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Fclose} + */ H5_DLL herr_t H5Fclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t file_id, hid_t es_id); /** @@ -655,7 +674,7 @@ H5_DLL hid_t H5Fget_access_plist(hid_t file_id); * \note The function will not return an error if intent is NULL; it will * simply do nothing. * - * \version 1.10.0 C function enhanced to work with SWMR functionality. + * \version 1.10.0 Function enhanced to work with SWMR functionality. * * \since 1.8.0 * @@ -707,7 +726,7 @@ H5_DLL herr_t H5Fget_fileno(hid_t file_id, unsigned long *fileno); * \c (#H5F_OBJ_DATASET|#H5F_OBJ_GROUP) would call for datasets and * groups. * - * \version 1.6.8, 1.8.2 C function return type changed to \c ssize_t. + * \version 1.6.8, 1.8.2 Function return type changed to \c ssize_t. * \version 1.6.5 #H5F_OBJ_LOCAL has been added as a qualifier on the types * of objects to be counted. #H5F_OBJ_LOCAL restricts the * search to objects opened through current file identifier. @@ -745,9 +764,9 @@ H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types); * To retrieve a count of open objects, use the H5Fget_obj_count() * function. This count can be used to set the \p max_objs parameter. * - * \version 1.8.2 C function return type changed to \c ssize_t and \p + * \version 1.8.2 Function return type changed to \c ssize_t and \p * max_objs parameter datatype changed to \c size_t. - * \version 1.6.8 C function return type changed to \c ssize_t and \p + * \version 1.6.8 Function return type changed to \c ssize_t and \p * max_objs parameter datatype changed to \c size_t. * \since 1.6.0 * @@ -798,6 +817,9 @@ H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle); * attribute, then the file will be mounted at the location where the * attribute, dataset, or named datatype is attached. * + * \par Example + * \snippet H5F_examples.c mount + * * \note To date, no file mount properties have been defined in HDF5. The * proper value to pass for \p plist is #H5P_DEFAULT, indicating the * default file mount property list. @@ -868,8 +890,6 @@ H5_DLL hssize_t H5Fget_freespace(hid_t file_id); * if any, the HDF5 portion of the file, and any data that may have * been appended beyond the data written through the HDF5 library. * - * \version 1.6.3 Fortran subroutine introduced in this release. - * * \since 1.6.3 * */ @@ -948,9 +968,7 @@ H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment); * * \note \Bold{Recommended Reading:} This function is part of the file image * operations feature set. It is highly recommended to study the guide - * "HDF5 File Image Operations" before using this feature set.\n See the - * "See Also" section below for links to other elements of HDF5 file - * image operations. \todo Fix the references. + * \ref_file_image_ops before using this feature set. * * \attention H5Pget_file_image() will fail, returning a negative value, if the * file is too large for the supplied buffer. @@ -958,8 +976,6 @@ H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment); * \see H5LTopen_file_image(), H5Pset_file_image(), H5Pget_file_image(), * H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks() * - * \version 1.8.13 Fortran subroutine added in this release. - * * \since 1.8.0 * */ @@ -976,197 +992,18 @@ H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len); * \ref H5AC-cache-config-t "here". * \return \herr_t * + * \note The \c in direction applies only to the H5AC_cache_config_t::version + * field. All other fields are out parameters. + * * \details H5Fget_mdc_config() loads the current metadata cache configuration * into the instance of H5AC_cache_config_t pointed to by the \p config_ptr - * parameter. - * - * Note that the \c version field of \p config_ptr must be initialized - * --this allows the library to support old versions of the H5AC_cache_config_t - * structure. - * - * \par General configuration section - * <table> - * <tr> - * <td><em>int</em> <code>version</code> </td> - * <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This field should - * be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined in H5ACpublic.h).</td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>rpt_fcn_enabled</code> </td> - * <td><p>OUT: Boolean flag indicating whether the adaptive cache resize report function is enabled. This - * field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is - * reported via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.</p><p>The - * report function is not supported code, and can be expected to change between versions of the - * library. Use it at your own risk.</p></td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>open_trace_file</code> </td> - * <td>OUT: Boolean field indicating whether the <code>trace_file_name</code> field should be used to - * open a trace file for the cache. This field will always be set to <code>0</code> in this - * context.</td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>close_trace_file</code> </td> - * <td>OUT: Boolean field indicating whether the current trace file (if any) should be closed. This field - * will always be set to <code>0</code> in this context.</td></tr> - * <tr> - * <td><em>char*</em><code>trace_file_name</code> </td> - * <td>OUT: Full path name of the trace file to be opened if the <code>open_trace_file</code> field is - * set to <code>1</code>. This field will always be set to the empty string in this context.</td></tr> - * <tr> - * <td><em>hbool_t</em> <code>evictions_enabled</code> </td> - * <td>OUT: Boolean flag indicating whether metadata cache entry evictions are - * enabled.</td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>set_initial_size</code> </td> - * <td>OUT: Boolean flag indicating whether the cache should be created with a user specified initial - * maximum size.<p>If the configuration is loaded from the cache, this flag will always be set - * to <code>0</code>.</p></td> - * </tr> - * <tr> - * <td><em>size_t</em> <code>initial_size</code> </td> - * <td>OUT: Initial maximum size of the cache in bytes, if applicable.<p>If the configuration is loaded - * from the cache, this field will contain the cache maximum size as of the time of the - * call.</p></td> - * </tr> - * <tr> - * <td><em>double</em> <code>min_clean_fraction</code> </td> - * <td>OUT: Float value specifying the minimum fraction of the cache that must be kept either clean or - * empty when possible.</td> - * </tr> - * <tr> - * <td><em>size_t</em> <code>max_size</code> </td> - * <td>OUT: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select - * as the maximum cache size.</td> - * </tr> - * <tr> - * <td><em>size_t</em> <code>min_size</code> </td> - * <td>OUT: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select - * as the maximum cache size.</td> - * </tr> - * <tr> - * <td><em>long int</em> <code>epoch_length</code> </td> - * <td>OUT: Number of cache accesses between runs of the adaptive cache resize - * code.</td> - * </tr> - * </table> - * - * \par Increment configuration section - * <table> - * <tr> - * <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code> </td> - * <td>OUT: Enumerated value indicating the operational mode of the automatic cache size increase code. - * At present, only the following values are legal:<p>\c H5C_incr__off: Automatic cache size increase - * is disabled.</p><p>\c H5C_incr__threshold: Automatic cache size increase is enabled using the hit - * rate threshold algorithm.</p></td> - * </tr> - * <tr> - * <td><em>double</em> <code>lower_hr_threshold</code> </td> - * <td>OUT: Hit rate threshold used in the hit rate threshold cache size increase algorithm.</td> - * </tr> - * <tr> - * <td><em>double</em> <code>increment</code> </td> - * <td>OUT: The factor by which the current maximum cache size is multiplied to obtain an initial new - * maximum cache size if a size increase is triggered in the hit rate threshold cache size increase - * algorithm.</td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>apply_max_increment</code> </td> - * <td>OUT: Boolean flag indicating whether an upper limit will be applied to the size of cache size - * increases.</td> - * </tr> - * <tr> - * <td><em>size_t</em> <code>max_increment</code> </td> - * <td>OUT: The maximum number of bytes by which the maximum cache size can be increased in a single step - * -- if applicable.</td> - * </tr> - * <tr> - * <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code> </td> - * <td>OUT: Enumerated value indicating the operational mode of the flash cache size increase code. At - * present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is - * disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add - * space algorithm.</p></td> - * </tr> - * <tr> - * <td><em>double</em> <code>flash_threshold</code> </td> - * <td>OUT: The factor by which the current maximum cache size is multiplied to obtain the minimum size - * entry / entry size increase which may trigger a flash cache size - * increase.</td> - * </tr> - * <tr> - * <td><em>double</em> <code>flash_multiple</code> </td> - * <td>OUT: The factor by which the size of the triggering entry / entry size increase is multiplied to - * obtain the initial cache size increment. This increment may be reduced to reflect existing free - * space in the cache and the <code>max_size</code> field above.</td> - * </tr> - * </table> - * - * \par Decrement configuration section - * <table> - * <tr><td colspan="2"><strong>Decrement configuration - * section:</strong></td> - * </tr> - * <tr> - * <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code> </td> - * <td>OUT: Enumerated value indicating the operational mode of the automatic cache size decrease code. - * At present, the following values are legal:<p>H5C_decr__off: Automatic cache size decrease is - * disabled, and the remaining decrement fields are ignored.</p><p>H5C_decr__threshold: Automatic - * cache size decrease is enabled using the hit rate threshold algorithm.</p><p>H5C_decr__age_out: - * Automatic cache size decrease is enabled using the ageout algorithm.</p> - * <p>H5C_decr__age_out_with_threshold: Automatic cache size decrease is enabled using the ageout - * with hit rate threshold algorithm</p></td> - * </tr> - * <tr><td><em>double</em> <code>upper_hr_threshold</code> </td> - * <td>OUT: Upper hit rate threshold. This value is only used if the decr_mode is either - * H5C_decr__threshold or H5C_decr__age_out_with_threshold.</td> - * </tr> - * <tr> - * <td><em>double</em> <code>decrement</code> </td> - * <td>OUT: Factor by which the current max cache size is multiplied to obtain an initial value for the - * new cache size when cache size reduction is triggered in the hit rate threshold cache size reduction - * algorithm.</td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>apply_max_decrement</code> </td> - * <td>OUT: Boolean flag indicating whether an upper limit should be applied to the size of cache size - * decreases.</td> - * </tr> - * <tr> - * <td><em>size_t</em> <code>max_decrement</code> </td> - * <td>OUT: The maximum number of bytes by which cache size can be decreased if any single step, if - * applicable.</td> - * </tr> - * <tr> - * <td><em>int</em> <code>epochs_before_eviction</code> </td> - * <td>OUT: The minimum number of epochs that an entry must reside unaccessed in cache before being - * evicted under either of the ageout cache size reduction algorithms.</td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>apply_empty_reserve</code> </td> - * <td>OUT: Boolean flag indicating whether an empty reserve should be maintained under either of the - * ageout cache size reduction algorithms.</td> - * </tr> - * <tr> - * <td><em>double</em> <code>empty_reserve</code> </td> - * <td>OUT: Empty reserve for use with the ageout cache size reduction algorithms, if applicable.</td> - * </tr> - * </table> - * - * \par Parallel configuration section - * <table> - * <tr><td><em>int</em> <code>dirty_bytes_threshold</code> </td> - * <td>OUT: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the - * metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the - * number of bytes of dirty metadata created since the last synchronization exceeds this - * limit.</p></td> - * </tr> - * </table> + * parameter.\n + * The fields of the H5AC_cache_config_t structure are shown below: + * \snippet H5ACpublic.h H5AC_cache_config_t_snip + * \click4more * * \since 1.8.0 * - * \todo Fix the reference! - * */ H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); /** @@ -1183,240 +1020,11 @@ H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); * * \details H5Fset_mdc_config() attempts to configure the file's metadata cache * according configuration supplied in \p config_ptr. - * - * \par General configuration fields - * <table> - * <tr> - * <td><em>int</em> <code>version</code></td> - * <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This - * field should be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined - * in H5ACpublic.h).</td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>rpt_fcn_enabled</code></td> - * <td>IN: Boolean flag indicating whether the adaptive cache resize report function is enabled. This - * field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is - * reported via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.<p>The report - * function is not supported code, and can be expected to change between versions of the library. Use - * it at your own risk.</p></td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>open_trace_File</code></td> - * <td>IN: Boolean field indicating whether the <code>trace_file_name</code> field should be used to open - * a trace file for the cache.<p>The trace file is a debuging feature that allows the capture of top - * level metadata cache requests for purposes of debugging and/or optimization. This field should - * <p>This field should only normally be set to <code>0</code>, as trace file collection imposes - * considerable overhead.</p> be set to <code>1</code> when the <code>trace_file_name</code> contains - * the full path of the desired trace file, and either there is no open trace file on the cache, or the - * <code>close_trace_file</code> field is also <code>1</code>.</p><p>The trace file feature is - * unsupported unless used at the direction of The HDF Group. It is intended to allow The HDF Group to - * collect a trace of cache activity in cases of occult failures and/or poor performance seen in the - * field, so as to aid in reproduction in the lab. If you use it absent the direction of The HDF Group, - * you are on your own.</p></td> - * </tr> - * <tr><td><em>hbool_t</em> <code>close_trace_file</code></td> - * <td>IN: Boolean field indicating whether the current trace file (if any) should be closed.<p>See the - * above comments on the <code>open_trace_file</code> field. This field should be set to - * <code>0</code> unless there is an open trace file on the cache that you wish to close.</p><p>The - * trace file feature is unsupported unless used at the direction of The HDF Group. It is intended to - * allow The HDF Group to collect a trace of cache activity in cases of occult failures and/or poor - * performance seen in the field, so as to aid in reproduction in the lab. If you use it absent the - * direction of The HDF Group, you are on your own.</p></td> - * </tr> - * <tr> - * <td><em>char</em> <code>trace_file_name[]</code></td> - * <td>IN: Full path of the trace file to be opened if the <code>open_trace_file</code> field is set - * to <code>1</code>.<p>In the parallel case, an ascii representation of the mpi rank of the process - * will be appended to the file name to yield a unique trace file name for each process.</p><p>The - * length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN characters.</p><p>The trace file - * feature is unsupported unless used at the direction of The HDF Group. It is intended to allow The - * HDF Group to collect a trace of cache activity in cases of occult failures and/or poor performance - * seen in the field, so as to aid in reproduction in the lab. If you use it absent the direction of - * The HDF Group, you are on your own.</p></td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>evictions_enabled</code></td> - * <td>IN: A boolean flag indicating whether evictions from the metadata cache are enabled. This flag is - * initially set to enabled (<code>1</code>).<p>In rare circumstances, the raw data throughput - * requirements may be so high that the user wishes to postpone metadata writes so as to reserve I/O - * throughput for raw data. The <code>evictions_enabled</code> field exists to allow this. However, - * this is an extreme step, and you have no business doing it unless you have read the User Guide - * section on metadata caching, and have considered all other options carefully.</p><p>The - * <code>evictions_enabled</code> field may not be set to disabled (<code>0</code>) unless all adaptive - * cache resizing code is disabled via the <code>incr_mode</code>, <code>flash_incr_mode</code>, and - * <code>decr_mode</code> fields.</p><p>When this flag is set to disabled (<code>0</code>), the - * metadata cache will not attempt to evict entries to make space for new entries, and thus will grow - * without bound.</p><p>Evictions will be re-enabled when this field is set back to <code>1</code>. - * This should be done as soon as possible.</p></td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>set_initial_size</code></td> - * <td>IN: Boolean flag indicating whether the cache should be forced to the user specified initial - * size.</td> - * </tr> - * <tr> - * <td><em>size_t</em> <code>initial_size</code></td> - * <td>IN: If <code>set_initial_size</code> is set to <code>1</code>, then <code>initial_size</code> must - * contain the desired initial size in bytes. This value must lie in the closed interval - * <code>[min_size, max_size]</code>. (see below)</td> - * </tr> - * <tr><td><em>double</em> <code>min_clean_fraction</code></td> - * <td>IN: This field specifies the minimum fraction of the cache that must be kept either clean or - * empty.<p>The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to start in the serial - * case. In the parallel case, a larger value is needed -- see <a - * href="/display/HDF5/Metadata+Caching+in+HDF5">Metadata Caching in HDF5</a> in the collection - * "Advanced Topics in HDF5."</p></td> - * </tr> - * <tr><td><em>size_t</em> <code>max_size</code></td> - * <td>IN: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select - * as the maximum cache size.</td> - * </tr> - * <tr> - * <td><em>size_t</em> <code>min_size</code></td> - * <td>IN: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select - * as the maximum cache size.</td> - * </tr> - * <tr><td><em>long int</em> <code>epoch_length</code></td> - * <td>IN: Number of cache accesses between runs of the adaptive cache resize code. 50,000 is a good - * starting number.</td> - * </tr> - * </table> - * - * \par Increment configuration fields - * <table> - * <tr> - * <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code></td> - * <td>IN: Enumerated value indicating the operational mode of the automatic cache size increase code. At - * present, only two values are legal:<p>\c H5C_incr__off: Automatic cache size increase is disabled, - * and the remaining increment fields are ignored.</p><p>\c H5C_incr__threshold: Automatic cache size - * increase is enabled using the hit rate threshold algorithm.</p></td> - * </tr> - * <tr> - * <td><em>double</em> <code>lower_hr_threshold</code></td> - * <td>IN: Hit rate threshold used by the hit rate threshold cache size increment algorithm.<p>When the - * hit rate over an epoch is below this threshold and the cache is full, the maximum size of the - * cache is multiplied by increment (below), and then clipped as necessary to stay within max_size, and - * possibly max_increment.</p><p>This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good - * starting point.</p></td> - * </tr> - * <tr> - * <td><em>double</em> <code>increment</code></td> - * <td>IN: Factor by which the hit rate threshold cache size increment algorithm multiplies the current - * maximum cache size to obtain a tentative new cache size.<p>The actual cache size increase will be - * clipped to satisfy the max_size specified in the general configuration, and possibly max_increment - * below.</p><p>The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable - * value.</p><p>If you set it to 1.0, you will effectively disable cache size increases.</p></td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>apply_max_increment</code></td> - * <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size - * increases.</td> - * </tr> - * <tr> - * <td><em>size_t</em> <code>max_increment</code></td> - * <td>IN: Maximum number of bytes by which cache size can be increased in a single step -- if - * applicable.</td> - * </tr> - * <tr> - * <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code></td> - * <td>IN: Enumerated value indicating the operational mode of the flash cache size increase code. At - * present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is - * disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add - * space algorithm.</p></td> - * </tr> - * <tr> - * <td><em>double</em> <code>flash_threshold</code></td> - * <td>IN: The factor by which the current maximum cache size is multiplied to obtain the minimum size - * entry / entry size increase which may trigger a flash cache size increase.<p>At present, this value - * must lie in the range [0.1, 1.0].</p></td> - * </tr> - * <tr> - * <td><em>double</em> <code>flash_multiple</code></td> - * <td>IN: The factor by which the size of the triggering entry / entry size increase is multiplied to - * obtain the initial cache size increment. This increment may be reduced to reflect existing free - * space in the cache and the <code>max_size</code> field above.<p>At present, this field must lie in - * the range [0.1, 10.0].</p></td> - * </tr> - * </table> - * - * \par Decrement configuration fields - * <table> - * <tr> - * <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code></td> - * <td>IN: Enumerated value indicating the operational mode of the automatic cache size decrease code. At - * present, the following values are legal:<p>\c H5C_decr__off: Automatic cache size decrease is - * disabled.</p><p>\c H5C_decr__threshold: Automatic cache size decrease is enabled using the hit - * rate threshold algorithm.</p><p>\c H5C_decr__age_out: Automatic cache size decrease is enabled using - * the ageout algorithm.</p><p>\c H5C_decr__age_out_with_threshold: Automatic cache size decrease is - * enabled using the ageout with hit rate threshold algorithm</p></td> - * </tr> - * <tr> - * <td><em>double</em> <code>upper_hr_threshold</code></td> - * <td>IN: Hit rate threshold for the hit rate threshold and ageout with hit rate threshold cache size - * decrement algorithms.<p>When \c decr_mode is \c H5C_decr__threshold, and the hit rate over a given - * epoch exceeds the supplied threshold, the current maximum cache size is multiplied by decrement to - * obtain a tentative new (and smaller) maximum cache size.</p><p>When \c decr_mode is \c - * H5C_decr__age_out_with_threshold, there is no attempt to find and evict aged out entries unless the - * hit rate in the previous epoch exceeded the supplied threshold.</p><p>This field must lie in the - * interval [0.0, 1.0].</p><p>For \c H5C_incr__threshold, .9995 or .99995 is a good place to - * start.</p><p>For \c H5C_decr__age_out_with_threshold, .999 might be more useful.</p></td> - * </tr> - * <tr> - * <td><em>double</em> <code>decrement</code></td> - * <td>IN: In the hit rate threshold cache size decrease algorithm, this parameter contains the factor by - * which the current max cache size is multiplied to produce a tentative new cache size.<p>The actual - * cache size decrease will be clipped to satisfy the min_size specified in the general configuration, - * and possibly max_decrement below.</p><p>The parameter must be be in the interval - * [0.0, 1.0].</p><p>If you set it to 1.0, you will effectively disable cache size decreases. 0.9 is a - * reasonable starting point.</p></td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>apply_max_decrement</code></td> - * <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size - * decreases.</td> - * </tr> - * <tr> - * <td><em>size_t</em> <code>max_decrement</code></td> - * <td>IN: Maximum number of bytes by which the maximum cache size can be decreased in any single step -- - * if applicable.</td> - * </tr> - * <tr> - * <td><em>int</em> <code>epochs_before_eviction</code></td> - * <td>IN: In the ageout based cache size reduction algorithms, this field contains the minimum number of - * epochs an entry must remain unaccessed in cache before the cache size reduction algorithm tries to - * evict it. 3 is a reasonable value.</td> - * </tr> - * <tr> - * <td><em>hbool_t</em> <code>apply_empty_reserve</code></td> - * <td>IN: Boolean flag indicating whether the ageout based decrement algorithms will maintain a empty - * reserve when decreasing cache size.</td> - * </tr> - * <tr> - * <td><em>double</em> <code>empty_reserve</code></td> - * <td>IN: Empty reserve as a fraction of maximum cache size if applicable.<p>When so directed, the - * ageout based algorithms will not decrease the maximum cache size unless the empty reserve can be - * met.</p><p>The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to - * start.</p></td> - * </tr> - * </table> - * - * \par Parallel configuration fields - * <table> - * <tr> - * <td><em>int</em> <code>dirty_bytes_threshold</code></td> - * <td>IN: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the - * metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the - * number of bytes of dirty metadata created since the last synchronization exceeds this - * limit.</p><p>This field only applies to the parallel case. While it is ignored elsewhere, it can - * still draw a value out of bounds error.</p><p>It must be consistant across all caches on any given - * file.</p><p>By default, this field is set to 256 KB. It shouldn't be more than half the current - * maximum cache size times the minimum clean fraction.</p></td> - * </tr> - * </table> + * \snippet H5ACpublic.h H5AC_cache_config_t_snip + * \click4more * * \since 1.8.0 * - * \todo Fix the MDC document reference! */ H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); /** @@ -1495,13 +1103,12 @@ H5_DLL herr_t H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_c * is enabled. However, the call should be useful if you choose to control metadata cache size from your * program. * - * See "Metadata Caching in HDF5" for details about the metadata cache and the adaptive cache resizing + * See \ref_mdc_in_hdf5 for details about the metadata cache and the adaptive cache resizing * algorithms. If you have not read, understood, and thought about the material covered in that * documentation, * you should not be using this API call. * \endparblock * - * \todo Fix the MDC document reference! */ H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id); /** @@ -1797,6 +1404,9 @@ H5_DLL herr_t H5Fclear_elink_file_cache(hid_t file_id); * For the parameters \p low and \p high, see the description for * H5Pset_libver_bounds(). * + * \par Example + * \snippet H5F_examples.c libver_bounds + * * \since 1.10.2 * */ @@ -1835,7 +1445,7 @@ H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t * list, and H5Fget_mdc_logging_status() will return the current state of * the logging flags. * - * The log format is described in the \Emph{Metadata Cache Logging} document. + * The log format is described in the \ref_mdc_logging document. * * \note Logging can only be started or stopped if metadata cache logging was enabled * via H5Pset_mdc_log_options().\n @@ -1849,8 +1459,6 @@ H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t * * \since 1.10.0 * - * \todo Fix the document reference! - * */ H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id); /** @@ -1887,7 +1495,7 @@ H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id); * list, and H5Fget_mdc_logging_status() will return the current state of * the logging flags. * - * The log format is described in the \Emph{Metadata Cache Logging} document. + * The log format is described in the \ref_mdc_logging document. * * \note Logging can only be started or stopped if metadata cache logging was enabled * via H5Pset_mdc_log_options().\n @@ -1933,7 +1541,7 @@ H5_DLL herr_t H5Fstop_mdc_logging(hid_t file_id); * list, and H5Fget_mdc_logging_status() will return the current state of * the logging flags. * - * The log format is described in the \Emph{Metadata Cache Logging} document. + * The log format is described in the \ref_mdc_logging document. * * \note Unlike H5Fstart_mdc_logging() and H5Fstop_mdc_logging(), this function can * be called on any open file identifier. @@ -1944,7 +1552,7 @@ H5_DLL herr_t H5Fget_mdc_logging_status(hid_t file_id, hbool_t *is_enabled, hboo /** * \ingroup SWMR * - * \todo Finish this! + * \todo UFO? */ H5_DLL herr_t H5Fformat_convert(hid_t fid); /** @@ -1998,7 +1606,7 @@ H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], u * \brief Obtains information about a cache image if it exists * * \file_id - * \param[out] image_addr Offset of the cache image if it exists, or #HADDR_UNDEF if it does not + * \param[out] image_addr Offset of the cache image if it exists, or \c HADDR_UNDEF if it does not * \param[out] image_size Length of the cache image if it exists, or 0 if it does not * \returns \herr_t * @@ -2139,11 +1747,10 @@ H5_DLL herr_t H5Fwait(hid_t file_id); * the desired behavior. * \endparblock * - * \see Enabling a Strict Consistency Semantics Model in Parallel HDF5 + * \see \ref_cons_semantics * * \since 1.8.9 * - * \todo Fix the reference! */ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag); /** @@ -2163,11 +1770,10 @@ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag); * Upon successful return, \p flag will be set to \c 1 if file access is set * to atomic mode and \c 0 if file access is set to nonatomic mode. * - * \see Enabling a Strict Consistency Semantics Model in Parallel HDF5 + * \see \ref_cons_semantics * * \since 1.8.9 * - * \todo Fix the reference! */ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); #endif /* H5_HAVE_PARALLEL */ @@ -2199,14 +1805,14 @@ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); #ifndef H5_NO_DEPRECATED_SYMBOLS /* Macros */ -#define H5F_ACC_DEBUG (H5CHECK H5OPEN 0x0000u) /*print debug info (deprecated)*/ +#define H5F_ACC_DEBUG (H5CHECK H5OPEN 0x0000u) /**< Print debug info \deprecated In which version? */ /* Typedefs */ /** * Current "global" information about file */ -//! [H5F_info1_t_snip] +//! <!-- [H5F_info1_t_snip] --> typedef struct H5F_info1_t { hsize_t super_ext_size; /**< Superblock extension size */ struct { @@ -2214,7 +1820,7 @@ typedef struct H5F_info1_t { H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */ } sohm; } H5F_info1_t; -//! [H5F_info1_t_snip] +//! <!-- [H5F_info1_t_snip] --> /* Function prototypes */ /** @@ -2252,7 +1858,7 @@ typedef struct H5F_info1_t { * header indexes. Each index might be either a B-tree or * a list. * - * \version 1.10.0 C function H5Fget_info() renamed to H5Fget_info1() and + * \version 1.10.0 Function H5Fget_info() renamed to H5Fget_info1() and * deprecated in this release. * * \since 1.8.0 diff --git a/src/H5Gmodule.h b/src/H5Gmodule.h index 219342d..fe26bd2 100644 --- a/src/H5Gmodule.h +++ b/src/H5Gmodule.h @@ -31,9 +31,94 @@ /** * \defgroup H5G H5G - * \brief Group Interface - * \details The HDF5 Group Interface, H5G, provides a mechanism for managing - * HDF5 groups and their members, which are other HDF5 objects. + * + * \details \Bold{Groups in HDF5:} A group associates names with objects and + * provides a mechanism for mapping a name to an object. Since all + * objects appear in at least one group (with the possible exception of + * the root object) and since objects can have names in more than one + * group, the set of all objects in an HDF5 file is a directed + * graph. The internal nodes (nodes with out-degree greater than zero) + * must be groups while the leaf nodes (nodes with out-degree zero) are + * either empty groups or objects of some other type. Exactly one + * object in every non-empty file is the root object. The root object + * always has a positive in-degree because it is pointed to by the file + * super block. + * + * \Bold{Locating objects in the HDF5 file hierarchy:} An object name + * consists of one or more components separated from one another by + * slashes. An absolute name begins with a slash and the object is + * located by looking for the first component in the root object, then + * looking for the second component in the first object, etc., until + * the entire name is traversed. A relative name does not begin with a + * slash and the traversal begins at the location specified by the + * create or access function. + * + * \Bold{Group implementations in HDF5:} The original HDF5 group + * implementation provided a single indexed structure for link + * storage. A new group implementation, in HDF5 Release 1.8.0, enables + * more efficient compact storage for very small groups, improved link + * indexing for large groups, and other advanced features. + * + * \li The \Emph{original indexed} format remains the default. Links + * are stored in a B-tree in the group’s local heap. + * \li Groups created in the new \Emph{compact-or-indexed} format, the + * implementation introduced with Release 1.8.0, can be tuned for + * performance, switching between the compact and indexed formats + * at thresholds set in the user application. + * - The \Emph{compact} format will conserve file space and processing + * overhead when working with small groups and is particularly + * valuable when a group contains no links. Links are stored + * as a list of messages in the group’s header. + * - The \Emph{indexed} format will yield improved + * performance when working with large groups, e.g., groups + * containing thousands to millions of members. Links are stored in + * a fractal heap and indexed with an improved B-tree. + * \li The new implementation also enables the use of link names consisting of + * non-ASCII character sets (see H5Pset_char_encoding()) and is + * required for all link types other than hard or soft links, e.g., + * external and user-defined links (see the \ref H5L APIs). + * + * The original group structure and the newer structures are not + * directly interoperable. By default, a group will be created in the + * original indexed format. An existing group can be changed to a + * compact-or-indexed format if the need arises; there is no capability + * to change back. As stated above, once in the compact-or-indexed + * format, a group can switch between compact and indexed as needed. + * + * Groups will be initially created in the compact-or-indexed format + * only when one or more of the following conditions is met: + * \li The low version bound value of the library version bounds property + * has been set to Release 1.8.0 or later in the file access property + * list (see H5Pset_libver_bounds()). Currently, that would require an + * H5Pset_libver_bounds() call with the low parameter set to + * #H5F_LIBVER_LATEST.\n When this property is set for an HDF5 file, + * all objects in the file will be created using the latest available + * format; no effort will be made to create a file that can be read by + * older libraries. + * \li The creation order tracking property, #H5P_CRT_ORDER_TRACKED, has been + * set in the group creation property list (see H5Pset_link_creation_order()). + * + * An existing group, currently in the original indexed format, will be + * converted to the compact-or-indexed format upon the occurrence of + * any of the following events: + * \li An external or user-defined link is inserted into the group. + * \li A link named with a string composed of non-ASCII characters is + * inserted into the group. + * + * The compact-or-indexed format offers performance improvements that + * will be most notable at the extremes, i.e., in groups with zero + * members and in groups with tens of thousands of members. But + * measurable differences may sometimes appear at a threshold as low as + * eight group members. Since these performance thresholds and criteria + * differ from application to application, tunable settings are + * provided to govern the switch between the compact and indexed + * formats (see H5Pset_link_phase_change()). Optimal thresholds will + * depend on the application and the operating environment. + * + * Future versions of HDF5 will retain the ability to create, read, + * write, and manipulate all groups stored in either the original + * indexed format or the compact-or-indexed format. + * */ #endif /* H5Gmodule_H */ diff --git a/src/H5Gpublic.h b/src/H5Gpublic.h index 68786dc..416ff2c 100644 --- a/src/H5Gpublic.h +++ b/src/H5Gpublic.h @@ -41,24 +41,31 @@ /* Public Typedefs */ /*******************/ -/* Types of link storage for groups */ +//! <!-- [H5G_storage_t_snip] --> +/** + * Types of link storage for groups + */ typedef enum H5G_storage_type_t { - H5G_STORAGE_TYPE_UNKNOWN = -1, /* Unknown link storage type */ - H5G_STORAGE_TYPE_SYMBOL_TABLE, /* Links in group are stored with a "symbol table" */ - /* (this is sometimes called "old-style" groups) */ - H5G_STORAGE_TYPE_COMPACT, /* Links are stored in object header */ - H5G_STORAGE_TYPE_DENSE /* Links are stored in fractal heap & indexed with v2 B-tree */ + H5G_STORAGE_TYPE_UNKNOWN = -1, /**< Unknown link storage type */ + H5G_STORAGE_TYPE_SYMBOL_TABLE, /**< Links in group are stored with a "symbol table" */ + /**< (this is sometimes called "old-style" groups) */ + H5G_STORAGE_TYPE_COMPACT, /**< Links are stored in object header */ + H5G_STORAGE_TYPE_DENSE /**< Links are stored in fractal heap & indexed with v2 B-tree */ } H5G_storage_type_t; +//! <!-- [H5G_storage_t_snip] --> -/* Information struct for group (for H5Gget_info/H5Gget_info_by_name/H5Gget_info_by_idx) */ -//! [H5G_info_t_snip] +//! <!-- [H5G_info_t_snip] --> +/** + * Information struct for group for + * H5Gget_info(), H5Gget_info_by_name(), and H5Gget_info_by_idx() + */ typedef struct H5G_info_t { - H5G_storage_type_t storage_type; /* Type of storage for links in group */ - hsize_t nlinks; /* Number of links in group */ - int64_t max_corder; /* Current max. creation order value for group */ - hbool_t mounted; /* Whether group has a file mounted on it */ + H5G_storage_type_t storage_type; /**< Type of storage for links in group */ + hsize_t nlinks; /**< Number of links in group */ + int64_t max_corder; /**< Current max. creation order value for group */ + hbool_t mounted; /**< Whether group has a file mounted on it */ } H5G_info_t; -//! [H5G_info_t_snip] +//! <!-- [H5G_info_t_snip] --> /********************/ /* Public Variables */ @@ -120,24 +127,8 @@ H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcp /** * -------------------------------------------------------------------------- - * \ingroup H5G - * - * \brief Asynchronous version of H5Gcreate2() - * - * \app_file - * \app_func - * \app_line - * \fgdta_loc_id - * \param[in] name Name of the group to create - * \lcpl_id - * \gcpl_id - * \gapl_id - * \es_id - * - * \return \hid_t{group} - * - * \see H5Gcreate2() - * + * \ingroup ASYNC + * \async_variant_of{H5Gcreate} */ H5_DLL hid_t H5Gcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, hid_t es_id); @@ -223,22 +214,8 @@ H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id); /** * -------------------------------------------------------------------------- - * \ingroup H5G - * - * \brief Asynchronous version of H5Gopen2() - * - * \app_file - * \app_func - * \app_line - * \fgdta_loc_id - * \param[in] name Name of the group to open - * \gapl_id - * \es_id - * - * \return \hid_t{group} - * - * \see H5Gopen2() - * + * \ingroup ASYNC + * \async_variant_of{H5Gopen} */ H5_DLL hid_t H5Gopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t gapl_id, hid_t es_id); @@ -296,21 +273,8 @@ H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo); /** * -------------------------------------------------------------------------- - * \ingroup H5G - * - * \brief Asynchronous version of H5Gget_info() - * - * \app_file - * \app_func - * \app_line - * \fgdta_loc_id - * \param[out] ginfo Struct in which group information is returned - * \es_id - * - * \return \hid_t{group} - * - * \see H5Gget_info() - * + * \ingroup ASYNC + * \async_variant_of{H5Gget_info} */ H5_DLL herr_t H5Gget_info_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, H5G_info_t *ginfo /*out*/, hid_t es_id); @@ -351,23 +315,8 @@ H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *gi /** * -------------------------------------------------------------------------- - * \ingroup H5G - * - * \brief Asynchronous version of H5Gget_info_by_name() - * - * \app_file - * \app_func - * \app_line - * \fgdta_loc_id - * \param[in] name Name of the group to query - * \param[out] ginfo Struct in which group information is returned - * \lapl_id - * \es_id - * - * \return \herr_t - * - * \see H5Gget_info_by_name() - * + * \ingroup ASYNC + * \async_variant_of{H5Gget_info_by_name} */ H5_DLL herr_t H5Gget_info_by_name_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, H5G_info_t *ginfo /*out*/, @@ -423,29 +372,8 @@ H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_ /** * -------------------------------------------------------------------------- - * \ingroup H5G - * - * \brief Asynchronous version of H5Gcreate2() - * - * \app_file - * \app_func - * \app_line - * \fgdta_loc_id - * \param[in] group_name Name of the group to query - * \param[in] idx_type Transient index identifying object - * \param[in] order Transient index identifying object - * \param[in] n Position in the index of the group to query - * \param[out] ginfo Struct in which group information is returned - * \lapl_id - * \es_id - * - * \return Returns - * \li The size of the object name if successful, or - * \li 0 if no name is associated with the group identifier, or - * \li negative value, if failure occurred - * - * \see H5Gcreate2() - * + * \ingroup ASYNC + * \async_variant_of{H5Gget_info_by_idx} */ H5_DLL herr_t H5Gget_info_by_idx_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *group_name, H5_index_t idx_type, @@ -523,29 +451,18 @@ H5_DLL herr_t H5Grefresh(hid_t group_id); * Failure to release a group with this call will result in * resource leaks. * - * \since 1.0.0 + * \par Example + * \snippet H5F_examples.c mount * - * \version 1.4.0 Fortran function introduced in this release + * \since 1.0.0 * */ H5_DLL herr_t H5Gclose(hid_t group_id); /** * -------------------------------------------------------------------------- - * \ingroup H5G - * - * \brief Asynchronous version of H5Gcreate2() - * - * \app_file - * \app_func - * \app_line - * \group_id - * \es_id - * - * \return \herr_t - * - * \see H5Gcreate2() - * + * \ingroup ASYNC + * \async_variant_of{H5Gclose} */ H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t group_id, hid_t es_id); @@ -595,60 +512,649 @@ H5_DLL herr_t H5Gclose_async(const char *app_file, const char *app_func, unsigne /* Typedefs */ -/* +//! <!-- [H5G_obj_t_snip] --> +/** * An object has a certain type. The first few numbers are reserved for use * internally by HDF5. Users may add their own types with higher values. The - * values are never stored in the file -- they only exist while an - * application is running. An object may satisfy the `isa' function for more - * than one type. + * values are never stored in the file -- they only exist while an application + * is running. An object may satisfy the `isa' function for more than one type. + * + * \deprecated */ typedef enum H5G_obj_t { - H5G_UNKNOWN = -1, /* Unknown object type */ - H5G_GROUP, /* Object is a group */ - H5G_DATASET, /* Object is a dataset */ - H5G_TYPE, /* Object is a named data type */ - H5G_LINK, /* Object is a symbolic link */ - H5G_UDLINK, /* Object is a user-defined link */ - H5G_RESERVED_5, /* Reserved for future use */ - H5G_RESERVED_6, /* Reserved for future use */ - H5G_RESERVED_7 /* Reserved for future use */ + H5G_UNKNOWN = -1, /**< Unknown object type */ + H5G_GROUP, /**< Object is a group */ + H5G_DATASET, /**< Object is a dataset */ + H5G_TYPE, /**< Object is a named data type */ + H5G_LINK, /**< Object is a symbolic link */ + H5G_UDLINK, /**< Object is a user-defined link */ + H5G_RESERVED_5, /**< Reserved for future use */ + H5G_RESERVED_6, /**< Reserved for future use */ + H5G_RESERVED_7 /**< Reserved for future use */ } H5G_obj_t; +//! <!-- [H5G_obj_t_snip] --> -/** Define the operator function pointer for for H5Giterate() */ -//! [H5G_iterate_t_snip] +//! <!-- [H5G_iterate_t_snip] --> +/** + * Callback for H5Giterate() + * + * \deprecated + */ typedef herr_t (*H5G_iterate_t)(hid_t group, const char *name, void *op_data); -//! [H5G_iterate_t_snip] +//! <!-- [H5G_iterate_t_snip] --> -/** Information about an object */ -//! [H5G_stat_t_snip] +//! <!-- [H5G_stat_t_snip] --> +/** + * Information about an object + * + * \deprecated + */ typedef struct H5G_stat_t { - unsigned long fileno[2]; /*file number */ - unsigned long objno[2]; /*object number */ - unsigned nlink; /*number of hard links to object*/ - H5G_obj_t type; /*basic object type */ - time_t mtime; /*modification time */ - size_t linklen; /*symbolic link value length */ - H5O_stat_t ohdr; /* Object header information */ + unsigned long fileno[2]; /**< file number */ + unsigned long objno[2]; /**< object number */ + unsigned nlink; /**< number of hard links to object*/ + H5G_obj_t type; /**< basic object type */ + time_t mtime; /**< modification time */ + size_t linklen; /**< symbolic link value length */ + H5O_stat_t ohdr; /**< Object header information */ } H5G_stat_t; -//! [H5G_stat_t_snip] +//! <!-- [H5G_stat_t_snip] --> /* Function prototypes */ -H5_DLL hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint); -H5_DLL hid_t H5Gopen1(hid_t loc_id, const char *name); -H5_DLL herr_t H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name, const char *new_name); -H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, hid_t new_loc_id, - const char *new_name); -H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_name); -H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name); -H5_DLL herr_t H5Gunlink(hid_t loc_id, const char *name); -H5_DLL herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char *buf /*out*/); -H5_DLL herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment); -H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf); -H5_DLL herr_t H5Giterate(hid_t loc_id, const char *name, int *idx, H5G_iterate_t op, void *op_data); -H5_DLL herr_t H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs); -H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link, - H5G_stat_t *statbuf /*out*/); -H5_DLL ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Creates a new group and links it into the file + * + * \fgdta_loc_id + * \param[in] name Name of the group to create + * \param[in] size_hint Optional parameter indicating the number of bytes + * to reserve for the names that will appear in the group + * + * \return \hid_t{group} + * + * \deprecated This function is deprecated in favor of H5Gcreate2(). + * + * \details H5Gcreate1() creates a new group with the specified name at the + * specified location, \p loc_id. \p loc_id may be a file, group, + * dataset, named datatype or attribute. If an attribute, dataset, or + * named datatype is specified for \p loc_id then the group will be + * created at the location where the attribute, dataset, or named + * datatype is attached. The name, name, must not already be taken by + * some other object and all parent groups must already exist. + * + * \p name can be a relative path based at \p loc_id or an absolute + * path from the root of the file. Use of this function requires that + * any intermediate groups specified in the path already exist. + * + * The length of a group name, or of the name of any object within a + * group, is not limited. + * + * \p size_hint is a hint for the number of bytes to reserve to store + * the names which will be eventually added to the new group. Passing a + * value of zero for \p size_hint is usually adequate since the library + * is able to dynamically resize the name heap, but a correct hint may + * result in better performance. If a non-positive value is supplied + * for \p size_hint, then a default size is chosen. + * + * The return value is a group identifier for the open group. This + * group identifier should be closed by calling H5Gclose() when it is + * no longer needed. + * + * See H5Gcreate_anon() for a discussion of the differences between + * H5Gcreate1() and H5Gcreate_anon(). + * + * \par Example + * \snippet H5F_examples.c mount + * + * \version 1.8.0 Function H5Gcreate() renamed to H5Gcreate1() and deprecated + * in this release. + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Gcreate1(hid_t loc_id, const char *name, size_t size_hint); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Opens an existing group for modification and returns a group + * identifier for that group + * + * \fgdta_loc_id + * \param[in] name Name of the group to open + * + * \return \hid_t{group} + * + * \deprecated This function is deprecated in favor of H5Gopen2(). + * + * \details H5Gopen1() opens an existing group, \p name, at the location + * specified by \p loc_id. + * + * H5Gopen1() returns a group identifier for the group that was + * opened. This group identifier should be released by calling + * H5Gclose() when it is no longer needed. + * + * \version 1.8.0 The function H5Gopen() was renamed to H5Gopen1() + * and deprecated in this release. + * \since 1.0.0 + * + */ +H5_DLL hid_t H5Gopen1(hid_t loc_id, const char *name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Creates a link of the specified type from \p new_name to \p + * cur_name + * + * \fg_loc_id{cur_loc_id} + * \param[in] type Link type + * \param[in] cur_name Name of the existing object + * \param[in] new_name New name for the object + * + * \return \herr_t + * + * \deprecated This function is deprecated. + * + * \details H5Glink() creates a new name for an object that has some current + * name, possibly one of many names it currently has. + * + * If \p link_type is #H5G_LINK_HARD, then \p cur_name must specify + * the name of an existing object and both names are interpreted + * relative to \p cur_loc_id, which is either a file identifier or a + * group identifier. + * + * If \p link_type is #H5G_LINK_SOFT, then \p cur_name can be anything + * and is interpreted at lookup time relative to the group which + * contains the final component of \p new_name. For instance, if \p + * cur_name is \Code{./foo}, \p new_name is \Code{./x/y/bar}, and a + * request is made for \Code{./x/y/bar}, then the actual object looked + * up is \Code{./x/y/./foo}. + + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Glink(hid_t cur_loc_id, H5G_link_t type, const char *cur_name, const char *new_name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Creates a link of the specified type from \p cur_name to \p + * new_name + * + * \fg_loc_id{cur_loc_id} + * \param[in] cur_name Name of the existing object + * \param[in] type Link type + * \fg_loc_id{new_loc_id} + * \param[in] new_name New name for the object + * + * \return \herr_t + * + * \deprecated This function is deprecated. + * + * \details H5Glink2() creates a new name for an object that has some current + * name, possibly one of many names it currently has. + * + * If \p link_type is #H5G_LINK_HARD, then \p cur_name must specify the + * name of an existing object and both names are interpreted relative + * to \p cur_loc_id and \p new_loc_id, respectively, which are either + * file identifiers or group identifiers. + * + * If \p link_type is #H5G_LINK_SOFT, then \p cur_name can be anything + * and is interpreted at lookup time relative to the group which + * contains the final component of \p new_name. For instance, if \p + * current_name is \Code{./foo}, \p new_name is \Code{./x/y/bar}, and a + * request is made for \Code{./x/y/bar}, then the actual object looked + * up is \Code{./x/y/./foo}. + + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, hid_t new_loc_id, + const char *new_name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Renames an object within an HDF5 file + * + * \fg_loc_id{src_loc_id} + * \param[in] src_name Object's original name + * \param[in] dst_name Object's new name + * + * \return \herr_t + * + * \deprecated This function is deprecated. + * + * \details H5Gmove() renames an object within an HDF5 file. The original name, + * \p src_name, is unlinked from the group graph and the new name, \p + * dst_name, is inserted as an atomic operation. Both names are + * interpreted relative to \p loc_id, which is either a file or a group + * identifier. + * + * \attention Exercise care in moving groups as it is possible to render data in + * a file inaccessible with H5Gmove(). See The Group Interface in the + * HDF5 User's Guide. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Renames an object within an HDF5 file + * + * \fg_loc_id{src_loc_id} + * \param[in] src_name Object's original name + * \fg_loc_id{dst_loc_id} + * \param[in] dst_name Object's new name + * + * \return \herr_t + * + * \deprecated This function is deprecated. + * + * \details H5Gmove2() renames an object within an HDF5 file. The original name, + * \p src_name, is unlinked from the group graph and the new name, \p + * dst_name, is inserted as an atomic operation. + * + * \p src_name and \p dst_name are interpreted relative to \p + * src_loc_id and \p dst_loc_id, respectively, which are either file or + * group identifiers. + * + * \attention Exercise care in moving groups as it is possible to render data in + * a file inaccessible with H5Gmove2(). See The Group Interface in the + * HDF5 User's Guide. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Removes the link to an object from a group + * + * \fg_loc_id{loc_id} + * \param[in] name Name of the object to unlink + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function H5Ldelete(). + * + * \details H5Gunlink() removes the object specified by \p name from the group + * graph and decrements the link count for the object to which \p name + * points. This action eliminates any association between name and the + * object to which name pointed. + * + * Object headers keep track of how many hard links refer to an object; + * when the link count reaches zero, the object can be removed from the + * file. Objects which are open are not removed until all identifiers + * to the object are closed. + * + * If the link count reaches zero, all file space associated with the + * object will be released, i.e., identified in memory as freespace. If + * any object identifier is open for the object, the space will not be + * released until after the object identifier is closed. + * + * Note that space identified as freespace is available for re-use only + * as long as the file remains open; once a file has been closed, the + * HDF5 library loses track of freespace. See “Freespace Management” in + * the HDF5 User's Guide for further details. + * + * \attention Exercise care in moving groups as it is possible to render data in + * a file inaccessible with H5Gunlink(). See The Group Interface in the + * HDF5 User's Guide. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gunlink(hid_t loc_id, const char *name); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Returns the name of the object that the symbolic link points to + * + * \fg_loc_id{loc_id} + * \param[in] name Symbolic link to the object whose name is to be returned + * \param[in] size Maximum number of characters of value to be returned + * \param[out] buf A buffer to hold the name of the object being sought + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function H5Lget_val(). + * + * \details H5Gget_linkval() returns up to size characters of the name of the + * object that the symbolic link name points to. + * + * The parameter \p loc_id is a file or group identifier. + * + * The parameter \p name must be a symbolic link pointing to the + * desired object and must be defined relative to \p loc_id. + * + * If size is smaller than the size of the returned object name, then + * the name stored in the buffer value will not be \c NULL terminated. + * + * This function fails if \p name is not a symbolic link. The presence + * of a symbolic link can be tested by passing zero for \p size and \p + * NULL for value. + * + * This function should be used only after H5Lget_info1() (or the + * deprecated function H5Gget_objinfo()) has been called to verify that + * name is a symbolic link. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char *buf /*out*/); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Sets comment for specified object + * + * \fgdt_loc_id + * \param[in] name Name of the object whose comment is to be set or reset + * name must be \Code{'.'} (dot) if \p loc_id fully specifies + * the object for which the comment is to be set. + * \param[in] comment The new comment + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function + * H5Oset_comment(). + * + * \details H5Gset_comment() sets the comment for the object specified by \p + * loc_id and name to comment. Any previously existing comment is + * overwritten. + * + * \p loc_id can specify any object in the file. name can be one of the + * following: + * \li The name of the object relative to \p loc_id + * \li An absolute name of the object, starting from \c /, the file’s + * root group + * \li A dot (\c .), if \p loc_id fully specifies the object + * + * If \p comment is the empty string or a null pointer, the comment + * message is removed from the object. + * + * Comments should be relatively short, null-terminated, ASCII strings. + * + * Comments can be attached to any object that has an object header, + * e.g., datasets, groups, and named datatypes, but not symbolic links. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Retrieves comment for specified object + * + * \fgdt_loc_id + * \param[in] name Name of the object whose comment is to be set or reset + * name must be \Code{'.'} (dot) if \p loc_id fully specifies + * the object for which the comment is to be set. + * \param[in] bufsize Maximum number of comment characters to be returned in \p buf. + * \param[in] buf The comment + * + * \return Returns the number of characters in the comment, counting the \c NULL + * terminator, if successful; the value returned may be larger than + * \p bufsize. Otherwise returns a negative value. + * + * \deprecated This function is deprecated in favor of the function + * H5Oget_comment(). + * + * \details H5Gget_comment() retrieves the comment for the the object specified + * by \p loc_id and \p name. The comment is returned in the buffer \p + * buf. + * + * \p loc_id can specify any object in the file. name can be one of the + * following: + * \li The name of the object relative to \p loc_id + * \li An absolute name of the object, starting from \c /, the file’s + * root group + * \li A dot (\c .), if \p loc_id fully specifies the object + * + * At most bufsize characters, including a null-terminator, are + * returned in \p buf. The returned value is not null-terminated if the + * comment is longer than the supplied buffer. If the size of the + * comment is unknown, a preliminary \p H5Gget_comment() call will + * return the size of the comment, including space for the + * null-terminator. + * + * If an object does not have a comment, the empty string is returned + * in comment. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char *buf); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Iterates over the entries of a group invoking a callback for each + * entry encountered + * + * \fg_loc_id + * \param[in] name Group over which the iteration is performed + * \param[in,out] idx Location at which to begin the iteration + * \param[in] op Operation to be performed on an object at each step of the + * iteration + * \param[in,out] op_data Data associated with the operation + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function + * H5Literate1(). + * + * \details H5Giterate() iterates over the members of name in the file or group + * specified with \p loc_id. For each object in the group, the \p + * op_data and some additional information, specified below, are passed + * to the operator function. The iteration begins with the \p idx + * object in the group and the next element to be processed by the + * operator is returned in \p idx. If \p idx is NULL, then the iterator + * starts at the first group member; since no stopping point is + * returned in this case, the iterator cannot be restarted if one of + * the calls to its operator returns non-zero. H5Giterate() does not + * recursively follow links into subgroups of the specified group. + * + * The prototype for \ref H5G_iterate_t is: + * \snippet this H5G_iterate_t_snip + * + * The operation receives the group identifier for the group being + * iterated over, \p group, the name of the current object within + * the group, \p name, and the pointer to the operator data + * passed in to H5Giterate(), \p op_data. + * + * The return values from an operator are: + * \li Zero causes the iterator to continue, returning zero when all + * group members have been processed. + * \li Positive causes the iterator to immediately return that positive + * value, indicating short-circuit success. The iterator can be + * restarted at the next group member. + * \li Negative causes the iterator to immediately return that value, + * indicating failure. The iterator can be restarted at the next + * group member. + * + * H5Giterate() assumes that the membership of the group identified by + * \p name remains unchanged through the iteration. If the membership + * changes during the iteration, the function's behavior is undefined. + * + * H5Giterate() is not recursive. In particular, if a member of \p name + * is found to be a group, call it \c subgroup_a, H5Giterate() does not + * examine the members of \c subgroup_a. When recursive iteration is + * required, the application must handle the recursion, explicitly + * calling H5Giterate() on discovered subgroups. + + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Giterate(hid_t loc_id, const char *name, int *idx, H5G_iterate_t op, void *op_data); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Returns number of objects in the group specified by its identifier + * + * \fg_loc_id + * \param[out] num_objs Number of objects in the group + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the function H5Gget_info(). + * + * \details H5Gget_num_objs() returns number of objects in a group. Group is + * specified by its identifier \p loc_id. If a file identifier is + * passed in, then the number of objects in the root group is returned. + * + * \version 1.8.0 Function deprecated in this release. + * + */ +H5_DLL herr_t H5Gget_num_objs(hid_t loc_id, hsize_t *num_objs); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Returns information about an object. + * + * \fgdt_loc_id + * \param[in] name Name of the object for which status is being sought + * \param[in] follow_link Link flag + * \param[out] statbuf Buffer in which to return information about the object + * + * \return \herr_t + * + * \deprecated This function is deprecated in favor of the functions H5Oget_info() + * and H5Lget_info1(). + * + * \details H5Gget_objinfo() returns information about the specified object + * through the \p statbuf argument. + * + * A file or group identifier, \p loc_id, and an object name, \p name, + * relative to \p loc_id, are commonly used to specify the + * object. However, if the object identifier is already known to the + * application, an alternative approach is to use that identifier, \c + * obj_id, in place of \p loc_id, and a dot (\c .) in place of \p + * name. Thus, the alternative versions of the first portion of an + * H5Gget_objinfo() call would be as follows: + * \code + * H5Gget_objinfo (loc_id name ...) + * H5Gget_objinfo (obj_id . ...) + * \endcode + * + * If the object is a symbolic link and follow_link is zero (0), then + * the information returned describes the link itself; otherwise the + * link is followed and the information returned describes the object + * to which the link points. If \p follow_link is non-zero but the + * final symbolic link is dangling (does not point to anything), then + * an error is returned. The \p statbuf fields are undefined for an + * error. The existence of an object can be tested by calling this + * function with a \c NULL \p statbuf. + * + * H5Gget_objinfo() fills in the following data structure (defined in + * H5Gpublic.h): + * \snippet this H5G_stat_t_snip + * + * where \ref H5O_stat_t (defined in H5Opublic.h) is: + * \snippet H5Opublic.h H5O_stat_t_snip + * + * \attention Some systems will be able to record the time accurately but unable + * to retrieve the correct time; such systems (e.g., Irix64) will + * report an \c mtime value of 0 (zero). + * + * \version 1.8.0 Function deprecated in this release. + * \version 1.6.1 Two new fields were added to the \ref H5G_stat_t struct in + * this release. + * + */ +H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link, + H5G_stat_t *statbuf /*out*/); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Returns a name of an object specified by an index + * + * \fg_loc_id + * \param[in] idx Transient index identifying object + * \param[in,out] name Pointer to user-provided buffer the object name + * \param[in] size Name length + * + * \return Returns the size of the object name if successful, or 0 if no name is + * associated with the group identifier. Otherwise returns a negative + * value. + * + * \deprecated This function is deprecated in favor of the function H5Lget_name_by_idx(). + * + * \details H5Gget_objname_by_idx() returns a name of the object specified by + * the index \p idx in the group \p loc_id. + * + * The group is specified by a group identifier \p loc_id. If + * preferred, a file identifier may be passed in \p loc_id; that file's + * root group will be assumed. + * + * \p idx is the transient index used to iterate through the objects in + * the group. The value of \p idx is any nonnegative number less than + * the total number of objects in the group, which is returned by the + * function H5Gget_num_objs(). Note that this is a transient index; an + * object may have a different index each time a group is opened. + * + * The object name is returned in the user-specified buffer \p name. + * + * If the size of the provided buffer \p name is less or equal the + * actual object name length, the object name is truncated to + * \Code{max_size - 1} characters. + * + * Note that if the size of the object's name is unkown, a preliminary + * call to H5Gget_objname_by_idx() with \p name set to \c NULL will + * return the length of the object's name. A second call to + * H5Gget_objname_by_idx() can then be used to retrieve the actual + * name. + * + * \version 1.8.0 Function deprecated in this release. + * \since 1.6.0 + * + */ +H5_DLL ssize_t H5Gget_objname_by_idx(hid_t loc_id, hsize_t idx, char *name, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5G + * + * \brief Returns the type of an object specified by an index + * + * \fg_loc_id + * \param[in] idx Transient index identifying object + * + * \return Returns the type of the object if successful. Otherwise returns a + * negative value. + * + * \deprecated This function is deprecated in favor of the function H5Oget_info(). + * + * \details H5Gget_objtype_by_idx() returns the type of the object specified by + * the index \p idx in the group \p loc_id. + * + * The group is specified by a group identifier \p loc_id. If + * preferred, a file identifier may be passed in \p loc_id; that file's + * root group will be assumed. + * + * \p idx is the transient index used to iterate through the objects in + * the group. This parameter is described in more detail in the + * discussion of H5Gget_objname_by_idx(). + * + * \version 1.8.0 Function deprecated in this release. + * \version 1.6.0 The function return type changed from \c int to the enumerated + * type \ref H5G_obj_t. + * \since 1.6.0 + * + */ H5_DLL H5G_obj_t H5Gget_objtype_by_idx(hid_t loc_id, hsize_t idx); #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5Ipublic.h b/src/H5Ipublic.h index be347e4..8e5e167 100644 --- a/src/H5Ipublic.h +++ b/src/H5Ipublic.h @@ -32,6 +32,7 @@ * test/tmisc.c to verify that the H5I{inc|dec|get}_ref() routines * work correctly with it. \endinternal */ +//! <!-- [H5I_type_t_snip] --> typedef enum H5I_type_t { H5I_UNINIT = (-2), /**< uninitialized type */ H5I_BADID = (-1), /**< invalid Type */ @@ -53,6 +54,7 @@ typedef enum H5I_type_t { H5I_EVENTSET, /**< type ID for event sets */ H5I_NTYPES /**< number of library types, MUST BE LAST! */ } H5I_type_t; +//! <!-- [H5I_type_t_snip] --> /** * Type of IDs to return to users @@ -86,30 +88,30 @@ typedef herr_t (*H5I_free_t)(void *, void **); /** * The type of a function to compare objects & keys */ -//! [H5I_search_func_t_snip] +//! <!-- [H5I_search_func_t_snip] --> typedef int (*H5I_search_func_t)(void *obj, hid_t id, void *key); -//! [H5I_search_func_t_snip] +//! <!-- [H5I_search_func_t_snip] --> /** * The type of H5Iiterate() callback functions */ -//! [H5I_iterate_func_t_snip] +//! <!-- [H5I_iterate_func_t_snip] --> typedef herr_t (*H5I_iterate_func_t)(hid_t id, void *udata); -//! [H5I_iterate_func_t_snip] +//! <!-- [H5I_iterate_func_t_snip] --> /** * The type of the realize_cb callback for H5Iregister_future */ -//! [H5I_future_realize_func_t_snip] +//! <!-- [H5I_future_realize_func_t_snip] --> typedef herr_t (*H5I_future_realize_func_t)(void *future_object, hid_t *actual_object_id); -//! [H5I_future_realize_func_t_snip] +//! <!-- [H5I_future_realize_func_t_snip] --> /** * The type of the discard_cb callback for H5Iregister_future */ -//! [H5I_future_discard_func_t_snip] +//! <!-- [H5I_future_discard_func_t_snip] --> typedef herr_t (*H5I_future_discard_func_t)(void *future_object); -//! [H5I_future_discard_func_t_snip] +//! <!-- [H5I_future_discard_func_t_snip] --> #ifdef __cplusplus extern "C" { @@ -173,7 +175,7 @@ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); * * \details The \p realize_cb parameter is a function pointer that will be * invoked by the HDF5 library to convert a future object into an - * actual object. The \realize_cb function may be invoked by + * actual object. The \p realize_cb function may be invoked by * H5Iobject_verify() to return the actual object for a user-defined * ID class (i.e. an ID class registered with H5Iregister_type()) or * internally by the HDF5 library in order to use or get information @@ -281,7 +283,7 @@ H5_DLL void *H5Iremove_verify(hid_t id, H5I_type_t type); * \p id. * * Valid types returned by the function are: - * \types + * \id_types * * If no valid type can be determined or the identifier submitted is * invalid, the function returns #H5I_BADID. diff --git a/src/H5Lmodule.h b/src/H5Lmodule.h index 54b94a4..16f1f34 100644 --- a/src/H5Lmodule.h +++ b/src/H5Lmodule.h @@ -35,6 +35,8 @@ * * \defgroup TRAV Link Traversal * \ingroup H5L + * \defgroup H5LA Advanced Link Functions + * \ingroup H5L */ #endif /* H5Lmodule_H */ diff --git a/src/H5Lpublic.h b/src/H5Lpublic.h index d5ec346..4b5e9e4 100644 --- a/src/H5Lpublic.h +++ b/src/H5Lpublic.h @@ -92,7 +92,7 @@ typedef enum { /** * \brief Information struct for links */ -//! [H5L_info2_t_snip] +//! <!-- [H5L_info2_t_snip] --> typedef struct { H5L_type_t type; /**< Type of link */ hbool_t corder_valid; /**< Indicate if creation order is valid */ @@ -103,7 +103,7 @@ typedef struct { size_t val_size; /**< Size of a soft link or user-defined link value */ } u; } H5L_info2_t; -//! [H5L_info2_t_snip] +//! <!-- [H5L_info2_t_snip] --> /* The H5L_class_t struct can be used to override the behavior of a * "user-defined" link class. Users should populate the struct with callback @@ -150,7 +150,7 @@ typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, * "user-defined" link class. Users should populate the struct with callback * functions defined elsewhere. */ -//! [H5L_class_t_snip] +//! <!-- [H5L_class_t_snip] --> typedef struct { int version; /**< Version number of this struct */ H5L_type_t id; /**< Link type ID */ @@ -162,16 +162,16 @@ typedef struct { H5L_delete_func_t del_func; /**< Callback for link deletion */ H5L_query_func_t query_func; /**< Callback for queries */ } H5L_class_t; -//! [H5L_class_t_snip] +//! <!-- [H5L_class_t_snip] --> /** * \brief Prototype for H5Literate2(), H5Literate_by_name2() operator * * The H5O_token_t version is used in the VOL layer and future public API calls. */ -//! [H5L_iterate2_t_snip] +//! <!-- [H5L_iterate2_t_snip] --> typedef herr_t (*H5L_iterate2_t)(hid_t group, const char *name, const H5L_info2_t *info, void *op_data); -//! [H5L_iterate2_t_snip] +//! <!-- [H5L_iterate2_t_snip] --> /** * \brief Callback for external link traversal @@ -201,8 +201,6 @@ typedef herr_t (*H5L_elink_traverse_t)(const char *parent_file_name, const char * * \return \herr_t * - * \todo We need to get the location ID story straight! - * * \details H5Lmove() moves a link within an HDF5 file. The original link, * \p src_name, is removed from \p src_loc and the new link, * \p dst_name, is inserted at dst_loc. This change is @@ -321,8 +319,6 @@ H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const * * \return \herr_t * - * \todo We need to get the location ID story straight! - * * \details H5Lcreate_hard() creates a new hard link to a pre-existing object * in an HDF5 file. * @@ -357,6 +353,11 @@ H5_DLL herr_t H5Lcopy(hid_t src_loc, const char *src_name, hid_t dst_loc, const */ H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, hid_t dst_loc, const char *dst_name, hid_t lcpl_id, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Lcreate_hard} + */ H5_DLL herr_t H5Lcreate_hard_async(const char *app_file, const char *app_func, unsigned app_line, hid_t cur_loc_id, const char *cur_name, hid_t new_loc_id, const char *new_name, hid_t lcpl_id, hid_t lapl_id, hid_t es_id); @@ -373,8 +374,6 @@ H5_DLL herr_t H5Lcreate_hard_async(const char *app_file, const char *app_func, u * * \return \herr_t * - * \todo We need to get the location ID story straight! - * * \details H5Lcreate_soft() creates a new soft link to an object in an HDF5 * file. * @@ -426,6 +425,11 @@ H5_DLL herr_t H5Lcreate_hard_async(const char *app_file, const char *app_func, u */ H5_DLL herr_t H5Lcreate_soft(const char *link_target, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Lcreate_soft} + */ H5_DLL herr_t H5Lcreate_soft_async(const char *app_file, const char *app_func, unsigned app_line, const char *link_target, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id, hid_t es_id); @@ -440,8 +444,6 @@ H5_DLL herr_t H5Lcreate_soft_async(const char *app_file, const char *app_func, u * * \return \herr_t * - * \todo We need to get the location ID story straight! - * * \details H5Ldelete() removes the link specified by \p name from the location * \p loc_id. * @@ -468,6 +470,11 @@ H5_DLL herr_t H5Lcreate_soft_async(const char *app_file, const char *app_func, u * */ H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Ldelete} + */ H5_DLL herr_t H5Ldelete_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t lapl_id, hid_t es_id); /** @@ -484,8 +491,6 @@ H5_DLL herr_t H5Ldelete_async(const char *app_file, const char *app_func, unsign * * \return \herr_t * - * \todo We need to get the location ID story straight! - * * \details H5Ldelete_by_idx() removes the \Emph{n}-th link in a group * according to the specified order, \p order, in the specified index, * \p index. @@ -500,6 +505,11 @@ H5_DLL herr_t H5Ldelete_async(const char *app_file, const char *app_func, unsign */ H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Ldelete_by_idx} + */ H5_DLL herr_t H5Ldelete_by_idx_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id, hid_t es_id); @@ -516,8 +526,6 @@ H5_DLL herr_t H5Ldelete_by_idx_async(const char *app_file, const char *app_func, * * \return \herr_t * - * \todo We need to get the location ID story straight! - * * \details H5Lget_val() returns tha value of link \p name. For smbolic links, * this is the path to which the link points, including the null * terminator. For external and user-defined links, it is the link @@ -575,8 +583,6 @@ H5_DLL herr_t H5Lget_val(hid_t loc_id, const char *name, void *buf /*out*/, size * * \return \herr_t * - * \todo We need to get the location ID story straight! - * * \details H5Lget_val_by_idx() retrieves the value of the \Emph{n}-th link in * a group, according to the specified order, \p order, within an * index, \p index. @@ -630,8 +636,6 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t * * \return \herr_t * - * \todo We need to get the location ID story straight! - * * \details H5Lexists() allows an application to determine whether the link \p * name exists in the location specified by \p loc_id. The link may be * of any type; only the presence of a link with that name is checked. @@ -707,6 +711,11 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t * */ H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Lexists} + */ H5_DLL herr_t H5Lexists_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hbool_t *exists, hid_t lapl_id, hid_t es_id); /** @@ -721,8 +730,6 @@ H5_DLL herr_t H5Lexists_async(const char *app_file, const char *app_func, unsign * * \return \herr_t * - * \todo We need to get the location ID story straight! - * * \details H5Lget_info2() returns information about the specified link through * the \p linfo argument. * @@ -830,8 +837,6 @@ H5_DLL herr_t H5Lget_info2(hid_t loc_id, const char *name, H5L_info2_t *linfo, h * * \see H5Lget_info2() * - * \todo Document H5Lget_info_by_idx() - * */ H5_DLL herr_t H5Lget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5L_info2_t *linfo, hid_t lapl_id); @@ -957,6 +962,11 @@ H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index */ H5_DLL herr_t H5Literate2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx, H5L_iterate2_t op, void *op_data); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Literate} + */ H5_DLL herr_t H5Literate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t group_id, H5_index_t idx_type, H5_iter_order_t order, hsize_t *idx_p, H5L_iterate2_t op, void *op_data, hid_t es_id); @@ -1642,8 +1652,10 @@ H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hi /* Typedefs */ -/* Information struct for link (for H5Lget_info1/H5Lget_info_by_idx1) */ -//! [H5L_info1_t_snip] +//! <!-- [H5L_info1_t_snip] --> +/** + * Information struct for link (for H5Lget_info1() and H5Lget_info_by_idx1()) + */ typedef struct { H5L_type_t type; /**< Type of link */ hbool_t corder_valid; /**< Indicate if creation order is valid */ @@ -1654,7 +1666,7 @@ typedef struct { size_t val_size; /**< Size of a soft link or UD link value */ } u; } H5L_info1_t; -//! [H5L_info1_t_snip] +//! <!-- [H5L_info1_t_snip] --> /** Callback during link traversal */ typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, @@ -1674,9 +1686,9 @@ typedef struct { } H5L_class_0_t; /** Prototype for H5Literate1() / H5Literate_by_name1() operator */ -//! [H5L_iterate1_t_snip] +//! <!-- [H5L_iterate1_t_snip] --> typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_t *info, void *op_data); -//! [H5L_iterate1_t_snip] +//! <!-- [H5L_iterate1_t_snip] --> /* Function prototypes */ /** @@ -1694,8 +1706,6 @@ typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_ * \deprecated As of HDF5-1.12 this function has been deprecated in favor of * the function H5Lget_info2() or the macro H5Lget_info(). * - * \todo We need to get the location ID story straight! - * * \details H5Lget_info1() returns information about the specified link through * the \p linfo argument. * diff --git a/src/H5MMpublic.h b/src/H5MMpublic.h index ebfb377..70ac644 100644 --- a/src/H5MMpublic.h +++ b/src/H5MMpublic.h @@ -29,8 +29,13 @@ #include "H5public.h" /* These typedefs are currently used for VL datatype allocation/freeing */ +//! <!-- [H5MM_allocate_t_snip] --> typedef void *(*H5MM_allocate_t)(size_t size, void *alloc_info); +//! <!-- [H5MM_allocate_t_snip] --> + +//! <!-- [H5MM_free_t_snip] --> typedef void (*H5MM_free_t)(void *mem, void *free_info); +//! <!-- [H5MM_free_t_snip] --> #ifdef __cplusplus extern "C" { diff --git a/src/H5Mmodule.h b/src/H5Mmodule.h index 8b4f11f..3dae3e2 100644 --- a/src/H5Mmodule.h +++ b/src/H5Mmodule.h @@ -26,4 +26,49 @@ #define H5_MY_PKG_ERR H5E_MAP #define H5_MY_PKG_INIT YES +/** + * \defgroup H5M H5M + * \brief Map Interface + * + * \details \Bold{The interface can only be used with the HDF5 VOL connectors that + * implement map objects.} The native HDF5 library does not support this + * feature. + * + * While the HDF5 data model is a flexible way to store data, some + * applications require a more general way to index information. HDF5 + * effectively uses key-value stores internally for a variety of + * purposes, but it does not expose a generic key-value store to the + * API. The Map APIs provide this capability to the HDF5 applications + * in the form of HDF5 map objects. These Map objects contain + * application-defined key-value stores, to which key-value pairs can + * be added, and from which values can be retrieved by key. + * + * HDF5 VOL connectors with support for map objects: + * - DAOS + * + * \par Example: + * \code + * hid_t file_id, fapl_id, map_id, vls_type_id; + * const char *names[2] = ["Alice", "Bob"]; + * uint64_t IDs[2] = [25385486, 34873275]; + * uint64_t val_out; + * + * <HDF5 VOL setup code ....> + * + * vls_type_id = H5Tcopy(H5T_C_S1); + * H5Tset_size(vls_type_id, H5T_VARIABLE); + * file_id = H5Fcreate("file.h5", H5F_ACC_TRUNC, H5P_DEFAULT, fapl_id); + * map_id = H5Mcreate(file_id, "map", vls_type_id, H5T_NATIVE_UINT64, H5P_DEFAULT, H5P_DEFAULT, H5P_DEFAULT); + * H5Mput(map_id, vls_type_id, &names[0], H5T_NATIVE_UINT64, &IDs[0], H5P_DEFAULT); + * H5Mput(map_id, vls_type_id, &names[1], H5T_NATIVE_UINT64, &IDs[1], H5P_DEFAULT); + * H5Mget(map_id, vls_type_id, &names[0], H5T_NATIVE_UINT64, &val_out, H5P_DEFAULT); + * if(val_out != IDs[0]) + * ERROR; + * H5Mclose(map_id); + * H5Tclose(vls_type_id); + * H5Fclose(file_id); + * \endcode + * + */ + #endif /* H5Dmodule_H */ diff --git a/src/H5Mpublic.h b/src/H5Mpublic.h index 4d8bef4..e0be828 100644 --- a/src/H5Mpublic.h +++ b/src/H5Mpublic.h @@ -61,8 +61,12 @@ typedef enum H5VL_map_specific_t { H5VL_MAP_DELETE /* H5Mdelete */ } H5VL_map_specific_t; -/* Callback for H5Miterate() */ +//! <!-- [H5M_iterate_t_snip] --> +/** + * Callback for H5Miterate() + */ typedef herr_t (*H5M_iterate_t)(hid_t map_id, const void *key, void *op_data); +//! <!-- [H5M_iterate_t_snip] --> /********************/ /* Public Variables */ @@ -81,38 +85,397 @@ extern "C" { */ #ifdef H5_HAVE_MAP_API +/** + * \ingroup H5M + * + * \brief Creates a map object + * + * \fgdta_loc_id + * \param[in] name Map object name + * \type_id{key_type_id} + * \type_id{val_type_id} + * \lcpl_id + * \mcpl_id + * \mapl_id + * \returns \hid_t{map object} + * + * \details H5Mcreate() creates a new map object for storing key-value + * pairs. The in-file datatype for keys is defined by \p key_type_id + * and the in-file datatype for values is defined by \p val_type_id. \p + * loc_id specifies the location to create the the map object and \p + * name specifies the name of the link to the map object relative to + * \p loc_id. + * + * \since 1.13.0 + * + */ H5_DLL hid_t H5Mcreate(hid_t loc_id, const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id, hid_t mcpl_id, hid_t mapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mcreate} + */ H5_DLL hid_t H5Mcreate_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t key_type_id, hid_t val_type_id, hid_t lcpl_id, hid_t mcpl_id, hid_t mapl_id, hid_t es_id); + +/** + * \ingroup H5M + * + * \brief + * + * \details + * + * \since 1.13.0 + * + */ H5_DLL hid_t H5Mcreate_anon(hid_t loc_id, hid_t key_type_id, hid_t val_type_id, hid_t mcpl_id, hid_t mapl_id); + +/** + * \ingroup H5M + * + * \brief Opens a map object + * + * \fgdta_loc_id{loc_id} + * \param[in] name Map object name relative to \p loc_id + * \mapl_id + * \returns \hid_t{map object} + * + * \details H5Mopen() finds a map object specified by \p name under the location + * specified by \p loc_id. The map object should be close with + * H5Mclose() when the application is not longer interested in + * accessing it. + * + * \since 1.13.0 + * + */ H5_DLL hid_t H5Mopen(hid_t loc_id, const char *name, hid_t mapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mopen} + */ H5_DLL hid_t H5Mopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t mapl_id, hid_t es_id); + +/** + * \ingroup H5M + * + * \brief Terminates access to a map object + * + * \map_id + * \returns \herr_t + * + * \details H5Mclose() closes access to a map object specified by \p map_id and + * releases resources used by it. + * + * It is illegal to subsequently use that same map identifier in calls + * to other map functions. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mclose(hid_t map_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mclose} + */ H5_DLL herr_t H5Mclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, hid_t es_id); -H5_DLL hid_t H5Mget_key_type(hid_t map_id); -H5_DLL hid_t H5Mget_val_type(hid_t map_id); -H5_DLL hid_t H5Mget_create_plist(hid_t map_id); -H5_DLL hid_t H5Mget_access_plist(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets key datatype for a map object + * + * \map_id + * \returns \hid_t{datatype} + * + * \details H5Mget_key_type() retrieves key datatype as stored in the file for a + * map object specified by \p map_id and returns identifier for the + * datatype. + * + * \since 1.13.0 + * + */ +H5_DLL hid_t H5Mget_key_type(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets value datatype for a map object + * + * \map_id + * \returns \hid_t{datatype} + * + * \details H5Mget_val_type() retrieves value datatype as stored in the file for + * a map object specified by \p map_id and returns identifier for the + * datatype . + * + * \since 1.13.0 + * + */ +H5_DLL hid_t H5Mget_val_type(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets creation property list for a map object + * + * \map_id + * \returns \hid_t{map creation property list} + * + * \details H5Mget_create_plist() returns an identifier for a copy of the + * creation property list for a map object specified by \p map_id. + * + * \since 1.13.0 + * + */ +H5_DLL hid_t H5Mget_create_plist(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Gets access property list for a map object + * + * \map_id + * \returns \hid_t{map access property list} + * + * \details H5Mget_access_plist() returns an identifier for a copy of the access + * property list for a map object specified by \p map_id. + * + * \since 1.13.0 + * + */ +H5_DLL hid_t H5Mget_access_plist(hid_t map_id); + +/** + * \ingroup H5M + * + * \brief Retrieves the number of key-value pairs in a map object + * + * \map_id + * \param[out] count The number of key-value pairs stored in the map object + * \dxpl_id + * \returns \herr_t + * + * \details H5Mget_count() retrieves the number of key-value pairs stored in a + * map specified by map_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mget_count(hid_t map_id, hsize_t *count, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Adds a key-value pair to a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \type_id{val_mem_type_id} + * \param[in] value Pointer to value buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mput() adds a key-value pair to a map object specified by \p + * map_id, or updates the value for the specified key if one was set + * previously. + * + * \p key_mem_type_id and \p val_mem_type_id specify the datatypes for + * the provided key and value buffers, and if different from those used + * to create the map object, the key and value will be internally + * converted to the datatypes for the map object. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mput(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, const void *value, hid_t dxpl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mput} + */ H5_DLL herr_t H5Mput_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, const void *value, hid_t dxpl_id, hid_t es_id); + +/** + * \ingroup H5M + * + * \brief Retrieves a key-value pair from a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \type_id{val_mem_type_id} + * \param[out] value Pointer to value buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mget() retrieves from a map object specified by \p map_id, the + * value associated with the provided key \p key. \p key_mem_type_id + * and \p val_mem_type_id specify the datatypes for the provided key + * and value buffers. If if the datatype specified by \p + * key_mem_type_id is different from that used to create the map object + * the key will be internally converted to the datatype for the map + * object for the query, and if the datatype specified by \p + * val_mem_type_id is different from that used to create the map object + * the returned value will be converted to have a datatype as specified + * by \p val_mem_type_id before the function returns. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mget(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value, hid_t dxpl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mget} + */ H5_DLL herr_t H5Mget_async(const char *app_file, const char *app_func, unsigned app_line, hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t val_mem_type_id, void *value, hid_t dxpl_id, hid_t es_id); + +/** + * \ingroup H5M + * + * \brief Checks if provided key exists in a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \param[out] exists Pointer to a buffer to return the existence status + * \dxpl_id + * \returns \herr_t + * + * \details H5Mexists() checks if the provided key is stored in the map object + * specified by \p map_id. If \p key_mem_type_id is different from that + * used to create the map object the key will be internally converted + * to the datatype for the map object for the query. + * + * Any further options can be specified through the property list + * \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mexists(hid_t map_id, hid_t key_mem_type_id, const void *key, hbool_t *exists, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Iterates over all key-value pairs in a map object + * + * \map_id + * \param[in,out] idx iteration index + * \type_id{key_mem_type_id} + * \param[in] op User-defined iterator function + * \op_data + * \dxpl_id + * \returns \herr_t + * + * \details H5Miterate() iterates over all key-value pairs stored in the map + * object specified by \p map_id, making the callback specified by \p + * op for each. The \p idx parameter is an in/out parameter that may be + * used to restart a previously interrupted iteration. At the start of + * iteration \p idx should be set to 0, and to restart iteration at the + * same location on a subsequent call to H5Miterate(), \p idx should be + * the same value as returned by the previous call. Iterate callback is + * defined as: + * \snippet this H5M_iterate_t_snip + * The \p key parameter is the buffer for the key for this iteration, + * converted to the datatype specified by \p key_mem_type_id. The \p + * op_data parameter is a simple pass through of the value passed to + * H5Miterate(), which can be used to store application-defined data for + * iteration. A negative return value from this function will cause + * H5Miterate() to issue an error, while a positive return value will + * cause H5Miterate() to stop iterating and return this value without + * issuing an error. A return value of zero allows iteration to continue. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Miterate(hid_t map_id, hsize_t *idx, hid_t key_mem_type_id, H5M_iterate_t op, void *op_data, hid_t dxpl_id); + +/** + * \ingroup H5M + * + * \brief Iterates over all key-value pairs in a map object + * + * \loc_id + * \param[in] map_name Map object name relative to the location specified by \p loc_id + * \param[in,out] idx Iteration index + * \type_id{key_mem_type_id} + * \param[in] op User-defined iterator function + * \op_data + * \dxpl_id + * \lapl_id + * \returns \herr_t + * + * \details H5Miterate_by_name() iterates over all key-value pairs stored in the + * map object specified by \p map_id, making the callback specified by + * \p op for each. The \p idx parameter is an in/out parameter that may + * be used to restart a previously interrupted iteration. At the start + * of iteration \p idx should be set to 0, and to restart iteration at + * the same location on a subsequent call to H5Miterate(), \p idx + * should be the same value as returned by the previous call. Iterate + * callback is defined as: + * \snippet this H5M_iterate_t_snip + * The\p key parameter is the buffer for the key for this iteration, + * converted to the datatype specified by \p key_mem_type_id. The \p + * op_data parameter is a simple pass through of the value passed to + * H5Miterate(), which can be used to store application-defined data + * for iteration. A negative return value from this function will cause + * H5Miterate() to issue an error, while a positive return value will cause + * H5Miterate() to stop iterating and return this value without issuing an + * error. A return value of zero allows iteration to continue. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *idx, hid_t key_mem_type_id, H5M_iterate_t op, void *op_data, hid_t dxpl_id, hid_t lapl_id); + +/** + * \ingroup H5M + * + * \brief Deletes a key-value pair from a map object + * + * \map_id + * \type_id{key_mem_type_id} + * \param[in] key Pointer to key buffer + * \dxpl_id + * \returns \herr_t + * + * \details H5Mdelete() deletes a key-value pair from the map object specified + * by \p map_id. \p key_mem_type_id specifies the datatype for the + * provided key buffer key, and if different from that used to create + * the map object, the key will be internally converted to the datatype + * for the map object. + * + * Any further options can be specified through the property list \p dxpl_id. + * + * \since 1.13.0 + * + */ H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t dxpl_id); /* API Wrappers for async routines */ diff --git a/src/H5Opublic.h b/src/H5Opublic.h index 04ef35b..7bc7784 100644 --- a/src/H5Opublic.h +++ b/src/H5Opublic.h @@ -86,17 +86,15 @@ #define H5O_INFO_NUM_ATTRS 0x0004u /* Fill in the num_attrs field */ #define H5O_INFO_ALL (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS) -/* Flags for H5Oget_native_info. - * Theses flags determine which fields will be filled in in the H5O_native_info_t - * struct. +//! <!-- [H5O_native_info_fields_snip] --> +/** + * Flags for H5Oget_native_info(). Theses flags determine which fields will be + * filled in in the \ref H5O_native_info_t struct. */ -//! [H5O_native_info_fields_snip] - #define H5O_NATIVE_INFO_HDR 0x0008u /* Fill in the hdr field */ #define H5O_NATIVE_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */ #define H5O_NATIVE_INFO_ALL (H5O_NATIVE_INFO_HDR | H5O_NATIVE_INFO_META_SIZE) - -//! [H5O_native_info_fields_snip] +//! <!-- [H5O_native_info_fields_snip] --> /* Convenience macro to check if the token is the 'undefined' token value */ #define H5O_IS_TOKEN_UNDEF(token) (!HDmemcmp(&(token), &(H5O_TOKEN_UNDEF), sizeof(H5O_token_t))) @@ -105,46 +103,48 @@ /* Public Typedefs */ /*******************/ -//! [H5O_type_t_snip] - -/* Types of objects in file */ +//! <!-- [H5O_type_t_snip] --> +/** + * Types of objects in file + */ typedef enum H5O_type_t { - H5O_TYPE_UNKNOWN = -1, /* Unknown object type */ - H5O_TYPE_GROUP, /* Object is a group */ - H5O_TYPE_DATASET, /* Object is a dataset */ - H5O_TYPE_NAMED_DATATYPE, /* Object is a named data type */ - H5O_TYPE_MAP, /* Object is a map */ - H5O_TYPE_NTYPES /* Number of different object types (must be last!) */ + H5O_TYPE_UNKNOWN = -1, /**< Unknown object type */ + H5O_TYPE_GROUP, /**< Object is a group */ + H5O_TYPE_DATASET, /**< Object is a dataset */ + H5O_TYPE_NAMED_DATATYPE, /**< Object is a named data type */ + H5O_TYPE_MAP, /**< Object is a map */ + H5O_TYPE_NTYPES /**< Number of different object types (must be last!) */ } H5O_type_t; +//! <!-- [H5O_type_t_snip] --> -//! [H5O_type_t_snip] - -/* Information struct for object header metadata (for H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx) */ -//! [H5O_hdr_info_t_snip] - +//! <!-- [H5O_hdr_info_t_snip] --> +/** + * Information struct for object header metadata (for + * H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx()) + */ typedef struct H5O_hdr_info_t { - unsigned version; /* Version number of header format in file */ - unsigned nmesgs; /* Number of object header messages */ - unsigned nchunks; /* Number of object header chunks */ - unsigned flags; /* Object header status flags */ + unsigned version; /**< Version number of header format in file */ + unsigned nmesgs; /**< Number of object header messages */ + unsigned nchunks; /**< Number of object header chunks */ + unsigned flags; /**< Object header status flags */ struct { - hsize_t total; /* Total space for storing object header in file */ - hsize_t meta; /* Space within header for object header metadata information */ - hsize_t mesg; /* Space within header for actual message information */ - hsize_t free; /* Free space within object header */ + hsize_t total; /**< Total space for storing object header in file */ + hsize_t meta; /**< Space within header for object header metadata information */ + hsize_t mesg; /**< Space within header for actual message information */ + hsize_t free; /**< Free space within object header */ } space; struct { - uint64_t present; /* Flags to indicate presence of message type in header */ - uint64_t shared; /* Flags to indicate message type is shared in header */ + uint64_t present; /**< Flags to indicate presence of message type in header */ + uint64_t shared; /**< Flags to indicate message type is shared in header */ } mesg; } H5O_hdr_info_t; +//! <!-- [H5O_hdr_info_t_snip] --> -//! [H5O_hdr_info_t_snip] - -//! [H5O_info2_t_snip] - -/* Data model information struct for objects */ -/* (For H5Oget_info / H5Oget_info_by_name / H5Oget_info_by_idx version 3) */ +//! <!-- [H5O_info2_t_snip] --> +/** + * Data model information struct for objects + * (For H5Oget_info(), H5Oget_info_by_name(), H5Oget_info_by_idx() version 3) + */ typedef struct H5O_info2_t { unsigned long fileno; /* File number that object is located in */ H5O_token_t token; /* Token representing the object */ @@ -156,44 +156,52 @@ typedef struct H5O_info2_t { time_t btime; /* Birth time */ hsize_t num_attrs; /* # of attributes attached to object */ } H5O_info2_t; +//! <!-- [H5O_info2_t_snip] --> -//! [H5O_info2_t_snip] - -//! [H5O_native_info_t_snip] - -/* Native file format information struct for objects */ -/* (For H5Oget_native_info / H5Oget_native_info_by_name / H5Oget_native_info_by_idx) */ +//! <!-- [H5O_native_info_t_snip] --> +/** + * Native file format information struct for objects. + * (For H5Oget_native_info(), H5Oget_native_info_by_name(), H5Oget_native_info_by_idx()) + */ typedef struct H5O_native_info_t { - H5O_hdr_info_t hdr; /* Object header information */ + H5O_hdr_info_t hdr; /**< Object header information */ /* Extra metadata storage for obj & attributes */ struct { - H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */ - H5_ih_info_t attr; /* v2 B-tree & heap for attributes */ + H5_ih_info_t obj; /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */ + H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */ } meta_size; } H5O_native_info_t; +//! <!-- [H5O_native_info_t_snip] --> -//! [H5O_native_info_t_snip] - -/* Typedef for message creation indexes */ +/** + * Typedef for message creation indexes + */ typedef uint32_t H5O_msg_crt_idx_t; -/* Prototype for H5Ovisit/H5Ovisit_by_name() operator (version 3) */ -//! [H5O_iterate2_t_snip] - +//! <!-- [H5O_iterate2_t_snip] --> +/** + * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (version 3) + */ typedef herr_t (*H5O_iterate2_t)(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data); +//! <!-- [H5O_iterate2_t_snip] --> -//! [H5O_iterate2_t_snip] - +//! <!-- [H5O_mcdt_search_ret_t_snip] --> typedef enum H5O_mcdt_search_ret_t { - H5O_MCDT_SEARCH_ERROR = -1, /* Abort H5Ocopy */ - H5O_MCDT_SEARCH_CONT, /* Continue the global search of all committed datatypes in the destination file */ - H5O_MCDT_SEARCH_STOP /* Stop the search, but continue copying. The committed datatype will be copied but - not merged. */ + H5O_MCDT_SEARCH_ERROR = -1, /**< Abort H5Ocopy */ + H5O_MCDT_SEARCH_CONT, /**< Continue the global search of all committed datatypes in the destination file + */ + H5O_MCDT_SEARCH_STOP /**< Stop the search, but continue copying. The committed datatype will be copied + but not merged. */ } H5O_mcdt_search_ret_t; +//! <!-- [H5O_mcdt_search_ret_t_snip] --> -/* Callback to invoke when completing the search for a matching committed datatype from the committed dtype - * list */ +//! <!-- [H5O_mcdt_search_cb_t_snip] --> +/** + * Callback to invoke when completing the search for a matching committed + * datatype from the committed dtype list + */ typedef H5O_mcdt_search_ret_t (*H5O_mcdt_search_cb_t)(void *op_data); +//! <!-- [H5O_mcdt_search_cb_t_snip] --> /********************/ /* Public Variables */ @@ -249,6 +257,11 @@ extern "C" { * */ H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Oopen} + */ H5_DLL hid_t H5Oopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t lapl_id, hid_t es_id); @@ -332,6 +345,11 @@ H5_DLL hid_t H5Oopen_by_token(hid_t loc_id, H5O_token_t token); */ H5_DLL hid_t H5Oopen_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Oopen_by_idx} + */ H5_DLL hid_t H5Oopen_by_idx_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, hid_t lapl_id, hid_t es_id); @@ -553,6 +571,11 @@ H5_DLL herr_t H5Oget_info3(hid_t loc_id, H5O_info2_t *oinfo, unsigned fields); */ H5_DLL herr_t H5Oget_info_by_name3(hid_t loc_id, const char *name, H5O_info2_t *oinfo, unsigned fields, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Oget_info_by_name} + */ H5_DLL herr_t H5Oget_info_by_name_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, H5O_info2_t *oinfo /*out*/, unsigned fields, hid_t lapl_id, hid_t es_id); @@ -968,7 +991,6 @@ H5_DLL herr_t H5Odecr_refcount(hid_t object_id); * - H5Pset_copy_object() * - H5Pset_create_intermediate_group() * - H5Pset_mcdt_search_cb() - * . * - Copying Committed Datatypes with #H5Ocopy - A comprehensive * discussion of copying committed datatypes (PDF) in * Advanced Topics in HDF5 @@ -980,6 +1002,11 @@ H5_DLL herr_t H5Odecr_refcount(hid_t object_id); */ H5_DLL herr_t H5Ocopy(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Ocopy} + */ H5_DLL herr_t H5Ocopy_async(const char *app_file, const char *app_func, unsigned app_line, hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id, hid_t es_id); @@ -1522,6 +1549,11 @@ H5_DLL herr_t H5Ovisit_by_name3(hid_t loc_id, const char *obj_name, H5_index_t i * */ H5_DLL herr_t H5Oclose(hid_t object_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Oclose} + */ H5_DLL herr_t H5Oclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t object_id, hid_t es_id); @@ -1572,6 +1604,11 @@ H5_DLL herr_t H5Oclose_async(const char *app_file, const char *app_func, unsigne * */ H5_DLL herr_t H5Oflush(hid_t obj_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Oflush} + */ H5_DLL herr_t H5Oflush_async(const char *app_file, const char *app_func, unsigned app_line, hid_t obj_id, hid_t es_id); /** @@ -1599,6 +1636,11 @@ H5_DLL herr_t H5Oflush_async(const char *app_file, const char *app_func, unsigne * */ H5_DLL herr_t H5Orefresh(hid_t oid); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Orefresh} + */ H5_DLL herr_t H5Orefresh_async(const char *app_file, const char *app_func, unsigned app_line, hid_t oid, hid_t es_id); @@ -1873,46 +1915,49 @@ H5_DLLVAR const H5O_token_t H5O_TOKEN_UNDEF_g; /* Typedefs */ -/* A struct that's part of the H5G_stat_t structure (deprecated) */ -//! [H5O_stat_t_snip] +//! <!-- [H5O_stat_t_snip] --> +/** + * A struct that's part of the \ref H5G_stat_t structure + * \deprecated + */ typedef struct H5O_stat_t { - hsize_t size; /* Total size of object header in file */ - hsize_t free; /* Free space within object header */ - unsigned nmesgs; /* Number of object header messages */ - unsigned nchunks; /* Number of object header chunks */ + hsize_t size; /**< Total size of object header in file */ + hsize_t free; /**< Free space within object header */ + unsigned nmesgs; /**< Number of object header messages */ + unsigned nchunks; /**< Number of object header chunks */ } H5O_stat_t; -//! [H5O_stat_t_snip] - -//! [H5O_info1_t_snip] +//! <!-- [H5O_stat_t_snip] --> -/* Information struct for object */ -/* (For H5Oget_info/H5Oget_info_by_name/H5Oget_info_by_idx versions 1 & 2) */ +//! <!-- [H5O_info1_t_snip] --> +/** + * Information struct for object (For H5Oget_info(), H5Oget_info_by_name(), + * H5Oget_info_by_idx() versions 1 & 2.) + */ typedef struct H5O_info1_t { - unsigned long fileno; /* File number that object is located in */ - haddr_t addr; /* Object address in file */ - H5O_type_t type; /* Basic object type (group, dataset, etc.) */ - unsigned rc; /* Reference count of object */ - time_t atime; /* Access time */ - time_t mtime; /* Modification time */ - time_t ctime; /* Change time */ - time_t btime; /* Birth time */ - hsize_t num_attrs; /* # of attributes attached to object */ - H5O_hdr_info_t hdr; /* Object header information */ + unsigned long fileno; /**< File number that object is located in */ + haddr_t addr; /**< Object address in file */ + H5O_type_t type; /**< Basic object type (group, dataset, etc.) */ + unsigned rc; /**< Reference count of object */ + time_t atime; /**< Access time */ + time_t mtime; /**< Modification time */ + time_t ctime; /**< Change time */ + time_t btime; /**< Birth time */ + hsize_t num_attrs; /**< # of attributes attached to object */ + H5O_hdr_info_t hdr; /**< Object header information */ /* Extra metadata storage for obj & attributes */ struct { - H5_ih_info_t obj; /* v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */ - H5_ih_info_t attr; /* v2 B-tree & heap for attributes */ + H5_ih_info_t obj; /**< v1/v2 B-tree & local/fractal heap for groups, B-tree for chunked datasets */ + H5_ih_info_t attr; /**< v2 B-tree & heap for attributes */ } meta_size; } H5O_info1_t; +//! <!-- [H5O_info1_t_snip] --> -//! [H5O_info1_t_snip] - -/* Prototype for H5Ovisit/H5Ovisit_by_name() operator (versions 1 & 2) */ -//! [H5O_iterate1_t_snip] - +//! <!-- [H5O_iterate1_t_snip] --> +/** + * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (versions 1 & 2) + */ typedef herr_t (*H5O_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t *info, void *op_data); - -//! [H5O_iterate1_t_snip] +//! <!-- [H5O_iterate1_t_snip] --> /* Function prototypes */ diff --git a/src/H5PLpublic.h b/src/H5PLpublic.h index c3555bc..55ff594 100644 --- a/src/H5PLpublic.h +++ b/src/H5PLpublic.h @@ -28,8 +28,7 @@ */ #define H5PL_NO_PLUGIN "::" -//! [H5PL_type_t_snip] - +//! <!-- [H5PL_type_t_snip] --> /** * Plugin type (bit-position) used by the plugin library */ @@ -39,8 +38,7 @@ typedef enum H5PL_type_t { H5PL_TYPE_VOL = 1, /**< VOL driver */ H5PL_TYPE_NONE = 2 /**< Sentinel: This must be last! */ } H5PL_type_t; - -//! [H5PL_type_t_snip] +//! <!-- [H5PL_type_t_snip] --> /* Common dynamic plugin type flags used by the set/get_loading_state functions */ #define H5PL_FILTER_PLUGIN 0x0001 diff --git a/src/H5Pmodule.h b/src/H5Pmodule.h index 130cb90..18f30c6 100644 --- a/src/H5Pmodule.h +++ b/src/H5Pmodule.h @@ -44,7 +44,6 @@ * and compressed. * * \todo Describe concisely what the functions in this module are about. - * \todo Clicking on "more" after "Property List Interface" at the top does not work * * \defgroup GPLO General Property List Operations * \ingroup H5P @@ -70,6 +69,10 @@ * \ingroup H5P * \defgroup OCPPL Object Copy Properties * \ingroup H5P + * \defgroup GACPL General Access Properties + * \ingroup H5P + * \defgroup MAPL Map Access Properties + * \ingroup H5P */ #endif /* H5Pmodule_H */ diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h index 801c561..6235ac8 100644 --- a/src/H5Ppublic.h +++ b/src/H5Ppublic.h @@ -111,23 +111,50 @@ extern "C" { /*******************/ /* Define property list class callback function pointer types */ -//! [H5P_cls_create_func_t_snip] +//! <!-- [H5P_cls_create_func_t_snip] --> typedef herr_t (*H5P_cls_create_func_t)(hid_t prop_id, void *create_data); -//! [H5P_cls_create_func_t_snip] -//! [H5P_cls_copy_func_t_snip] +//! <!-- [H5P_cls_create_func_t_snip] --> + +//! <!-- [H5P_cls_copy_func_t_snip] --> typedef herr_t (*H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data); -//! [H5P_cls_copy_func_t_snip] -//! [H5P_cls_close_func_t_snip] +//! <!-- [H5P_cls_copy_func_t_snip] --> + +//! <!-- [H5P_cls_close_func_t_snip] --> typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); -//! [H5P_cls_close_func_t_snip] +//! <!-- [H5P_cls_close_func_t_snip] --> /* Define property list callback function pointer types */ -//! [H5P_prp_cb1_t_snip] +//! <!-- [H5P_prp_cb1_t_snip] --> +/** + * \brief Callback function for H5Pregister2(),H5Pregister1(),H5Pinsert2(),H5Pinsert1() + * + * \param[in] name The name of the property + * \param[in] size The size of the property in bytes + * \param[in,out] value The value for the property + * \return \herr_t + * + * \details The H5P_prp_cb1_t() describes the parameters used by the + * property create,copy and close callback functions. + */ typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); -//! [H5P_prp_cb1_t_snip] -//! [H5P_prp_cb2_t_snip] +//! <!-- [H5P_prp_cb1_t_snip] --> + +//! <!-- [H5P_prp_cb2_t_snip] --> +/** + * \brief Callback function for H5Pregister2(),H5Pregister1(),H5Pinsert2(),H5Pinsert1() + * + * \plist_id{prop_id} + * \param[in] name The name of the property + * \param[in] size The size of the property in bytes + * \param[in] value The value for the property + * \return \herr_t + * + * \details The H5P_prp_cb2_t() describes the parameters used by the + * property set ,copy and delete callback functions. + */ typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, void *value); -//! [H5P_prp_cb2_t_snip] +//! <!-- [H5P_prp_cb2_t_snip] --> + typedef H5P_prp_cb1_t H5P_prp_create_func_t; typedef H5P_prp_cb2_t H5P_prp_set_func_t; typedef H5P_prp_cb2_t H5P_prp_get_func_t; @@ -135,60 +162,93 @@ typedef herr_t (*H5P_prp_encode_func_t)(const void *value, void **buf, size_t *s typedef herr_t (*H5P_prp_decode_func_t)(const void **buf, void *value); typedef H5P_prp_cb2_t H5P_prp_delete_func_t; typedef H5P_prp_cb1_t H5P_prp_copy_func_t; -//! [H5P_prp_compare_func_t_snip] + +//! <!-- [H5P_prp_compare_func_t_snip] --> typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size); -//! [H5P_prp_compare_func_t_snip] +//! <!-- [H5P_prp_compare_func_t_snip] --> + typedef H5P_prp_cb1_t H5P_prp_close_func_t; /* Define property list iteration function type */ -//! [H5P_iterate_t_snip] +//! <!-- [H5P_iterate_t_snip] --> typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data); -//! [H5P_iterate_t_snip] +//! <!-- [H5P_iterate_t_snip] --> -/* Actual IO mode property */ +//! <!--[H5D_mpio_actual_chunk_opt_mode_t_snip] --> +/** + * Actual IO mode property + * + * \details The default value, #H5D_MPIO_NO_CHUNK_OPTIMIZATION, is used for all + * I/O operations that do not use chunk optimizations, including + * non-collective I/O and contiguous collective I/O. + */ typedef enum H5D_mpio_actual_chunk_opt_mode_t { - /* The default value, H5D_MPIO_NO_CHUNK_OPTIMIZATION, is used for all I/O - * operations that do not use chunk optimizations, including non-collective - * I/O and contiguous collective I/O. - */ H5D_MPIO_NO_CHUNK_OPTIMIZATION = 0, + /**< No chunk optimization was performed. Either no collective I/O was + attempted or the dataset wasn't chunked. */ H5D_MPIO_LINK_CHUNK, + /**< Collective I/O is performed on all chunks simultaneously. */ H5D_MPIO_MULTI_CHUNK + /**< Each chunk was individually assigned collective or independent I/O based + on what fraction of processes access the chunk. If the fraction is greater + than the multi chunk ratio threshold, collective I/O is performed on that + chunk. The multi chunk ratio threshold can be set using + H5Pset_dxpl_mpio_chunk_opt_ratio(). The default value is 60%. */ } H5D_mpio_actual_chunk_opt_mode_t; +//! <!--[H5D_mpio_actual_chunk_opt_mode_t_snip] --> +//! <!-- [H5D_mpio_actual_io_mode_t_snip] --> +/** + * The following values are conveniently defined as a bit field so that + * we can switch from the default to independent or collective and then to + * mixed without having to check the original value. + */ typedef enum H5D_mpio_actual_io_mode_t { - /* The following four values are conveniently defined as a bit field so that - * we can switch from the default to independent or collective and then to - * mixed without having to check the original value. - * - * NO_COLLECTIVE means that either collective I/O wasn't requested or that - * no I/O took place. - * - * CHUNK_INDEPENDENT means that collective I/O was requested, but the - * chunk optimization scheme chose independent I/O for each chunk. - */ - H5D_MPIO_NO_COLLECTIVE = 0x0, + H5D_MPIO_NO_COLLECTIVE = 0x0, + /**< No collective I/O was performed. Collective I/O was not requested or + collective I/O isn't possible on this dataset */ H5D_MPIO_CHUNK_INDEPENDENT = 0x1, - H5D_MPIO_CHUNK_COLLECTIVE = 0x2, - H5D_MPIO_CHUNK_MIXED = 0x1 | 0x2, - - /* The contiguous case is separate from the bit field. */ + /**< HDF5 performed one the chunk collective optimization schemes and each + chunk was accessed independently */ + H5D_MPIO_CHUNK_COLLECTIVE = 0x2, + /**< HDF5 performed one the chunk collective optimization schemes and each + chunk was accessed collectively */ + H5D_MPIO_CHUNK_MIXED = 0x1 | 0x2, + /**< HDF5 performed one the chunk collective optimization schemes and some + chunks were accessed independently, some collectively. */ + /** \internal The contiguous case is separate from the bit field. */ H5D_MPIO_CONTIGUOUS_COLLECTIVE = 0x4 + /**< Collective I/O was performed on a contiguous dataset */ } H5D_mpio_actual_io_mode_t; +//! <!-- [H5D_mpio_actual_io_mode_t_snip] --> -/* Broken collective IO property */ +//! <!-- [H5D_mpio_no_collective_cause_t_snip] --> +/** + * Broken collective IO property + */ typedef enum H5D_mpio_no_collective_cause_t { - H5D_MPIO_COLLECTIVE = 0x00, - H5D_MPIO_SET_INDEPENDENT = 0x01, - H5D_MPIO_DATATYPE_CONVERSION = 0x02, - H5D_MPIO_DATA_TRANSFORMS = 0x04, - H5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED = 0x08, - H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES = 0x10, - H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET = 0x20, - H5D_MPIO_PARALLEL_FILTERED_WRITES_DISABLED = 0x40, + H5D_MPIO_COLLECTIVE = 0x00, + /**< Collective I/O was performed successfully */ + H5D_MPIO_SET_INDEPENDENT = 0x01, + /**< Collective I/O was not performed because independent I/O was requested */ + H5D_MPIO_DATATYPE_CONVERSION = 0x02, + /**< Collective I/O was not performed because datatype conversions were required */ + H5D_MPIO_DATA_TRANSFORMS = 0x04, + /**< Collective I/O was not performed because data transforms needed to be applied */ + H5D_MPIO_MPI_OPT_TYPES_ENV_VAR_DISABLED = 0x08, + /**< \todo FIXME! */ + H5D_MPIO_NOT_SIMPLE_OR_SCALAR_DATASPACES = 0x10, + /**< Collective I/O was not performed because one of the dataspaces was neither simple nor scalar */ + H5D_MPIO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET = 0x20, + /**< Collective I/O was not performed because the dataset was neither contiguous nor chunked */ + H5D_MPIO_PARALLEL_FILTERED_WRITES_DISABLED = 0x40, + /**< \todo FIXME! */ H5D_MPIO_ERROR_WHILE_CHECKING_COLLECTIVE_POSSIBLE = 0x80, - H5D_MPIO_NO_COLLECTIVE_MAX_CAUSE = 0x100 + /**< \todo FIXME! */ + H5D_MPIO_NO_COLLECTIVE_MAX_CAUSE = 0x100 + /**< Sentinel */ } H5D_mpio_no_collective_cause_t; +//! <!-- [H5D_mpio_no_collective_cause_t_snip] --> /********************/ /* Public Variables */ @@ -493,8 +553,6 @@ H5_DLL hid_t H5Pcreate(hid_t cls_id); * list of this class is being created. The #H5P_cls_create_func_t * callback function is defined as follows: * - * \todo fix snippets to work, when you click on them. - * * \snippet this H5P_cls_create_func_t_snip * * The parameters to this callback function are defined as follows: @@ -1233,8 +1291,6 @@ H5_DLL herr_t H5Pget_size(hid_t id, const char *name, size_t *size); * property list objects; the initial value is assumed to * have any necessary setup already performed on it. * - * \todo "cpp_note" goes here - * * \since 1.8.0 * */ @@ -1326,9 +1382,6 @@ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); * If the membership changes during the iteration, the function's * behavior is undefined. * - * - * \todo "cpp_note" goes here - * * \since 1.4.0 * */ @@ -1582,16 +1635,12 @@ H5_DLL int H5Piterate(hid_t id, int *idx, H5P_iterate_t iter_func, void *iter_da * property is being closed. The #H5P_prp_close_func_t callback * function is defined as follows: * - * \snippet this H5P_prp_cb2_t_snip + * \snippet this H5P_prp_cb1_t_snip * * The parameters to the callback function are defined as follows: * * <table> * <tr> - * <td>\ref hid_t \c prop_id</td> - * <td>IN: The identifier of the property list being closed</td> - * </tr> - * <tr> * <td>\Code{const char * name}</td> * <td>IN: The name of the property in the list</td> * </tr> @@ -1611,8 +1660,6 @@ H5_DLL int H5Piterate(hid_t id, int *idx, H5P_iterate_t iter_func, void *iter_da * list close routine returns an error value but the property list is * still closed. * - * \todo "cpp_note" goes here - * * \since 1.8.0 * */ @@ -1701,7 +1748,7 @@ H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name); /* Object creation property list (OCPL) routines */ /** - * \ingroup OCPL + * \ingroup DCPL * * \brief Verifies that all required filters are available * @@ -1805,7 +1852,7 @@ H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, un * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in * H5Ppublic.h * - * \plist_id{plist_id} + * \ocpl_id{plist_id} * \param[in] idx Sequence number within the filter pipeline of the filter * for which information is sought * \param[out] flags Bit vector specifying certain general properties of the @@ -1869,7 +1916,7 @@ H5_DLL H5Z_filter_t H5Pget_filter2(hid_t plist_id, unsigned idx, unsigned int *f * * \brief Returns information about the specified filter * - * \plist_id + * \ocpl_id{plist_id} * \param[in] filter_id Filter identifier * \param[out] flags Bit vector specifying certain general * properties of the filter @@ -1927,10 +1974,7 @@ H5_DLL herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t filter_id, unsig * * \brief Returns the number of filters in the pipeline * - * \todo Signature for H5Pget_nfilters() is different in H5Pocpl.c than in - * H5Ppublic.h. - * - * \plist_id + * \ocpl_id{plist_id} * * \return Returns the number of filters in the pipeline if successful; * otherwise returns a negative value. @@ -1938,8 +1982,8 @@ H5_DLL herr_t H5Pget_filter_by_id2(hid_t plist_id, H5Z_filter_t filter_id, unsig * \details H5Pget_nfilters() returns the number of filters defined in the * filter pipeline associated with the property list \p plist_id. * - * In each pipeline, the filters are numbered from 0 through N-1, - * where N is the value returned by this function. During output to + * In each pipeline, the filters are numbered from 0 through \Code{N-1}, + * where \c N is the value returned by this function. During output to * the file, the filters are applied in increasing order; during * input from the file, they are applied in decreasing order. * @@ -1987,7 +2031,7 @@ H5_DLL herr_t H5Pget_obj_track_times(hid_t plist_id, hbool_t *track_times); * * \brief Modifies a filter in the filter pipeline * - * \plist_id + * \ocpl_id{plist_id} * \param[in] filter Filter to be modified * \param[in] flags Bit vector specifying certain general properties * of the filter @@ -2016,7 +2060,7 @@ H5_DLL herr_t H5Pmodify_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int * * \brief Delete one or more filters in the filter pipeline * - * \plist_id + * \ocpl_id{plist_id} * \param[in] filter Filter to be deleted * * \return \herr_t @@ -2170,7 +2214,7 @@ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, uns * * \brief Sets deflate (GNU gzip) compression method and compression level * - * \plist_id + * \ocpl_id{plist_id} * \param[in] level Compression level * * \return \herr_t @@ -2226,7 +2270,7 @@ H5_DLL herr_t H5Pset_deflate(hid_t plist_id, unsigned level); * * \brief Adds a filter to the filter pipeline * - * \param[in] plist_id Dataset or group creation property list identifier + * \ocpl_id{plist_id} * \param[in] filter Filter identifier for the filter to be added to the * pipeline * \param[in] flags Bit vector specifying certain general properties of @@ -2478,7 +2522,7 @@ H5_DLL herr_t H5Pset_deflate(hid_t plist_id, unsigned level); * (The SZIP filter is an exception to this rule; see H5Pset_szip() * for details.) * - * \todo Removed several references to links to documentation + * \see \ref_filter_pipe, \ref_group_impls * * \version 1.8.5 Function applied to group creation property lists. * \since 1.6.0 @@ -2491,7 +2535,7 @@ H5_DLL herr_t H5Pset_filter(hid_t plist_id, H5Z_filter_t filter, unsigned int fl * * \brief Sets up use of the Fletcher32 checksum filter * - * \param[in] plist_id Dataset or group creation property list identifier + * \ocpl_id{plist_id} * * \return \herr_t * @@ -2672,7 +2716,7 @@ H5_DLL herr_t H5Pget_shared_mesg_index(hid_t plist_id, unsigned index_num, unsig /** * \ingroup FCPL * - * \brief Retrieves number of shared object header message indexes in file + * \brief Retrieves the number of shared object header message indexes in file * creation property list * * \fcpl_id{plist_id} @@ -3237,8 +3281,8 @@ H5_DLL herr_t H5Pget_core_write_tracking(hid_t fapl_id, hbool_t *is_enabled, siz * <td>#H5FD_SEC2</td> * <td>This driver uses POSIX file-system functions like read and * write to perform I/O to a single, permanent file on local disk - * with no system buffering. This driver is POSIX-compliant and is - * the default file driver for all systems.</td> + * with no system buffering. This driver is POSIX-compliant and + * is the default file driver for all systems.</td> * <td>H5Pset_fapl_sec2()</td> * </tr> * <tr> @@ -3276,8 +3320,9 @@ H5_DLL herr_t H5Pget_core_write_tracking(hid_t fapl_id, hbool_t *is_enabled, siz * <td>#H5FD_CORE</td> * <td>With this driver, an application can work with a file in * memory for faster reads and writes. File contents are kept in - * memory until the file is closed. At closing, the memory version - * of the file can be written back to disk or abandoned.</td> + * memory until the file is closed. At closing, the memory + * version of the file can be written back to disk or abandoned. + * </td> * <td>H5Pset_fapl_core()</td> * </tr> * <tr> @@ -3286,7 +3331,8 @@ H5_DLL herr_t H5Pget_core_write_tracking(hid_t fapl_id, hbool_t *is_enabled, siz * <td>With this driver, the HDF5 file’s address space is partitioned * into pieces and sent to separate storage files using an * underlying driver of the user’s choice. This driver is for - * systems that do not support files larger than 2 gigabytes.</td> + * systems that do not support files larger than 2 gigabytes. + * </td> * <td>H5Pset_fapl_family()</td> * </tr> * <tr> @@ -3352,7 +3398,7 @@ H5_DLL hid_t H5Pget_driver(hid_t plist_id); * struct. Driver-specific versions of that struct are defined * for each low-level driver in the relevant source code file * H5FD*.c. For example, the struct used for the MULTI driver is - * #H5FD_multi_fapl_t defined in H5FDmulti.c. + * \c H5FD_multi_fapl_t defined in H5FDmulti.c. * * If no driver-specific properties have been registered, * H5Pget_driver_info() returns NULL. @@ -3369,8 +3415,50 @@ H5_DLL hid_t H5Pget_driver(hid_t plist_id); * */ H5_DLL const void *H5Pget_driver_info(hid_t plist_id); -H5_DLL herr_t H5Pget_elink_file_cache_size(hid_t plist_id, unsigned *efc_size); -H5_DLL herr_t H5Pget_evict_on_close(hid_t fapl_id, hbool_t *evict_on_close); +/** + * \ingroup FAPL + * + * \brief Retrieves the size of the external link open file cache + * + * \fapl_id{plist_id} + * \param[out] efc_size External link open file cache size in number of files + * + * \return \herr_t + * + * \details H5Pget_elink_file_cache_size() retrieves the number of files that + * can be held open in an external link open file cache. + * + * \since 1.8.7 + * + */ +H5_DLL herr_t H5Pget_elink_file_cache_size(hid_t plist_id, unsigned *efc_size); +/** + * \ingroup FAPL + * + * \brief Retrieves the file access property list setting that determines + * whether an HDF5 object will be evicted from the library's metadata + * cache when it is closed + * + * \fapl_id + * \param[out] evict_on_close Pointer to a variable that will indicate if + * the object will be evicted on close + * + * \return \herr_t + * + * \details The library's metadata cache is fairly conservative about holding on + * to HDF5 object metadata (object headers, chunk index structures, + * etc.), which can cause the cache size to grow, resulting in memory + * pressure on an application or system. When enabled, the "evict on + * close" property will cause all metadata for an object to be + * immediately evicted from the cache as long as it is not referenced + * by any other open object. + * + * See H5Pset_evict_on_close() for additional notes on behavior. + * + * \since 1.10.1 + * + */ +H5_DLL herr_t H5Pget_evict_on_close(hid_t fapl_id, hbool_t *evict_on_close); /** * \ingroup FAPL * @@ -3386,9 +3474,7 @@ H5_DLL herr_t H5Pget_evict_on_close(hid_t fapl_id, hbool_t *evict_on_close) * application can retrieve a file handle for low-level access to * a particular member of a family of files. The file handle is * retrieved with a separate call to H5Fget_vfd_handle() (or, - * in special circumstances, to H5FDget_vfd_handle()). - * - * \todo References the VFL documentation. + * in special circumstances, to H5FDget_vfd_handle(), see \ref VFL). * * \since 1.6.0 * @@ -3415,8 +3501,113 @@ H5_DLL herr_t H5Pget_family_offset(hid_t fapl_id, hsize_t *offset); * */ H5_DLL herr_t H5Pget_fclose_degree(hid_t fapl_id, H5F_close_degree_t *degree); +/** + * \ingroup FAPL + * + * \brief Retrieves a copy of the file image designated as the initial content + * and structure of a file + * + * \fapl_id + * \param[in,out] buf_ptr_ptr On input, \c NULL or a pointer to a + * pointer to a buffer that contains the + * file image.\n On successful return, if \p buf_ptr_ptr is not + * \c NULL, \Code{*buf_ptr_ptr} will contain a pointer to a copy + * of the initial image provided in the last call to + * H5Pset_file_image() for the supplied \p fapl_id. If no initial + * image has been set, \Code{*buf_ptr_ptr} will be \c NULL. + * \param[in,out] buf_len_ptr On input, \c NULL or a pointer to a buffer + * specifying the required size of the buffer to hold the file + * image.\n On successful return, if \p buf_len_ptr was not + * passed in as \c NULL, \p buf_len_ptr will return the required + * size in bytes of the buffer to hold the initial file image in + * the supplied file access property list, \p fapl_id. If no + * initial image is set, the value of \Code{*buf_len_ptr} will be + * set to 0 (zero) + * \return \herr_t + * + * \details H5Pget_file_image() allows an application to retrieve a copy of the + * file image designated for a VFD to use as the initial contents of a file. + * + * If file image callbacks are defined, H5Pget_file_image() will use + * them when allocating and loading the buffer to return to the + * application (see H5Pset_file_image_callbacks()). If file image + * callbacks are not defined, the function will use \c malloc and \c + * memcpy. When \c malloc and \c memcpy are used, it is the caller’s + * responsibility to discard the returned buffer with a call to \c + * free. + * + * It is the responsibility of the calling application to free the + * buffer whose address is returned in \p buf_ptr_ptr. This can be + * accomplished with \c free if file image callbacks have not been set + * (see H5Pset_file_image_callbacks()) or with the appropriate method + * if file image callbacks have been set. + * + * \see H5LTopen_file_image(), H5Fget_file_image(), H5Pset_file_image(), + * H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks(), + * \ref H5FD_file_image_callbacks_t, \ref H5FD_file_image_op_t, + * <a href="https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations"> + * HDF5 File Image Operations</a>. + * + * + * \since 1.8.9 + * + */ H5_DLL herr_t H5Pget_file_image(hid_t fapl_id, void **buf_ptr_ptr, size_t *buf_len_ptr); +/** + * \ingroup FAPL + * + * \brief Retrieves callback routines for working with file images + * + * \fapl_id + * \param[in,out] callbacks_ptr Pointer to the instance of the + * #H5FD_file_image_callbacks_t struct in which the callback + * routines are to be returned\n + * Struct fields must be initialized to NULL before the call + * is made.\n + * Struct field contents upon return will match those passed in + * in the last H5Pset_file_image_callbacks() call for the file + * access property list \p fapl_id. + * \return \herr_t + * + * \details H5Pget_file_image_callbacks() retrieves the callback routines set for + * working with file images opened with the file access property list + * \p fapl_id. + * + * The callbacks must have been previously set with + * H5Pset_file_image_callbacks() in the file access property list. + * + * Upon the successful return of H5Pset_file_image_callbacks(), the + * fields in the instance of the #H5FD_file_image_callbacks_t struct + * pointed to by \p callbacks_ptr will contain the same values as were + * passed in the most recent H5Pset_file_image_callbacks() call for the + * file access property list \p fapl_id. + * + * \see H5LTopen_file_image(), H5Fget_file_image(), H5Pset_file_image(), + * H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks(), + * \ref H5FD_file_image_callbacks_t, \ref H5FD_file_image_op_t, + * <a href="https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations"> + * HDF5 File Image Operations</a>. + * + * \since 1.8.9 + * + */ H5_DLL herr_t H5Pget_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr); +/** + * \ingroup FAPL + * + * \brief Retrieves the file locking property values + * + * \fapl_id + * \param[out] use_file_locking File locking flag + * \param[out] ignore_when_disabled Ignore when disabled flag + * \return \herr_t + * + * \details H5Pget_file_locking() retrieves the file locking property values for + * the file access property list specified by \p fapl_id. + * + * \since 1.10.7 + * + */ H5_DLL herr_t H5Pget_file_locking(hid_t fapl_id, hbool_t *use_file_locking, hbool_t *ignore_when_disabled); /** * \ingroup FAPL @@ -3471,11 +3662,212 @@ H5_DLL herr_t H5Pget_gc_references(hid_t fapl_id, unsigned *gc_ref /*out*/); * */ H5_DLL herr_t H5Pget_libver_bounds(hid_t plist_id, H5F_libver_t *low, H5F_libver_t *high); +/** + * \ingroup FAPL + * + * \brief Get the current initial metadata cache configuration from the + * provided file access property list + * + * \fapl_id{plist_id} + * \param[in,out] config_ptr Pointer to the instance of #H5AC_cache_config_t + * in which the current metadata cache configuration is to be + * reported + * \return \herr_t + * + * \note The \c in direction applies only to the \ref H5AC_cache_config_t.version + * field. All other fields are \c out parameters. + * + * \details The fields of the #H5AC_cache_config_t structure are shown + * below: + * \snippet H5ACpublic.h H5AC_cache_config_t_snip + * \click4more + * + * H5Pget_mdc_config() gets the initial metadata cache configuration + * contained in a file access property list and loads it into the + * instance of #H5AC_cache_config_t pointed to by the \p config_ptr + * parameter. This configuration is used when the file is opened. + * + * Note that the version field of \Code{*config_ptr} must be + * initialized; this allows the library to support earlier versions of + * the #H5AC_cache_config_t structure. + * + * See the overview of the metadata cache in the special topics section + * of the user guide for details on the configuration data returned. If + * you haven't read and understood that documentation, the results of + * this call will not make much sense. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pget_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr); /* out */ +/** + * \ingroup FAPL + * + * \brief Retrieves the metadata cache image configuration values for a file + * access property list + * + * \fapl_id{plist_id} + * \param[out] config_ptr Pointer to metadata cache image configuration values + * \return \herr_t + * + * \details H5Pget_mdc_image_config() retrieves the metadata cache image values + * into \p config_ptr for the file access property list specified in \p + * plist_id. + * + * #H5AC_cache_image_config_t is defined as follows: + * \snippet H5ACpublic.h H5AC_cache_image_config_t_snip + * \click4more + * + * \since 1.10.1 + */ H5_DLL herr_t H5Pget_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config_ptr /*out*/); +/** + * \ingroup FAPL + * + * \brief Gets metadata cache logging options + * + * \fapl_id{plist_id} + * \param[out] is_enabled Flag whether logging is enabled + * \param[out] location Location of log in UTF-8/ASCII (file path/name) (On + * Windows, this must be ASCII) + * \param[out] location_size Size in bytes of the location string + * \param[out] start_on_access Whether the logging begins as soon as the file is + * opened or created + * \return \herr_t + * + * \details The metadata cache is a central part of the HDF5 library through + * which all file metadata reads and writes take place. File metadata + * is normally invisible to the user and is used by the library for + * purposes such as locating and indexing data. File metadata should + * not be confused with user metadata, which consists of attributes + * created by users and attached to HDF5 objects such as datasets via + * \ref H5A API calls. + * + * Due to the complexity of the cache, a trace/logging feature has been + * created that can be used by HDF5 developers for debugging and + * performance analysis. The functions that control this functionality + * will normally be of use to a very limited number of developers + * outside of The HDF Group. The functions have been documented to help + * users create logs that can be sent with bug reports. + * + * Control of the log functionality is straightforward. Logging is + * enabled via the H5Pset_mdc_log_options() function, which will modify + * the file access property list used to open or create a file. This + * function has a flag that determines whether logging begins at file + * open or starts in a paused state. Log messages can then be + * controlled via the H5Fstart_mdc_logging() / H5Fstop_mdc_logging() + * functions. H5Pget_mdc_log_options() can be used to examine a file + * access property list, and H5Fget_mdc_logging_status() will return + * the current state of the logging flags. + * + * The log format is described in the + * <a href="https://bit.ly/2PG6fNv">Metadata Cache Logging</a> document. + * + * \since 1.10.0 + */ H5_DLL herr_t H5Pget_mdc_log_options(hid_t plist_id, hbool_t *is_enabled, char *location, size_t *location_size, hbool_t *start_on_access); -H5_DLL herr_t H5Pget_meta_block_size(hid_t fapl_id, hsize_t *size /*out*/); +/** + * \ingroup FAPL + * + * \brief Returns the current metadata block size setting + * + * \fapl_id{fapl_id} + * \param[out] size Minimum size, in bytes, of metadata block allocations + * + * \return \herr_t + * + * \details Returns the current minimum size, in bytes, of new + * metadata block allocations. This setting is retrieved from the + * file access property list \p fapl_id. + * + * This value is set by H5Pset_meta_block_size() and is + * retrieved from the file access property list \p fapl_id. + * + * \since 1.4.0 + */ +H5_DLL herr_t H5Pget_meta_block_size(hid_t fapl_id, hsize_t *size); +/** + * \ingroup FAPL + * + * \brief Retrieves the number of read attempts from a file access + * property list + * + * \fapl_id{plist_id} + * \param[out] attempts The number of read attempts + * + * \return \herr_t + * + * \details H5Pget_metadata_read_attempts() retrieves the number of read + * attempts that is set in the file access property list \p plist_id. + * + * For a default file access property list, the value retrieved + * will depend on whether the user sets the number of attempts via + * H5Pset_metadata_read_attempts(): + * + * <ul> + * + * <li>If the number of attempts is set to N, the value + * returned will be N. + * <li>If the number of attempts is not set, the value returned + * will be the default for non-SWMR access (1). SWMR is short + * for single-writer/multiple-reader. + * </ul> + * + * For the file access property list of a specified HDF5 file, + * the value retrieved will depend on how the file is opened + * and whether the user sets the number of read attempts via + * H5Pset_metadata_read_attempts(): + * + * <ul> + * <li>For a file opened with SWMR access: + * + * <ul> + * <li> If the number of attempts is set to N, the value + * returned will be N. + * <li> If the number of attempts is not set, the value + * returned will be the default for SWMR access (100). + * </ul> + * <li>For a file opened without SWMR access, the value + * retrieved will always be the default for non-SWMR access + * (1). The value set via H5Pset_metadata_read_attempts() does + * not have any effect on non-SWMR access. + * </ul> + * + * \par Failure Modes + * \parblock + * + * When the input property list is not a file access property list. + * + * When the library is unable to retrieve the number of read attempts from + * the file access property list. + * + * \endparblock + * + * \par Examples + * \parblock + * + * The first example illustrates the two cases for retrieving the number + * of read attempts from a default file access property list. + * + * \include H5Pget_metadata_read_attempts.1.c + * + * The second example illustrates the two cases for retrieving the + * number of read attempts from the file access property list of a file + * opened with SWMR acccess. + * + * \include H5Pget_metadata_read_attempts.2.c + * + * The third example illustrates the two cases for retrieving the number + * of read attempts from the file access property list of a file opened + * with non-SWMR acccess. + * + * \include H5Pget_metadata_read_attempts.3.c + * + * \endparblock + * + * \since 1.10.0 + */ H5_DLL herr_t H5Pget_metadata_read_attempts(hid_t plist_id, unsigned *attempts); /** * \ingroup FAPL @@ -3510,10 +3902,102 @@ H5_DLL herr_t H5Pget_metadata_read_attempts(hid_t plist_id, unsigned *attempts); * */ H5_DLL herr_t H5Pget_multi_type(hid_t fapl_id, H5FD_mem_t *type); +/** + * \ingroup FAPL + * + * \brief Retrieves the object flush property values from the file access property list + * + * \fapl_id{plist_id} + * \param[in] func The user-defined callback function + * \param[in] udata The user-defined input data for the callback function + * + * \return \herr_t + * + * \details H5Pget_object_flush_cb() gets the user-defined callback + * function that is set in the file access property list + * \p fapl_id and stored in the parameter \p func. The callback is + * invoked whenever an object flush occurs in the file. This + * routine also obtains the user-defined input data that is + * passed along to the callback function in the parameter + * \p udata. + * + * \par Example + * \parblock + * The example below illustrates the usage of this routine to obtain the + * object flush property values. + * + * \include H5Pget_object_flush_cb.c + * \endparblock + * + * \since 1.10.0 + */ H5_DLL herr_t H5Pget_object_flush_cb(hid_t plist_id, H5F_flush_cb_t *func, void **udata); -H5_DLL herr_t H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned *min_meta_per, - unsigned *min_raw_per); +/** + * \ingroup FAPL + * + * \brief Retrieves the maximum size for the page buffer and the minimum + percentage for metadata and raw data pages + * + * \fapl_id{plist_id} + * \param[out] buf_size Maximum size, in bytes, of the page buffer + * \param[out] min_meta_perc Minimum metadata percentage to keep in the + * page buffer before allowing pages containing metadata to + * be evicted + * + * \param[out] min_raw_perc Minimum raw data percentage to keep in the + * page buffer before allowing pages containing raw data to + * be evicted + * + * \return \herr_t + * + * \details H5Pget_page_buffer_size() retrieves \p buf_size, the maximum + * size in bytes of the page buffer, \p min_meta_perc, the + * minimum metadata percentage, and \p min_raw_perc, the + * minimum raw data percentage. + * + * \since 1.10.1 + */ +H5_DLL herr_t H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned *min_meta_perc, + unsigned *min_raw_perc); +/** + * \ingroup FAPL + * + * \brief Returns maximum data sieve buffer size + * + * \fapl_id{fapl_id} + * \param[in] size Maximum size, in bytes, of data sieve buffer + * + * \return \herr_t + * + * \details H5Pget_sieve_buf_size() retrieves, size, the current maximum + * size of the data sieve buffer. + * + * This value is set by H5Pset_sieve_buf_size() and is retrieved + * from the file access property list fapl_id. + * + * \version 1.6.0 The \p size parameter has changed from type \c hsize_t + * to \c size_t + * \since 1.4.0 + */ H5_DLL herr_t H5Pget_sieve_buf_size(hid_t fapl_id, size_t *size /*out*/); +/** + * \ingroup FAPL + * + * \brief Retrieves the current small data block size setting + * + * \fapl_id{fapl_id} + * \param[out] size Maximum size, in bytes, of the small data block + * + * \result \herr_t + * + * \details H5Pget_small_data_block_size() retrieves the current setting + * for the size of the small data block. + * + * If the returned value is zero (0), the small data block + * mechanism has been disabled for the file. + * + * \since 1.4.4 + */ H5_DLL herr_t H5Pget_small_data_block_size(hid_t fapl_id, hsize_t *size /*out*/); /** * \ingroup FAPL @@ -3684,6 +4168,64 @@ H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignme */ H5_DLL herr_t H5Pset_cache(hid_t plist_id, int mdc_nelmts, size_t rdcc_nslots, size_t rdcc_nbytes, double rdcc_w0); +/** + * \ingroup FAPL + * + * \brief Sets write tracking information for core driver, #H5FD_CORE + * + * \fapl_id{fapl_id} + * \param[in] is_enabled Boolean value specifying whether feature is + enabled + * \param[in] page_size Positive integer specifying size, in bytes, of + * write aggregation pages Value of 1 (one) enables + * tracking with no paging. + * + * \return \herr_t + * + * \details When a file is created or opened for writing using the core + * virtual file driver (VFD) with the backing store option + * turned on, the core driver can be configured to track + * changes to the file and write out only the modified bytes. + * + * This write tracking feature is enabled and disabled with \p + * is_enabled. The default setting is that write tracking is + * disabled, or off. + * + * To avoid a large number of small writes, changes can + * be aggregated into pages of a user-specified size, \p + * page_size. + * + * Setting \p page_size to 1 enables tracking with no page + * aggregation. + * + * The backing store option is set via the function + * H5Pset_fapl_core. + * + * \attention + * \parblock + * This function is only for use with the core VFD and must + * be used after the call to H5Pset_fapl_core(). It is an error + * to use this function with any other VFD. + * + * It is an error to use this function when the backing store + * flag has not been set using H5Pset_fapl_core(). + * + * This function only applies to the backing store write + * operation which typically occurs when the file is flushed + * or closed. This function has no relationship to the + * increment parameter passed to H5Pset_fapl_core(). + * + * For optimum performance, the \p page_size parameter should be + * a power of two. + * + * It is an error to set the page size to 0. + * \endparblock + * + * \version 1.8.14 C function modified in this release to return error + * if \p page_size is set to 0 (zero). + * \since 1.8.13 + * + */ H5_DLL herr_t H5Pset_core_write_tracking(hid_t fapl_id, hbool_t is_enabled, size_t page_size); /** * \ingroup FAPL @@ -3712,8 +4254,141 @@ H5_DLL herr_t H5Pset_core_write_tracking(hid_t fapl_id, hbool_t is_enabled, size * */ H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id, const void *driver_info); +/** + * \ingroup FAPL + * + * \brief Sets the number of files that can be held open in an external + * link open file cache + * + * \par Motivation + * \parblock + * The <em>external link open file cache</em> holds files open after + * they have been accessed via an external link. This cache reduces + * the number of times such files are opened when external links are + * accessed repeatedly and can siginificantly improves performance in + * certain heavy-use situations and when low-level file opens or closes + * are expensive. + * + * H5Pset_elink_file_cache_size() sets the number of files + * that will be held open in an external link open file + * cache. H5Pget_elink_file_cache_size() retrieves the size of an existing + * cache; and H5Fclear_elink_file_cache() clears an existing cache without + * closing it. + * \endparblock + * + * \fapl_id{plist_id} + * \param[in] efc_size External link open file cache size in number of files + * <em>Default setting is 0 (zero).</em> + * + * \return \herr_t + * + * \details H5Pset_elink_file_cache_size() specifies the number of files + * that will be held open in an external link open file cache. + * + * The default external link open file cache size is 0 (zero), + * meaning that files accessed via an external link are not + * held open. Setting the cache size to a positive integer + * turns on the cache; setting the size back to zero turns it + * off. + * + * With this property set, files are placed in the external + * link open file cache cache when they are opened via an + * external link. Files are then held open until either + * they are evicted from the cache or the parent file is + * closed. This property setting can improve performance when + * external links are repeatedly accessed. + * + * When the cache is full, files will be evicted using a least + * recently used (LRU) scheme; the file which has gone the + * longest time without being accessed through the parent file + * will be evicted and closed if nothing else is holding that + * file open. + * + * Files opened through external links inherit the parent + * file’s file access property list by default, and therefore + * inherit the parent file’s external link open file cache + * setting. + * + * When child files contain external links of their own, the + * caches can form a graph of cached external files. Closing + * the last external reference to such a graph will recursively + * close all files in the graph, even if cycles are present. + * \par Example + * \parblock + * The following code sets up an external link open file cache that will + * hold open up to 8 files reached through external links: + * + * \code + * status = H5Pset_elink_file_cache_size(fapl_id, 8); + * \endcode + * \endparblock + * + * \since 1.8.7 + */ H5_DLL herr_t H5Pset_elink_file_cache_size(hid_t plist_id, unsigned efc_size); +/** + * \ingroup FAPL + * + * \brief Controls the library's behavior of evicting metadata associated with + * a closed object + * + * \fapl_id + * \param[in] evict_on_close Whether the HDF5 object should be evicted on close + * + * \return \herr_t + * + * \details The library's metadata cache is fairly conservative about holding + * on to HDF5 object metadata(object headers, chunk index structures, + * etc.), which can cause the cache size to grow, resulting in memory + * pressure on an application or system. When enabled, the "evict on + * close" property will cause all metadata for an object to be evicted + * from the cache as long as metadata is not referenced by any other + * open object. + * + * This function only applies to file access property lists. + * + * The default library behavior is to not evict on object or file + * close. + * + * When applied to a file access property list, any subsequently opened + * object will inherit the "evict on close" property and will have + * its metadata evicted when the object is closed. + * + * \since 1.10.1 + * + */ H5_DLL herr_t H5Pset_evict_on_close(hid_t fapl_id, hbool_t evict_on_close); +/** + * \ingroup FAPL + * + * \brief Sets offset property for low-level access to a file in a family of + * files + * + * \fapl_id + * \param[in] offset Offset in bytes within the HDF5 file + * + * \return \herr_t + * + * \details H5Pset_family_offset() sets the offset property in the file access + * property list \p fapl_id so that the user application can + * retrieve a file handle for low-level access to a particular member + * of a family of files. The file handle is retrieved with a separate + * call to H5Fget_vfd_handle() (or, in special circumstances, to + * H5FDget_vfd_handle(); see \ref VFL). + * + * The value of \p offset is an offset in bytes from the beginning of + * the HDF5 file, identifying a user-determined location within the + * HDF5 file. + * The file handle the user application is seeking is for the specific + * member-file in the associated family of files to which this offset + * is mapped. + * + * Use of this function is only appropriate for an HDF5 file written as + * a family of files with the \c FAMILY file driver. + * + * \since 1.6.0 + * + */ H5_DLL herr_t H5Pset_family_offset(hid_t fapl_id, hsize_t offset); /** * \ingroup FAPL @@ -3776,9 +4451,279 @@ H5_DLL herr_t H5Pset_family_offset(hid_t fapl_id, hsize_t offset); * */ H5_DLL herr_t H5Pset_fclose_degree(hid_t fapl_id, H5F_close_degree_t degree); +/** + * \ingroup FAPL + * + * \brief Sets an initial file image in a memory buffer + * + * \fapl_id + * \param[in] buf_ptr Pointer to the initial file image, or + * NULL if no initial file image is desired + * \param[in] buf_len Size of the supplied buffer, or + * 0 (zero) if no initial image is desired + * + * \return \herr_t + * + * \details H5Pset_file_image() allows an application to provide a file image + * to be used as the initial contents of a file. + * Calling H5Pset_file_image()makes a copy of the buffer specified in + * \p buf_ptr of size \p buf_len. + * + * \par Motivation: + * H5Pset_file_image() and other elements of HDF5 are + * used to load an image of an HDF5 file into system memory and open + * that image as a regular HDF5 file. An application can then use the + * file without the overhead of disk I/O. + * + * \par Recommended Reading: + * This function is part of the file image + * operations feature set. It is highly recommended to study the guide + * [<em>HDF5 File Image Operations</em>] + * (https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations + * ) before using this feature set. See the “See Also” section below + * for links to other elements of HDF5 file image operations. + * + * \see + * \li H5LTopen_file_image() + * \li H5Fget_file_image() + * \li H5Pget_file_image() + * \li H5Pset_file_image_callbacks() + * \li H5Pget_file_image_callbacks() + * + * \li [HDF5 File Image Operations] + * (https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations) + * in [Advanced Topics in HDF5] + * (https://portal.hdfgroup.org/display/HDF5/Advanced+Topics+in+HDF5) + * + * \li Within H5Pset_file_image_callbacks(): + * \li Callback #H5FD_file_image_callbacks_t + * \li Callback #H5FD_file_image_op_t + * + * \version 1.8.13 Fortran subroutine added in this release. + * \since 1.8.9 + * + */ H5_DLL herr_t H5Pset_file_image(hid_t fapl_id, void *buf_ptr, size_t buf_len); +/** + * \ingroup FAPL + * + * \brief Sets the callbacks for working with file images + * + * \note **Motivation:** H5Pset_file_image_callbacks() and other elements + * of HDF5 are used to load an image of an HDF5 file into system + * memory and open that image as a regular HDF5 file. An application + * can then use the file without the overhead of disk I/O.\n + * **Recommended Reading:** This function is part of the file + * image operations feature set. It is highly recommended to study + * the guide [HDF5 File Image Operations] + * (https://portal.hdfgroup.org/display/HDF5/HDF5+File+Image+Operations + * ) before using this feature set. See the “See Also” section below + * for links to other elements of HDF5 file image operations. + * + * \fapl_id + * \param[in,out] callbacks_ptr Pointer to the instance of the + * #H5FD_file_image_callbacks_t structure + * + * \return \herr_t \n + * **Failure Modes**: Due to interactions between this function and + * H5Pset_file_image() and H5Pget_file_image(), + * H5Pset_file_image_callbacks() will fail if a file image has + * already been set in the target file access property list, \p fapl_id. + * + * \details H5Pset_file_image_callbacks() sets callback functions for working + * with file images in memory. + * + * H5Pset_file_image_callbacks() allows an application to control the + * management of file image buffers through user defined callbacks. + * These callbacks can be used in the management of file image buffers + * in property lists and with certain file drivers. + * + * H5Pset_file_image_callbacks() must be used before any file image has + * been set in the file access property list. Once a file image has + * been set, the function will fail. + * + * The callback routines set up by H5Pset_file_image_callbacks() are + * invoked when a new file image buffer is allocated, when an existing + * file image buffer is copied or resized, or when a file image buffer + * is released from use. + * + * Some file drivers allow the use of user-defined callback functions + * for allocating, freeing, and copying the driver’s internal buffer, + * potentially allowing optimizations such as avoiding large \c malloc + * and \c memcpy operations, or to perform detailed logging. + * + * From the perspective of the HDF5 library, the operations of the + * \ref H5FD_file_image_callbacks_t.image_malloc "image_malloc", + * \ref H5FD_file_image_callbacks_t.image_memcpy "image_memcpy", + * \ref H5FD_file_image_callbacks_t.image_realloc "image_realloc", and + * \ref H5FD_file_image_callbacks_t.image_free "image_free" callbacks + * must be identical to those of the + * corresponding C standard library calls (\c malloc, \c memcpy, + * \c realloc, and \c free). While the operations must be identical, + * the file image callbacks have more parameters. The return values + * of \ref H5FD_file_image_callbacks_t.image_malloc "image_malloc" and + * \ref H5FD_file_image_callbacks_t.image_realloc "image_realloc" are identical to + * the return values of \c malloc and \c realloc. The return values of + * \ref H5FD_file_image_callbacks_t.image_malloc "image_malloc" and + * \ref H5FD_file_image_callbacks_t.image_free "image_free" differ from the return + * values of \c memcpy and \c free in that the return values of + * \ref H5FD_file_image_callbacks_t.image_memcpy "image_memcpy" and + * \ref H5FD_file_image_callbacks_t.image_free "image_free" can also indicate failure. + * + * The callbacks and their parameters, along with a struct and + * an \c ENUM required for their use, are described below. + * + * <b>Callback struct and \c ENUM:</b> + * + * The callback functions set up by H5Pset_file_image_callbacks() use + * a struct and an \c ENUM that are defined as follows + * + * The struct #H5FD_file_image_callbacks_t serves as a container + * for the callback functions and a pointer to user-supplied data. + * The struct is defined as follows: + * \snippet H5FDpublic.h H5FD_file_image_callbacks_t_snip + * + * Elements of the #H5FD_file_image_op_t are used by the + * callbacks to invoke certain operations on file images. The ENUM is + * defined as follows: + * \snippet H5FDpublic.h H5FD_file_image_op_t_snip + * + * The elements of the #H5FD_file_image_op_t are used in the following + * callbacks: + * + * - The \ref H5FD_file_image_callbacks_t.image_malloc "image_malloc" callback + * contains a pointer to a function that must appear to HDF5 to have + * functionality identical to that of the standard C library \c malloc() call. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h image_malloc_snip + * \n + * - The \ref H5FD_file_image_callbacks_t.image_memcpy "image_memcpy" + * callback contains a pointer to a function + * that must appear to HDF5 to have functionality identical to that + * of the standard C library \c memcopy() call, except that it returns + * a \p NULL on failure. (The \c memcpy C Library routine is defined + * to return the \p dest parameter in all cases.) + * + * - Setting \ref H5FD_file_image_callbacks_t.image_memcpy "image_memcpy" + * to \c NULL indicates that HDF5 should invoke + * the standard C library \c memcpy() routine when copying buffers. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h image_memcpy_snip + * \n + * - The \ref H5FD_file_image_callbacks_t.image_realloc "image_realloc" callback + * contains a pointer to a function that must appear to HDF5 to have + * functionality identical to that of the standard C library \c realloc() call. + * + * - Setting \ref H5FD_file_image_callbacks_t.image_realloc "image_realloc" + * to \p NULL indicates that HDF5 should + * invoke the standard C library \c realloc() routine when resizing + * file image buffers. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h image_realloc_snip + * \n + * - The \ref H5FD_file_image_callbacks_t.image_free "image_free" callback contains + * a pointer to a function that must appear to HDF5 to have functionality + * identical to that of the standard C library \c free() call, except + * that it will return \c 0 (\c SUCCEED) on success and \c -1 (\c FAIL) on failure. + * + * - Setting \ref H5FD_file_image_callbacks_t.image_free "image_free" + * to \c NULL indicates that HDF5 should invoke + * the standard C library \c free() routine when releasing file image + * buffers. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h image_free_snip + * \n + * - The \ref H5FD_file_image_callbacks_t.udata_copy "udata_copy" + * callback contains a pointer to a function + * that, from the perspective of HDF5, allocates a buffer of suitable + * size, copies the contents of the supplied \p udata into the new + * buffer, and returns the address of the new buffer. The function + * returns NULL on failure. This function is necessary if a non-NULL + * \p udata parameter is supplied, so that property lists containing + * the image callbacks can be copied. If the \p udata parameter below + * is \c NULL, then this parameter should be \c NULL as well. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h udata_copy_snip + * \n + * - The \ref H5FD_file_image_callbacks_t.udata_free "udata_free" + * callback contains a pointer to a function + * that, from the perspective of HDF5, frees a user data block. This + * function is necessary if a non-NULL udata parameter is supplied so + * that property lists containing image callbacks can be discarded + * without a memory leak. If the udata parameter below is \c NULL, + * this parameter should be \c NULL as well. + * + * - Signature in #H5FD_file_image_callbacks_t: + * \snippet H5FDpublic.h udata_free_snip + * + * - \p **udata**, the final field in the #H5FD_file_image_callbacks_t + * struct, provides a pointer to user-defined data. This pointer will + * be passed to the + * \ref H5FD_file_image_callbacks_t.image_malloc "image_malloc", + * \ref H5FD_file_image_callbacks_t.image_memcpy "image_memcpy", + * \ref H5FD_file_image_callbacks_t.image_realloc "image_realloc", and + * \ref H5FD_file_image_callbacks_t.image_free "image_free" callbacks. + * Define udata as \c NULL if no user-defined data is provided. + * + * \since 1.8.9 + * + */ H5_DLL herr_t H5Pset_file_image_callbacks(hid_t fapl_id, H5FD_file_image_callbacks_t *callbacks_ptr); +/** + * \ingroup FAPL + * + * \brief Sets the file locking property values + * + * \fapl_id + * \param[in] use_file_locking Toggle to specify file locking (or not) + * \param[in] ignore_when_disabled Toggle to ignore when disabled (or not) + * + * \return \herr_t + * + * \details H5Pset_file_locking() overrides the default file locking flag + * setting that was set when the library was configured. + * + * This setting can be overridden by the \c HDF5_USE_FILE_LOCKING + * environment variable. + * + * File locking is used when creating/opening a file to prevent + * problematic file accesses. + * + * \since 1.10.7 + * + */ H5_DLL herr_t H5Pset_file_locking(hid_t fapl_id, hbool_t use_file_locking, hbool_t ignore_when_disabled); +/** + * \ingroup FAPL + * + * \brief Sets garbage collecting references flag + * + * \fapl_id + * \param[in] gc_ref Flag setting reference garbage collection to on (1) or off (0) + * + * \return \herr_t + * + * \details H5Pset_gc_references() sets the flag for garbage collecting + * references for the file. + * + * Dataset region references and other reference types use space in an + * HDF5 file's global heap. If garbage collection is on and the user + * passes in an uninitialized value in a reference structure, the heap + * might get corrupted. When garbage collection is off, however, and + * the user re-uses a reference, the previous heap block will be + * orphaned and not returned to the free heap space. + * + * When garbage collection is on, the user must initialize the + * reference structures to 0 or risk heap corruption. + * + * The default value for garbage collecting references is off. + * + */ H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); /** * \ingroup FAPL @@ -3861,10 +4806,11 @@ H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); * <td>\p low=#H5F_LIBVER_V18<br /> * \p high=#H5F_LIBVER_V18</td> * <td> - * \li The library will create objects with the latest format versions - * available to library release 1.8.x. + * \li The library will create objects with the latest format + * versions available to library release 1.8.x. * \li API calls that create objects or features that are available - * to versions of the library greater than 1.8.x release will fail. + * to versions of the library greater than 1.8.x release will + * fail. * \li Earlier versions of the library may not be able to access * objects created with this setting.</td> * </tr> @@ -3872,14 +4818,15 @@ H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); * <td>\p low=#H5F_LIBVER_V18<br /> * \p high=#H5F_LIBVER_V110</td> * <td> - * \li The library will create objects with the latest format versions - * available to library release 1.8.x. + * \li The library will create objects with the latest format + * versions available to library release 1.8.x. * \li The library will allow objects to be created with the latest * format versions available to library release 1.10.x. - * Since 1.10.x is also #H5F_LIBVER_LATEST, there is no upper limit - * on the format versions to use. For example, if a newer format - * version is required to support a feature e.g. virtual dataset, - * this setting will allow the object to be created. + * Since 1.10.x is also #H5F_LIBVER_LATEST, there is no upper + * limit on the format versions to use. For example, if a + * newer format version is required to support a feature e.g. + * virtual dataset, this setting will allow the object to be + * created. * \li Earlier versions of the library may not be able to access * objects created with this setting.</td> * </tr> @@ -3888,39 +4835,356 @@ H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); * \p high=#H5F_LIBVER_V110 * </td> * <td> - * \li The library will create objects with the latest format versions - * available to library release 1.10.x. + * \li The library will create objects with the latest format + * versions available to library release 1.10.x. * \li The library will allow objects to be created with the latest * format versions available to library release 1.10.x. - * Since 1.10.x is also #H5F_LIBVER_LATEST, there is no upper limit - * on the format versions to use. For example, if a newer format - * version is required to support a feature e.g. virtual dataset, - * this setting will allow the object to be created. + * Since 1.10.x is also #H5F_LIBVER_LATEST, there is no upper + * limit on the format versions to use. For example, if a + * newer format version is required to support a feature e.g. + * virtual dataset, this setting will allow the object to be + * created. * \li This setting allows users to take advantage of the latest - * features and performance enhancements in the library. However, - * objects written with this setting may be accessible to a smaller - * range of library versions than would be the case if low is set - * to #H5F_LIBVER_EARLIEST. - * \li Earlier versions of the library may not be able to access objects created with this + * features and performance enhancements in the library. + * However, objects written with this setting may be + * accessible to a smaller range of library versions than + * would be the case if low is set to #H5F_LIBVER_EARLIEST. + * \li Earlier versions of the library may not be able to access + * objects created with this * setting. * </td> * </tr> * </table> * - * \version 1.10.2 #H5F_LIBVER_V18 added to the enumerated defines in #H5F_libver_t. + * \version 1.10.2 #H5F_LIBVER_V18 added to the enumerated defines in + * #H5F_libver_t. * * \since 1.8.0 * */ H5_DLL herr_t H5Pset_libver_bounds(hid_t plist_id, H5F_libver_t low, H5F_libver_t high); +/** + * \ingroup FAPL + * + * \brief Set the initial metadata cache configuration in the indicated File + * Access Property List to the supplied value + * + * \fapl_id{plist_id} + * \param[in] config_ptr Pointer to the instance of \p H5AC_cache_config_t + * containing the desired configuration + * \return \herr_t + * + * \details The fields of the #H5AC_cache_config_t structure are shown + * below: + * \snippet H5ACpublic.h H5AC_cache_config_t_snip + * \click4more + * + * \details H5Pset_mdc_config() attempts to set the initial metadata cache + * configuration to the supplied value. It will fail if an invalid + * configuration is detected. This configuration is used when the file + * is opened. + * + * See the overview of the metadata cache in the special topics section + * of the user manual for details on what is being configured. If you + * have not read and understood that documentation, you really should + * not be using this API call. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pset_mdc_config(hid_t plist_id, H5AC_cache_config_t *config_ptr); +/** + * \ingroup FAPL + * + * \brief Sets metadata cache logging options + * + * \fapl_id{plist_id} + * \param[in] is_enabled Whether logging is enabled + * \param[in] location Location of log in UTF-8/ASCII (file path/name) + * (On Windows, this must be ASCII) + * \param[in] start_on_access Whether the logging will begin as soon as the + * file is opened or created + * + * \return \herr_t + * + * \details The metadata cache is a central part of the HDF5 library through + * which all file metadata reads and writes take place. File metadata + * is normally invisible to the user and is used by the library for + * purposes such as locating and indexing data. File metadata should + * not be confused with user metadata, which consists of attributes + * created by users and attached to HDF5 objects such as datasets via + * H5A API calls. + * + * Due to the complexity of the cache, a trace/logging feature has + * been created that can be used by HDF5 developers for debugging and + * performance analysis. The functions that control this functionality + * will normally be of use to a very limited number of developers + * outside of The HDF Group. The functions have been documented to + * help users create logs that can be sent with bug reports. + * + * Control of the log functionality is straightforward. Logging is + * enabled via the H5Pset_mdc_log_options() function, + * which will modify the file access property list used to open or + * create a file. This function has a flag that determines whether + * logging begins at file open or starts in a paused state. Log + * messages can then be controlled via the H5Fstart_mdc_logging() + * and H5Fstop_mdc_logging() function. + * + * H5Pget_mdc_log_options() can be used to examine a file access + * property list, and H5Fget_mdc_logging_status() will return the + * current state of the logging flags. + * + * The log format is described in [<em>Metadata Cache Logging</em>] + * (https://portal.hdfgroup.org/display/HDF5/Fine-tuning+the+Metadata+Cache). + * + * \since 1.10.0 + * + */ 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 \ref VFL. + * + * The type of data specified in \p type may be one of the following: + * + * <table> + * <tr> + * <td>#H5FD_MEM_SUPER</td> <td>Super block data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_BTREE</td> <td>B-tree data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_DRAW</td> <td>Dataset raw data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_GHEAP</td> <td>Global heap data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_LHEAP</td> <td>Local Heap data</td> + * </tr> + * <tr> + * <td>#H5FD_MEM_OHDR</td> <td>Object header data</td> + * </tr> + * </table> + * + * 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 @@ -3943,14 +5207,242 @@ 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); +/** + * \ingroup FAPL + * + * \brief Sets metadata write mode to collective or independent (default) + * + * \fapl_id{plist_id} + * \param[out] is_collective Boolean value indicating whether metadata + * writes are collective (\Code{>0}) or independent (\Code{0}). + * \Emph{Default mode:} Independent (\Code{0}) + * \return \herr_t + * + * \details H5Pset_coll_metadata_write() tells the HDF5 library whether to + * perform metadata writes collectively (1) or independently (0). + * + * If collective access is selected, then on a flush of the metadata + * cache, all processes will divide the metadata cache entries to be + * flushed evenly among themselves and issue a single MPI-IO collective + * write operation. This is the preferred method when the size of the + * metadata created by the application is large. + * + * If independent access is selected, the library uses the default + * method for doing metadata I/O either from process zero or + * independently from each process. + * + * \sa_metadata_ops + * + * \since 1.10.0 + */ H5_DLL herr_t H5Pset_coll_metadata_write(hid_t plist_id, hbool_t is_collective); +/** + * \ingroup FAPL + * + * \brief Retrieves metadata write mode setting + * + * \fapl_id{plist_id} + * \param[out] is_collective Pointer to a boolean value indicating whether + * metadata writes are collective (\Code{>0}) or independent (\Code{0}). + * \Emph{Default mode:} Independent (\Code{0}) + * \return \herr_t + * + * \details H5Pget_coll_metadata_write() retrieves the collective metadata write + * setting from the file access property into \p is_collective. + * + * \sa_metadata_ops + * + * \since 1.10.0 + */ H5_DLL herr_t H5Pget_coll_metadata_write(hid_t plist_id, hbool_t *is_collective); + +/** + * \todo Add missing documentation + */ H5_DLL herr_t H5Pget_mpi_params(hid_t fapl_id, MPI_Comm *comm, MPI_Info *info); + +/** + * \todo Add missing documentation + */ H5_DLL herr_t H5Pset_mpi_params(hid_t fapl_id, MPI_Comm comm, MPI_Info info); #endif /* H5_HAVE_PARALLEL */ +/** + * \ingroup FAPL + * + * \brief Sets the metadata cache image option for a file access property list + * + * \fapl_id{plist_id} + * \param[out] config_ptr Pointer to metadata cache image configuration values + * \return \herr_t + * + * \details H5Pset_mdc_image_config() sets the metadata cache image option with + * configuration values specified by \p config_ptr for the file access + * property list specified in \p plist_id. + * + * #H5AC_cache_image_config_t is defined as follows: + * \snippet H5ACpublic.h H5AC_cache_image_config_t_snip + * \click4more + * + * \par Limitations: While it is an obvious error to request a cache image when + * opening the file read only, it is not in general possible to test for + * this error in the H5Pset_mdc_image_config() call. Rather than fail the + * subsequent file open, the library silently ignores the file image + * request in this case.\n It is also an error to request a cache image on + * a file that does not support superblock extension messages (i.e. a + * superblock version less than 2). As above, it is not always possible to + * detect this error in the H5Pset_mdc_image_config() call, and thus the + * request for a cache image will fail silently in this case as well.\n + * Creation of cache images is currently disabled in parallel -- as above, + * any request for a cache image in this context will fail silently.\n + * Files with cache images may be read in parallel applications, but note + * that the load of the cache image is a collective operation triggered by + * the first operation that accesses metadata after file open (or, if + * persistent free space managers are enabled, on the first allocation or + * deallocation of file space, or read of file space manager status, + * whichever comes first). Thus the parallel process may deadlock if any + * process does not participate in this access.\n + * In long sequences of file closes and opens, infrequently accessed + * metadata can accumulate in the cache image to the point where the cost + * of storing and restoring this metadata exceeds the benefit of retaining + * frequently used metadata in the cache image. When implemented, the + * #H5AC_cache_image_config_t::entry_ageout should address this problem. In + * the interim, not requesting a cache image every n file close/open cycles + * may be an acceptable work around. The choice of \c n will be driven by + * application behavior, but \Code{n = 10} seems a good starting point. + * + * \since 1.10.1 + */ H5_DLL herr_t H5Pset_mdc_image_config(hid_t plist_id, H5AC_cache_image_config_t *config_ptr); +/** + * \ingroup FAPL + * + * \brief Sets the maximum size for the page buffer and the minimum percentage + * for metadata and raw data pages + * + * \fapl_id{plist_id} + * \param[in] buf_size Maximum size, in bytes, of the page buffer + * \param[in] min_meta_per Minimum metadata percentage to keep in the page buffer + * before allowing pages containing metadata to be evicted (Default is 0) + * \param[in] min_raw_per Minimum raw data percentage to keep in the page buffer + * before allowing pages containing raw data to be evicted (Default is 0) + * \return \herr_t + * + * \details H5Pset_page_buffer_size() sets buf_size, the maximum size in bytes + * of the page buffer. The default value is zero, meaning that page + * buffering is disabled. When a non-zero page buffer size is set, the + * library will enable page buffering if that size is larger or equal + * than a single page size if a paged file space strategy is enabled + * using the functions H5Pset_file_space_strategy() and + * H5Pset_file_space_page_size(). + * + * The page buffer layer captures all I/O requests before they are + * issued to the VFD and "caches" them in fixed sized pages. Once the + * total number of pages exceeds the page buffer size, the library + * evicts pages from the page buffer by writing them to the VFD. At + * file close, the page buffer is flushed writing all the pages to the + * file. + * + * If a non-zero page buffer size is set, and the file space strategy + * is not set to paged or the page size for the file space strategy is + * larger than the page buffer size, the subsequent call to H5Fcreate() + * or H5Fopen() using the \p plist_id will fail. + * + * The function also allows setting the minimum percentage of pages for + * metadata and raw data to prevent a certain type of data to evict hot + * data of the other type. + * + * \since 1.10.1 + * + */ H5_DLL herr_t H5Pset_page_buffer_size(hid_t plist_id, size_t buf_size, unsigned min_meta_per, unsigned min_raw_per); @@ -4288,7 +5780,7 @@ H5_DLL H5D_layout_t H5Pget_layout(hid_t plist_id); * virtual dataset that has the creation property list specified * by \p dcpl_id. * - * \virtual + * \see_virtual * * \since 1.10.0 * @@ -4331,7 +5823,7 @@ H5_DLL herr_t H5Pget_virtual_count(hid_t dcpl_id, size_t *count /*out*/); * assigned to \p size for a second H5Pget_virtual_dsetname() * call, which will retrieve the actual dataset name. * - * \virtual + * \see_virtual * * \since 1.10.0 * @@ -4375,7 +5867,7 @@ H5_DLL ssize_t H5Pget_virtual_dsetname(hid_t dcpl_id, size_t index, char *name / * \p size for a second H5Pget_virtual_filename() call, which * will retrieve the actual filename. * - * \virtual + * \see_virtual * * \since 1.10.0 * @@ -4400,7 +5892,7 @@ H5_DLL ssize_t H5Pget_virtual_filename(hid_t dcpl_id, size_t index, char *name / * index, \p index, and returns a dataspace identifier for the * selection within the source dataset used in the mapping. * - * \virtual + * \see_virtual * * \since 1.10.0 * @@ -4425,7 +5917,7 @@ H5_DLL hid_t H5Pget_virtual_srcspace(hid_t dcpl_id, size_t index); * index, \p index, and returns a dataspace identifier for the * selection within the virtual dataset used in the mapping. * - * \virtual + * \see_virtual * * \since 1.10.0 * @@ -5159,6 +6651,133 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, * */ H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels_per_block); + +/** + * \ingroup DCPL + * + * \brief Sets the mapping between virtual and source datasets + * + * \dcpl_id + * \param[in] vspace_id The dataspace identifier with the selection within the + * virtual dataset applied, possibly an unlimited selection + * \param[in] src_file_name The name of the HDF5 file where the source dataset is + * located or a \Code{"."} (period) for a source dataset in the same + * file. The file might not exist yet. The name can be specified using + * a C-style \c printf statement as described below. + * \param[in] src_dset_name The path to the HDF5 dataset in the file specified by + * \p src_file_name. The dataset might not exist yet. The dataset name + * can be specified using a C-style \c printf statement as described below. + * \param[in] src_space_id The source dataset’s dataspace identifier with a + * selection applied, possibly an unlimited selection + * \return \herr_t + * + * \details H5Pset_virtual() maps elements of the virtual dataset (VDS) + * described by the virtual dataspace identifier \p vspace_id to the + * elements of the source dataset described by the source dataset + * dataspace identifier \p src_space_id. The source dataset is + * identified by the name of the file where it is located, + * \p src_file_name, and the name of the dataset, \p src_dset_name. + * + * \par C-style \c printf Formatting Statements: + * C-style \c printf formatting allows a pattern to be specified in the name + * of a source file or dataset. Strings for the file and dataset names are + * treated as literals except for the following substitutions: + * <table> + * <tr> + * <td>\Code{"%%"}</td> + * <td>Replaced with a single \Code{"%"} (percent) character.</td> + * </tr> + * <tr> + * <td><code>"%<d>b"</code></td> + * <td>Where <code>"<d>"</code> is the virtual dataset dimension axis (0-based) + * and \Code{"b"} indicates that the block count of the selection in that + * dimension should be used. The full expression (for example, \Code{"%0b"}) + * is replaced with a single numeric value when the mapping is evaluated at + * VDS access time. Example code for many source and virtual dataset mappings + * is available in the "Examples of Source to Virtual Dataset Mapping" + * chapter in the + * <a href="https://portal.hdfgroup.org/display/HDF5/RFC+HDF5+Virtual+Dataset"> + * RFC: HDF5 Virtual Dataset</a>. + * </td> + * </tr> + * </table> + * If the printf form is used for the source file or dataset names, the + * selection in the source dataset’s dataspace must be fixed-size. + * + * \par Source File Resolutions: + * When a source dataset residing in a different file is accessed, the + * library will search for the source file \p src_file_name as described + * below: + * \li If \p src_file_name is a \Code{"."} (period) then it refers to the + * file containing the virtual dataset. + * \li If \p src_file_name is a relative pathname, the following steps are + * performed: + * - The library will get the prefix(es) set in the environment + * variable \c HDF5_VDS_PREFIX and will try to prepend each prefix + * to \p src_file_name to form a new \p src_file_name. If the new + * \p src_file_name does not exist or if \c HDF5_VDS_PREFIX is not + * set, the library will get the prefix set via H5Pset_virtual_prefix() + * and prepend it to \p src_file_name to form a new \p src_file_name. + * If the new \p src_file_name does not exist or no prefix is being + * set by H5Pset_virtual_prefix() then the path of the file containing + * the virtual dataset is obtained. This path can be the absolute path + * or the current working directory plus the relative path of that + * file when it is created/opened. The library will prepend this path + * to \p src_file_name to form a new \p src_file_name. + * - If the new \p src_file_name does not exist, then the library will + * look for \p src_file_name and will return failure/success accordingly. + * \li If \p src_file_name is an absolute pathname, the library will first + * try to find \p src_file_name. If \p src_file_name does not exist, + * \p src_file_name is stripped of directory paths to form a new + * \p src_file_name. The search for the new \p src_file_name then follows + * the same steps as described above for a relative pathname. See + * examples below illustrating how \p src_file_name is stripped to form + * a new \p src_file_name. + * \par + * Note that \p src_file_name is considered to be an absolute pathname when + * the following condition is true: + * \li For Unix, the first character of \p src_file_name is a slash + * (\Code{/}).\n For example, consider a \p src_file_name of + * \Code{/tmp/A.h5}. If that source file does not exist, the new + * \p src_file_name after stripping will be \Code{A.h5}. + * \li For Windows, there are 6 cases: + * 1. \p src_file_name is an absolute drive with absolute pathname.\n + * For example, consider a \p src_file_name of \Code{/tmp/A.h5}. + * If that source file does not exist, the new \p src_file_name + * after stripping will be \Code{A.h5}. + * 2. \p src_file_name is an absolute pathname without specifying + * drive name.\n For example, consider a \p src_file_name of + * \Code{/tmp/A.h5}. If that source file does not exist, the new + * \p src_file_name after stripping will be \Code{A.h5}. + * 3. \p src_file_name is an absolute drive with relative pathname.\n + * For example, consider a \p src_file_name of \Code{/tmp/A.h5}. + * If that source file does not exist, the new \p src_file_name + * after stripping will be \Code{tmp/A.h5}. + * 4. \p src_file_name is in UNC (Uniform Naming Convention) format + * with server name, share name, and pathname.\n + * For example, consider a \p src_file_name of \Code{/tmp/A.h5}. + * If that source file does not exist, the new \p src_file_name + * after stripping will be \Code{A.h5}. + * 5. \p src_file_name is in Long UNC (Uniform Naming Convention) + * format with server name, share name, and pathname.\n + * For example, consider a \p src_file_name of \Code{/tmp/A.h5}. + * If that source file does not exist, the new \p src_file_name + * after stripping will be \Code{A.h5}. + * 6. \p src_file_name is in Long UNC (Uniform Naming Convention) + * format with an absolute drive and an absolute pathname.\n + * For example, consider a \p src_file_name of \Code{/tmp/A.h5}. + * If that source file does not exist, the new \p src_file_name + * after stripping will be \Code{A.h5} + * + * \see <a href="https://portal.hdfgroup.org/display/HDF5/Virtual+Dataset++-+VDS"> + * Virtual Dataset Overview</a> + * + * \see_virtual + * + * \version 1.10.2 A change was made to the method of searching for VDS source files. + * \since 1.10.0 + * + */ H5_DLL herr_t H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_file_name, const char *src_dset_name, hid_t src_space_id); @@ -5191,8 +6810,6 @@ H5_DLL herr_t H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_fil * \p udata is the user-defined input data for the callback * function. * - * \todo Example Usage was removed and needs to be re-added - * * \since 1.10.0 * */ @@ -5298,7 +6915,7 @@ H5_DLL ssize_t H5Pget_efile_prefix(hid_t dapl_id, char *prefix /*out*/, size_t s * NULL will return the size of the prefix without the NULL * terminator. * - * \virtual + * \see_virtual * * \since 1.10.2 * @@ -5348,7 +6965,7 @@ H5_DLL herr_t H5Pget_virtual_printf_gap(hid_t dapl_id, hsize_t *gap_size); * list, \p dapl_id, and retrieves the flag, \p view, set by the * H5Pset_virtual_view() call. * - * \virtual + * \see_virtual * * \since 1.10.0 * @@ -5389,7 +7006,7 @@ H5_DLL herr_t H5Pget_virtual_view(hid_t dapl_id, H5D_vds_view_t *view); * \p boundary. It is a 1-dimensional array with \p ndims * elements, which should be the same as the rank of the * dataset’s dataspace. While appending to a dataset along a - * particular dimension index via H5DOappend(), the library + * particular dimension index via H5Dappend(), the library * determines a boundary is reached when the resulting dimension * size is divisible by \p boundary[index]. A zero value for * \p boundary[index] indicates no boundary is set for that @@ -5415,8 +7032,7 @@ H5_DLL herr_t H5Pget_virtual_view(hid_t dapl_id, H5D_vds_view_t *view); * * The callback function \p func must conform to the following * prototype: - * \Code{typedef herr_t (#H5D_append_cb_t)(hid_t dataset_id, - * hsize_t *cur_dims, void *user_data)} + * \snippet H5Dpublic.h H5D_append_cb_t_snip * * The parameters of the callback function, per the above * prototype, are defined as follows: @@ -5426,10 +7042,6 @@ H5_DLL herr_t H5Pget_virtual_view(hid_t dapl_id, H5D_vds_view_t *view); * a boundary is hit. * \li \p user_data is the user-defined input data. * - * \todo Example Usage was removed and should be added back. - * \todo Adding snippet for H5D_append_cb_t_snip did not work. - * \todo H5DOappend() not found - * * \since 1.10.0 * */ @@ -5643,7 +7255,7 @@ H5_DLL herr_t H5Pset_efile_prefix(hid_t dapl_id, const char *prefix); * buffer should not be freed until the property list has been * closed. * - * \virtual + * \see_virtual * * \since 1.10.2 * @@ -5685,7 +7297,7 @@ H5_DLL herr_t H5Pset_virtual_prefix(hid_t dapl_id, const char *prefix); * d-2 and d-3 will be filled according to the virtual * dataset’s fill value setting. * - * \virtual + * \see_virtual * * \since 1.10.0 * @@ -5723,7 +7335,7 @@ H5_DLL herr_t H5Pset_virtual_printf_gap(hid_t dapl_id, hsize_t gap_size); * Missing mapped data is filled with the fill value set in the * VDS creation property list. * - * \virtual + * \see_virtual * * \since 1.10.0 * @@ -5731,8 +7343,48 @@ H5_DLL herr_t H5Pset_virtual_printf_gap(hid_t dapl_id, hsize_t gap_size); H5_DLL herr_t H5Pset_virtual_view(hid_t dapl_id, H5D_vds_view_t view); /* Dataset xfer property list (DXPL) routines */ +/** + * + * \ingroup DXPL + * + * \brief Gets B-tree split ratios for a dataset transfer property list + * + * \dxpl_id{plist_id} + * \param[out] left The B-tree split ratio for left-most nodes + * \param[out] middle The B-tree split ratio for right-most nodes and lone nodes + * \param[out] right The B-tree split ratio for all other nodes + * \return \herr_t + * + * \details H5Pget_btree_ratios() returns the B-tree split ratios for a dataset + * transfer property list. + * + * The B-tree split ratios are returned through the non-NULL arguments + * \p left, \p middle, and \p right, as set by the H5Pset_btree_ratios() + * function. + * + */ H5_DLL herr_t H5Pget_btree_ratios(hid_t plist_id, double *left /*out*/, double *middle /*out*/, double *right /*out*/); +/** + * + * \ingroup DXPL + * + * \brief Reads buffer settings + * + * \param[in] plist_id Identifier for the dataset transfer property list + * \param[out] tconv Address of the pointer to application-allocated type + * conversion buffer + * \param[out] bkg Address of the pointer to application-allocated + * background buffer + * + * \return Returns buffer size, in bytes, if successful; otherwise 0 on failure. + * + * \details H5Pget_buffer() reads values previously set with H5Pset_buffer(). + * + * \version 1.6.0 The return type changed from \p hsize_t to \p size_t. + * \version 1.4.0 The return type changed to \p hsize_t. + * + */ H5_DLL size_t H5Pget_buffer(hid_t plist_id, void **tconv /*out*/, void **bkg /*out*/); /** * @@ -5740,54 +7392,237 @@ H5_DLL size_t H5Pget_buffer(hid_t plist_id, void **tconv /*out*/, void **bkg /*o * * \brief Retrieves a data transform expression * - * \param[in] plist_id Identifier of the property list or class - * \param[out] expression Pointer to memory where the transform expression - * will be copied - * \param[in] size Number of bytes of the transform expression to copy to + * \param[in] plist_id Identifier of the property list or class + * \param[out] expression Pointer to memory where the transform expression will + * be copied + * \param[in] size Number of bytes of the transform expression to copy + * to * - * \return Returns the size of the transform expression if successful; - * otherwise returns a negative value. + * \return Success: the size of the transform expression. Failure: a negative + * value. * - * \details H5Pget_data_transform() retrieves the data transform - * expression previously set in the dataset transfer property - * list \p plist_id by H5Pset_data_transform(). + * \details H5Pget_data_transform() retrieves the data transform expression + * previously set in the dataset transfer property list \p plist_id + * by H5Pset_data_transform(). * - * H5Pget_data_transform() can be used to both retrieve the - * transform expression and to query its size. + * H5Pget_data_transform() can be used to both retrieve the transform + * expression and query its size. * * If \p expression is non-NULL, up to \p size bytes of the data - * transform expression are written to the buffer. If - * \p expression is NULL, \p size is ignored and the function - * does not write anything to the buffer. The function always - * returns the size of the data transform expression. + * transform expression are written to the buffer. If \p expression + * is NULL, \p size is ignored, and the function does not write + * anything to the buffer. The function always returns the size of + * the data transform expression. * - * If 0 is returned for the size of the expression, no data - * transform expression exists for the property list. + * If 0 is returned for the size of the expression, no data transform + * expression exists for the property list. * * If an error occurs, the buffer pointed to by \p expression is - * unchanged and the function returns a negative value. + * unchanged, and the function returns a negative value. + * + * \par Example + * An example snippet from examples/h5_dtransform.c: + * \snippet h5_dtransform.c H5Pget_data_transform_snip * * \since 1.8.0 * */ -H5_DLL ssize_t H5Pget_data_transform(hid_t plist_id, char *expression /*out*/, size_t size); +H5_DLL ssize_t H5Pget_data_transform(hid_t plist_id, char *expression /*out*/, size_t size); +/** + * + * \ingroup DXPL + * + * \brief Determines whether error-detection is enabled for dataset reads + * + * \param[in] plist_id Dataset transfer property list identifier + * + * \return Returns \p H5Z_ENABLE_EDC or \p H5Z_DISABLE_EDC if successful; + * otherwise returns a negative value. + * + * \details H5Pget_edc_check() queries the dataset transfer property + * list \p plist to determine whether error detection is enabled for + * data read operations. + * + * \since 1.6.0 + * + */ H5_DLL H5Z_EDC_t H5Pget_edc_check(hid_t plist_id); -H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size /*out*/); -H5_DLL int H5Pget_preserve(hid_t plist_id); -H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void **operate_data); -H5_DLL herr_t H5Pget_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t *alloc_func, void **alloc_info, - H5MM_free_t *free_func, void **free_info); -H5_DLL herr_t H5Pset_btree_ratios(hid_t plist_id, double left, double middle, double right); -H5_DLL herr_t H5Pset_buffer(hid_t plist_id, size_t size, void *tconv, void *bkg); +/** + * + * \ingroup DXPL + * + * \brief Retrieves number of I/O vectors to be read/written in hyperslab I/O + * + * \param[in] fapl_id Dataset transfer property list identifier + * \param[out] size Number of I/O vectors to accumulate in memory for I/O operations + * + * \return \herr_t + * + * \details H5Pget_hyper_vector_size() retrieves the number of I/O vectors to be accumulated in + * memory before being issued to the lower levels of the HDF5 library for reading or + * writing the actual data. + * + * The number of I/O vectors set in the dataset transfer property list \p fapl_id is + * returned in \p size. Unless the default value is in use, \p size was + * previously set with a call to H5Pset_hyper_vector_size(). + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size /*out*/); +/** + * + * \ingroup DXPL + * + * \brief Checks status of the dataset transfer property list (\b DEPRECATED) + * + * \deprecated{H5Pget_preserve() is deprecated as it is no longer useful; + * compound datatype field preservation is now core functionality + * in the HDF5 library.} + * + * \param[in] plist_id Identifier for the dataset transfer property list + * + * \return Returns 1 or 0 if successful; otherwise returns a negative value. + * + * \details H5Pget_preserve() checks the status of the dataset transfer + * property list. + * + * \version 1.6.0 The flag parameter was changed from INTEGER to LOGICAL to + * better match the C API. (Fortran 90) + * + */ +H5_DLL int H5Pget_preserve(hid_t plist_id); +/** + * + * \ingroup DXPL + * + * \brief Gets user-defined datatype conversion callback function + * + * \param[in] dxpl_id Dataset transfer property list identifier + * \param[out] op User-defined type conversion callback function + * \param[out] operate_data User-defined input data for the callback function + * + * \return \herr_t + * + * \details H5Pget_type_conv_cb() gets the user-defined datatype conversion + * callback function \p op in the dataset transfer property list + * \p dxpl_id. + * + * The parameter \p operate_data is a pointer to user-defined input + * data for the callback function. + * + * The callback function \p op defines the actions an application is + * to take when there is an exception during datatype conversion. + * + * Please refer to the function H5Pset_type_conv_cb() for more details. + * + */ +H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void **operate_data); +/** + * + * \ingroup DXPL + * + * \brief Gets the memory manager for variable-length datatype allocation in H5Dread() and H5Dvlen_reclaim() + * + * \param[in] plist_id Identifier for the dataset transfer property list + * \param[out] alloc_func User's allocate routine, or NULL for system malloc + * \param[out] alloc_info Extra parameter for user’s allocation routine. + * Contents are ignored if preceding + * parameter is NULL \param[out] free_func User's free routine, or NULL for + * system free \param[out] free_info + * Extra parameter for user’s free routine. Contents are ignored if preceding + * parameter is NULL + * + * \return \herr_t + * + * \details H5Pget_vlen_mem_manager() is the companion function to + * H5Pset_vlen_mem_manager(), returning the parameters set by + * that function. + * + */ +H5_DLL herr_t H5Pget_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t *alloc_func, void **alloc_info, + H5MM_free_t *free_func, void **free_info); +/** + * + * \ingroup DXPL + * + * \brief Sets B-tree split ratios for a dataset transfer property list + * + * \param[in] plist_id The dataset transfer property list identifier + * \param[in] left The B-tree split ratio for left-most nodes + * \param[in] middle The B-tree split ratio for all other nodes + * \param[in] right The B-tree split ratio for right-most nodes and lone + * nodes + * + * \return \herr_t + * + * \details H5Pset_btree_ratios() sets the B-tree split ratios for a dataset + * transfer property list. The split ratios determine what percent of + * children go in the first node when a node splits. + * + * The ratio \p left is used when the splitting node is the left-most + * node at its level in the tree; + * the ratio \p right is used when the splitting node is the right-most + * node at its level; and + * the ratio \p middle is used for all other cases. + * + * A node that is the only node at its level in the tree uses the + * ratio \p right when it splits. + * + * All ratios are real numbers between 0 and 1, inclusive. + * + */ +H5_DLL herr_t H5Pset_btree_ratios(hid_t plist_id, double left, double middle, double right); + +/** + * + * \ingroup DXPL + * + * \brief Sets type conversion and background buffers + * + * \dxpl_id{plist_id} + * \param[in] size Size, in bytes, of the type conversion and background buffers + * \param[in] tconv Pointer to application-allocated type conversion buffer + * \param[in] bkg Pointer to application-allocated background buffer + * \return \herr_t + * + * \details Given a dataset transfer property list, H5Pset_buffer() sets the + * maximum size for the type conversion buffer and background buffer + * and optionally supplies pointers to application-allocated + * buffers. If the buffer size is smaller than the entire amount of + * data being transferred between the application and the file, and a + * type conversion buffer or background buffer is required, then strip + * mining will be used. + * + * Note that there are minimum size requirements for the buffer. Strip + * mining can only break the data up along the first dimension, so the + * buffer must be large enough to accommodate a complete slice that + * encompasses all of the remaining dimensions. For example, when strip + * mining a \Code{100x200x300} hyperslab of a simple data space, the + * buffer must be large enough to hold \Code{1x200x300} data + * elements. When strip mining a \Code{100x200x300x150} hyperslab of a + * simple data space, the buffer must be large enough to hold + * \Code{1x200x300x150} data elements. + * + * If \p tconv and/or \p bkg are null pointers, then buffers will be + * allocated and freed during the data transfer. + * + * The default value for the maximum buffer is 1 MiB. + * + * \version 1.6.0 The \p size parameter has changed from type hsize_t to \c size_t. + * \version 1.4.0 The \p size parameter has changed to type hsize_t. + * + */ +H5_DLL herr_t H5Pset_buffer(hid_t plist_id, size_t size, void *tconv, void *bkg); + /** * \ingroup DXPL * * \brief Sets a data transform expression * - * \param[in] plist_id Identifier of the property list or class + * \dxpl_id{plist_id} * \param[in] expression Pointer to the null-terminated data transform * expression - * * \return \herr_t * * \details H5Pset_data_transform() sets the data transform to be used for @@ -5795,11 +7630,11 @@ H5_DLL herr_t H5Pset_buffer(hid_t plist_id, size_t size, void *tconv, void *b * transfer property list \p plist_id. * * The \p expression parameter is a string containing an algebraic - * expression, such as (5/9.0)*(x-32) or x*(x-5). When a dataset - * is read or written with this property list, the transform - * expression is applied with the x being replaced by the values - * in the dataset. When reading data, the values in the file are - * not changed and the transformed data is returned to the user. + * expression, such as \Code{(5/9.0)*(x-32)} or \Code{x*(x-5)}. When a + * dataset is read or written with this property list, the transform + * expression is applied with the \c x being replaced by the values in + * the dataset. When reading data, the values in the file are not + * changed and the transformed data is returned to the user. * * Data transforms can only be applied to integer or * floating-point datasets. Order of operations is obeyed and @@ -5813,17 +7648,354 @@ H5_DLL herr_t H5Pset_buffer(hid_t plist_id, size_t size, void *tconv, void *b * */ H5_DLL herr_t H5Pset_data_transform(hid_t plist_id, const char *expression); + +/** + * \ingroup DXPL + * + * \brief Sets the dataset transfer property list to enable or disable error + * detection when reading data + * + * \dxpl_id{plist_id} + * \param[in] check Specifies whether error checking is enabled or disabled + * for dataset read operations + * \return \herr_t + * + * \details H5Pset_edc_check() sets the dataset transfer property list \p plist + * to enable or disable error detection when reading data. + * + * Whether error detection is enabled or disabled is specified in the + * \p check parameter. Valid values are #H5Z_ENABLE_EDC (default) and + * #H5Z_DISABLE_EDC. + * + * \note The initial error detection implementation, Fletcher32 checksum, + * supports error detection for chunked datasets only. + * + * \attention The Fletcher32 EDC checksum filter, set with H5Pset_fletcher32(), + * was added in HDF5 Release 1.6.0. In the original implementation, + * however, the checksum value was calculated incorrectly on + * little-endian systems. The error was fixed in HDF5 Release 1.6.3.\n + * As a result of this fix, an HDF5 library of Release 1.6.0 through + * Release 1.6.2 cannot read a dataset created or written with + * Release 1.6.3 or later if the dataset was created with the + * checksum filter and the filter is enabled in the reading + * library. (Libraries of Release 1.6.3 and later understand the + * earlier error and compensate appropriately.)\n + * \Bold{Work-around:} An HDF5 library of Release 1.6.2 or earlier + * will be able to read a dataset created or written with the + * checksum filter by an HDF5 library of Release 1.6.3 or later if + * the checksum filter is disabled for the read operation. This can + * be accomplished via an H5Pset_edc_check() call with the value + * #H5Z_DISABLE_EDC in the second parameter. This has the obvious + * drawback that the application will be unable to verify the + * checksum, but the data does remain accessible. + * + * \version 1.6.3 Error in checksum calculation on little-endian systems + * corrected in this release. + * \since 1.6.0 + * + */ H5_DLL herr_t H5Pset_edc_check(hid_t plist_id, H5Z_EDC_t check); + +/** + * \ingroup DXPL + * + * \brief Sets user-defined filter callback function + * + * \dxpl_id{plist_id} + * \param[in] func User-defined filter callback function + * \param[in] op_data User-defined input data for the callback function + * \return \herr_t + * + * \details H5Pset_filter_callback() sets the user-defined filter callback + * function \p func in the dataset transfer property list \p plist_id. + * + * The parameter \p op_data is a pointer to user-defined input data for + * the callback function and will be passed through to the callback + * function. + * + * The callback function \p func defines the actions an application is + * to take when a filter fails. The function prototype is as follows: + * \snippet H5Zpublic.h H5Z_filter_func_t_snip + * where \c filter indicates which filter has failed, \c buf and \c buf_size + * are used to pass in the failed data, and op_data is the required + * input data for this callback function. + * + * Valid callback function return values are #H5Z_CB_FAIL and #H5Z_CB_CONT. + * + * \since 1.6.0 + * + */ H5_DLL herr_t H5Pset_filter_callback(hid_t plist_id, H5Z_filter_func_t func, void *op_data); -H5_DLL herr_t H5Pset_hyper_vector_size(hid_t fapl_id, size_t size); + +/** + * \ingroup DXPL + * + * \brief Sets number of I/O vectors to be read/written in hyperslab I/O + * + * \dxpl_id{plist_id} + * \param[in] size Number of I/O vectors to accumulate in memory for I/O + * operations\n + * Must be greater than 1 (one)\n + * Default value: 1024 + * \return \herr_t + * + * \details H5Pset_hyper_vector_size() sets the number of I/O vectors to be + * accumulated in memory before being issued to the lower levels of + * the HDF5 library for reading or writing the actual data. + * + * The I/O vectors are hyperslab offset and length pairs and are + * generated during hyperslab I/O. + * + * The number of I/O vectors is passed in \p size to be set in the + * dataset transfer property list \p plist_id. \p size must be + * greater than 1 (one). + * + * H5Pset_hyper_vector_size() is an I/O optimization function; + * increasing vector_size should provide better performance, but the + * library will use more memory during hyperslab I/O. The default value + * of \p size is 1024. + * + * \since 1.6.0 + * + */ +H5_DLL herr_t H5Pset_hyper_vector_size(hid_t plist_id, size_t size); + +/** + * \ingroup DXPL + * + * \brief Sets the dataset transfer property list \p status + * + * \dxpl_id{plist_id} + * \param[in] status Status toggle of the dataset transfer property list + * \return \herr_t + * + * \deprecated This function is deprecated as it no longer has any effect; + * compound datatype field preservation is now core functionality in + * the HDF5 library. + * + * \details H5Pset_preserve() sets the dataset transfer property list status to + * \c 1 or \c 0. + * + * When reading or writing compound datatypes and the destination is + * partially initialized and the read/write is intended to initialize + * the other members, one must set this property to \c 1. Otherwise the + * I/O pipeline treats the destination datapoints as completely + * uninitialized. + * + * \todo Add missing version information: introduction, deprecation, etc. + * Why is the declaration not in the deprecated section? + * + */ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); + +/** + * \ingroup DXPL + * + * \brief Sets user-defined datatype conversion callback function + * + * \dxpl_id + * \param[in] op User-defined type conversion callback function + * \param[in] operate_data User-defined input data for the callback function + * \return \herr_t + * + * \details H5Pset_type_conv_cb() sets the user-defined datatype conversion + * callback function \p op in the dataset transfer property list \p + * dxpl_id + * + * The parameter operate_data is a pointer to user-defined input data + * for the callback function and will be passed through to the callback + * function. + * + * The callback function \p op defines the actions an application is to + * take when there is an exception during datatype conversion. The + * function prototype is as follows: + * \snippet H5Tpublic.h H5T_conv_except_func_t_snip + * + * \todo Add version information. + * + */ H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void *operate_data); + +/** + * \ingroup DXPL + * + * \brief Sets the memory manager for variable-length datatype allocation in + * H5Dread() and H5Dvlen_reclaim() + * + * \dxpl_id{plist_id} + * \param[in] alloc_func User's allocate routine, or \c NULL for system \c malloc + * \param[in] alloc_info Extra parameter for user's allocation routine. + * Contents are ignored if preceding parameter is \c NULL. + * \param[in] free_func User's free routine, or \c NULL for system \c free + * \param[in] free_info Extra parameter for user's free routine. Contents are + * ignored if preceding parameter is \c NULL + * \return \herr_t + * + * \details H5Pset_vlen_mem_manager() sets the memory manager for + * variable-length datatype allocation in H5Dread() and free in + * H5Dvlen_reclaim(). + * + * The \p alloc_func and \p free_func parameters identify the memory + * management routines to be used. If the user has defined custom + * memory management routines, \p alloc_func and/or free_func should be + * set to make those routine calls (i.e., the name of the routine is + * used as the value of the parameter); if the user prefers to use the + * system's \c malloc and/or \c free, the \p alloc_func and \p + * free_func parameters, respectively, should be set to \c NULL + * + * The prototypes for these user-defined functions are as follows: + * \snippet H5MMpublic.h H5MM_allocate_t_snip + * + * \snippet H5MMpublic.h H5MM_free_t_snip + * + * The \p alloc_info and \p free_info parameters can be used to pass + * along any required information to the user's memory management + * routines. + * + * In summary, if the user has defined custom memory management + * routines, the name(s) of the routines are passed in the \p + * alloc_func and \p free_func parameters and the custom routines' + * parameters are passed in the \p alloc_info and \p free_info + * parameters. If the user wishes to use the system \c malloc and \c + * free functions, the \p alloc_func and/or \p free_func parameters are + * set to \c NULL and the \p alloc_info and \p free_info parameters are + * ignored. + * + * \todo Add version information. + */ H5_DLL herr_t H5Pset_vlen_mem_manager(hid_t plist_id, H5MM_allocate_t alloc_func, void *alloc_info, H5MM_free_t free_func, void *free_info); + #ifdef H5_HAVE_PARALLEL +/** + * \ingroup DXPL + * + * \brief Retrieves the type of chunk optimization that HDF5 actually performed + * on the last parallel I/O call (not necessarily the type requested) + * + * \dxpl_id{plist_id} + * \param[out] actual_chunk_opt_mode The type of chunk optimization performed by HDF5 + * \return \herr_t + * + * \par Motivation: + * A user can request collective I/O via a data transfer property list + * (DXPL) that has been suitably modified with H5Pset_dxpl_mpio(). + * However, HDF5 will sometimes ignore this request and perform independent + * I/O instead. This property allows the user to see what kind of I/O HDF5 + * actually performed. Used in conjunction with H5Pget_mpio_actual_io_mode(), + * this property allows the user to determine exactly what HDF5 did when + * attempting collective I/O. + * + * \details H5Pget_mpio_actual_chunk_opt_mode() retrieves the type of chunk + * optimization performed when collective I/O was requested. This + * property is set before I/O takes place, and will be set even if I/O + * fails. + * + * Valid values returned in \p actual_chunk_opt_mode: + * \snippet this H5D_mpio_actual_chunk_opt_mode_t_snip + * \click4more + * + * \since 1.8.8 + * + */ H5_DLL herr_t H5Pget_mpio_actual_chunk_opt_mode(hid_t plist_id, H5D_mpio_actual_chunk_opt_mode_t *actual_chunk_opt_mode); +/** + * \ingroup DXPL + * + * \brief Retrieves the type of I/O that HDF5 actually performed on the last + * parallel I/O call (not necessarily the type requested) + * + * \dxpl_id{plist_id} + * \param[out] actual_io_mode The type of I/O performed by this process + * \return \herr_t + * + * \par Motivation: + * A user can request collective I/O via a data transfer property list + * (DXPL) that has been suitably modified with H5Pset_dxpl_mpio(). + * However, HDF5 will sometimes ignore this request and perform independent + * I/O instead. This property allows the user to see what kind of I/O HDF5 + * actually performed. Used in conjunction with H5Pget_mpio_actual_chunk_opt_mode(), + * this property allows the user to determine exactly HDF5 did when + * attempting collective I/O. + * + * \details H5Pget_mpio_actual_io_mode() retrieves the type of I/O performed on + * the selection of the current process. This property is set after all + * I/O is completed; if I/O fails, it will not be set. + * + * Valid values returned in \p actual_io_mode: + * \snippet this H5D_mpio_actual_io_mode_t_snip + * \click4more + * + * \attention All processes do not need to have the same value. For example, if + * I/O is being performed using the multi chunk optimization scheme, + * one process's selection may include only chunks accessed + * collectively, while another may include chunks accessed + * independently. In this case, the first process will report + * #H5D_MPIO_CHUNK_COLLECTIVE while the second will report + * #H5D_MPIO_CHUNK_INDEPENDENT. + * + * \see H5Pget_mpio_no_collective_cause(), H5Pget_mpio_actual_chunk_opt_mode() + * + * \since 1.8.8 + * + */ H5_DLL herr_t H5Pget_mpio_actual_io_mode(hid_t plist_id, H5D_mpio_actual_io_mode_t *actual_io_mode); +/** + * \ingroup DXPL + * + * \brief Retrieves local and global causes that broke collective I/O on the last + * parallel I/O call + * + * \dxpl_id{plist_id} + * \param[out] local_no_collective_cause An enumerated set value indicating the + * causes that prevented collective I/O in the local process + * \param[out] global_no_collective_cause An enumerated set value indicating + * the causes across all processes that prevented collective I/O + * \return \herr_t + * + * \par Motivation: + * A user can request collective I/O via a data transfer property list (DXPL) + * that has been suitably modified with H5P_SET_DXPL_MPIO. However, there are + * conditions that can cause HDF5 to forgo collective I/O and perform + * independent I/O. Such causes can be different across the processes of a + * parallel application. This function allows the user to determine what + * caused the HDF5 library to skip collective I/O locally, that is in the + * local process, and globally, across all processes. + * + * \details H5Pget_mpio_no_collective_cause() serves two purposes. It can be + * used to determine whether collective I/O was used for the last + * preceding parallel I/O call. If collective I/O was not used, the + * function retrieves the local and global causes that broke collective + * I/O on that parallel I/O call. The properties retrieved by this + * function are set before I/O takes place and are retained even when + * I/O fails. + * + * Valid values returned in \p local_no_collective_cause and \p + * global_no_collective_cause are as follows or, if there are multiple + * causes, a bitwise OR of the relevant causes; the numbers in the + * center column are the bitmask values: + * \snippet this H5D_mpio_no_collective_cause_t_snip + * \click4more + * + * \attention Each process determines whether it can perform collective I/O and + * broadcasts the result. Those results are combined to make a + * collective decision; collective I/O will be performed only if all + * processes can perform collective I/O.\n + * If collective I/O was not used, the causes that prevented it are + * reported by individual process by means of an enumerated set. The + * causes may differ among processes, so H5Pget_mpio_no_collective_cause() + * returns two property values. The first value is the one produced + * by the local process to report local causes. This local information + * is encoded in an enumeration, the \ref H5D_mpio_no_collective_cause_t + * described above, with all individual causes combined into a single + * enumeration value by means of a bitwise OR operation. The second + * value reports global causes; this global value is the result of a + * bitwise-OR operation across the values returned by all the processes. + * + * \since 1.8.10 + * + */ H5_DLL herr_t H5Pget_mpio_no_collective_cause(hid_t plist_id, uint32_t *local_no_collective_cause, uint32_t *global_no_collective_cause); #endif /* H5_HAVE_PARALLEL */ @@ -5880,6 +8052,36 @@ H5_DLL herr_t H5Pget_create_intermediate_group(hid_t plist_id, unsigned *crt_int H5_DLL herr_t H5Pset_create_intermediate_group(hid_t plist_id, unsigned crt_intmd); /* Group creation property list (GCPL) routines */ + +/** + * \ingroup GCPL + * + * \brief Returns the estimated link count and average link name length in a group + * + * \gcpl_id{plist_id} + * \param[out] est_num_entries The estimated number of links in the group + * referenced by \p plist_id + * \param[out] est_name_len The estimated average length of line names in the group + * referenced by \p plist_id + * \return \herr_t + * + * \details H5Pget_est_link_info() retrieves two settings from the group creation + * property list \p plist_id: the estimated number of links that are + * expected to be inserted into a group created with the property list + * and the estimated average length of those link names. + * + * The estimated number of links is returned in \p est_num_entries. The + * limit for \p est_num_entries is 64 K. + * + * The estimated average length of the anticipated link names is returned + * in \p est_name_len. The limit for \p est_name_len is 64 K. + * + * See \ref_group_impls for a discussion of the available types of HDF5 + * group structures. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pget_est_link_info(hid_t plist_id, unsigned *est_num_entries /* out */, unsigned *est_name_len /* out */); /** @@ -5949,7 +8151,64 @@ H5_DLL herr_t H5Pget_link_creation_order(hid_t plist_id, unsigned *crt_order_fla */ H5_DLL herr_t H5Pget_link_phase_change(hid_t plist_id, unsigned *max_compact /*out*/, unsigned *min_dense /*out*/); +/** + * \ingroup GCPL + * + * \brief Retrieves the anticipated size of the local heap for original-style + * groups + * + * \gcpl_id{plist_id} + * \param[out] size_hint Anticipated size of local heap + * \return \herr_t + * + * \details H5Pget_local_heap_size_hint() queries the group creation property + * list, \p plist_id, for the anticipated size of the local heap, \p + * size_hint, for original-style groups, i.e., for groups of the style + * used prior to HDF5 Release 1.8.0. See H5Pset_local_heap_size_hint() + * for further discussion. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pget_local_heap_size_hint(hid_t plist_id, size_t *size_hint /*out*/); +/** + * \ingroup GCPL + * + * \brief Sets estimated number of links and length of link names in a group + * + * \gcpl_id{plist_id} + * \param[in] est_num_entries Estimated number of links to be inserted into group + * \param[in] est_name_len Estimated average length of link names + * \return \herr_t + * + * \details H5Pset_est_link_info() inserts two settings into the group creation + * property list plist_id: the estimated number of links that are + * expected to be inserted into a group created with the property list + * and the estimated average length of those link names. + * + * The estimated number of links is passed in \p est_num_entries. The + * limit for \p est_num_entries is 64 K. + * + * The estimated average length of the anticipated link names is passed + * in \p est_name_len. The limit for \p est_name_len is 64 K. + * + * The values for these two settings are multiplied to compute the + * initial local heap size (for old-style groups, if the local heap + * size hint is not set) or the initial object header size for + * (new-style compact groups; see \ref_group_impls). Accurately setting + * these parameters will help reduce wasted file space. + * + * If a group is expected to have many links and to be stored in dense + * format, set \p est_num_entries to 0 (zero) for maximum + * efficiency. This will prevent the group from being created in the + * compact format. + * + * See \ref_group_impls for a discussion of the available types of HDF5 + * group structures. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pset_est_link_info(hid_t plist_id, unsigned est_num_entries, unsigned est_name_len); /** * \ingroup GCPL @@ -6043,11 +8302,115 @@ H5_DLL herr_t H5Pset_link_creation_order(hid_t plist_id, unsigned crt_order_flag * */ H5_DLL herr_t H5Pset_link_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); +/** + * \ingroup GCPL + * + * \brief Specifies the anticipated maximum size of a local heap + * + * \gcpl_id{plist_id} + * \param[in] size_hint Anticipated maximum size in bytes of local heap + * \return \herr_t + * + * \details H5Pset_local_heap_size_hint() is used with original-style HDF5 + * groups (see “Motivation” below) to specify the anticipated maximum + * local heap size, size_hint, for groups created with the group + * creation property list \p plist_id. The HDF5 library then uses \p + * size_hint to allocate contiguous local heap space in the file for + * each group created with \p plist_id. + * + * For groups with many members or very few members, an appropriate + * initial value of \p size_hint would be the anticipated number of + * group members times the average length of group member names, plus a + * small margin: + * \code + * size_hint = max_number_of_group_members * + * (average_length_of_group_member_link_names + 2) + * \endcode + * If it is known that there will be groups with zero members, the use + * of a group creation property list with \p size_hint set to to 1 (one) + * will guarantee the smallest possible local heap for each of those groups. + * + * Setting \p size_hint to zero (0) causes the library to make a + * reasonable estimate for the default local heap size. + * + * \par Motivation: + * In situations where backward-compatibility is required, specifically, when + * libraries prior to HDF5 Release 1.8.0 may be used to read the file, groups + * must be created and maintained in the original style. This is HDF5’s default + * behavior. If backward compatibility with pre-1.8.0 libraries is not a concern, + * greater efficiencies can be obtained with the new-format compact and indexed + * groups. See <a href="https://portal.hdfgroup.org/display/HDF5/Groups">Group + * implementations in HDF5</a> in the \ref H5G API introduction (at the bottom).\n + * H5Pset_local_heap_size_hint() is useful for tuning file size when files + * contain original-style groups with either zero members or very large + * numbers of members.\n + * The original style of HDF5 groups, the only style available prior to HDF5 + * Release 1.8.0, was well-suited for moderate-sized groups but was not optimized + * for either very small or very large groups. This original style remains the + * default, but two new group implementations were introduced in HDF5 Release 1.8.0: + * compact groups to accommodate zero to small numbers of members and indexed groups + * for thousands or tens of thousands of members ... or millions, if that's what + * your application requires.\n + * The local heap size hint, \p size_hint, is a performance tuning parameter for + * original-style groups. As indicated above, an HDF5 group may have zero, a handful, + * or tens of thousands of members. Since the original style of HDF5 groups stores the + * metadata for all of these group members in a uniform format in a local heap, the size + * of that metadata (and hence, the size of the local heap) can vary wildly from group + * to group. To intelligently allocate space and to avoid unnecessary fragmentation of + * the local heap, it can be valuable to provide the library with a hint as to the local + * heap’s likely eventual size. This can be particularly valuable when it is known that + * a group will eventually have a great many members. It can also be useful in conserving + * space in a file when it is known that certain groups will never have any members. + * + * \since 1.8.0 + * + */ H5_DLL herr_t H5Pset_local_heap_size_hint(hid_t plist_id, size_t size_hint); /* Map access property list (MAPL) routines */ #ifdef H5_HAVE_MAP_API +/** + * \ingroup MAPL + * + * \brief Set map iteration hints + * + * \mapl_id + * \param[in] key_prefetch_size Number of keys to prefetch at a time during + * iteration + * \param[in] key_alloc_size The initial size of the buffer allocated to hold + * prefetched keys + * \return \herr_t + * + * \details H5Pset_map_iterate_hints() adjusts the behavior of H5Miterate() when + * prefetching keys for iteration. The \p key_prefetch_size parameter + * specifies the number of keys to prefetch at a time during + * iteration. The \p key_alloc_size parameter specifies the initial + * size of the buffer allocated to hold these prefetched keys. If this + * buffer is too small it will be reallocated to a larger size, though + * this may result in an additional I/O. + * + * \since 1.12.? + * + */ H5_DLL herr_t H5Pset_map_iterate_hints(hid_t mapl_id, size_t key_prefetch_size, size_t key_alloc_size); +/** + * \ingroup MAPL + * + * \brief Set map iteration hints + * + * \mapl_id + * \param[out] key_prefetch_size Pointer to number of keys to prefetch at a time + * during iteration + * \param[out] key_alloc_size Pointer to the initial size of the buffer allocated + * to hold prefetched keys + * \return \herr_t + * + * \details H5Pget_map_iterate() returns the map iterate hints, \p key_prefetch_size + * and \p key_alloc_size, as set by H5Pset_map_iterate_hints(). + * + * \since 1.12.? + * + */ H5_DLL herr_t H5Pget_map_iterate_hints(hid_t mapl_id, size_t *key_prefetch_size /*out*/, size_t *key_alloc_size /*out*/); #endif /* H5_HAVE_MAP_API */ @@ -6409,9 +8772,6 @@ H5_DLL herr_t H5Pset_elink_acc_flags(hid_t lapl_id, unsigned flags); * </pre> * * - * \todo Add Programming Note for C++ Developers Using C Functions - * - * * \since 1.8.3 * */ @@ -6594,10 +8954,7 @@ H5_DLL herr_t H5Pset_nlinks(hid_t plist_id, size_t nlinks); * \li H5Pget_mcdt_search_cb() * \li H5Pset_copy_object() * \li H5Pset_mcdt_search_cb() - * - * \todo missing link to "Copying Committed Datatypes with H5Ocopy - A - * comprehensive discussion of copying committed datatypes (PDF) - * in Advanced Topics in HDF5 + * \li \ref_h5ocopy * * \since 1.8.9 * @@ -6711,8 +9068,7 @@ H5_DLL herr_t H5Pget_copy_object(hid_t plist_id, unsigned *copy_options /*out*/) * \li H5Pget_mcdt_search_cb() * \li H5Pset_copy_object() * \li H5Pset_mcdt_search_cb() - * - * \todo Link to Copying Committed Datatypes with H5Ocopy was removed. + * \li \ref_h5ocopy * * \since 1.8.9 * @@ -6803,8 +9159,8 @@ H5_DLL herr_t H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func, * \li H5Pget_mcdt_search_cb() * \li H5Pset_copy_object() * \li H5Pset_mcdt_search_cb() + * \li \ref_h5ocopy * - * \todo Link to Copying Committed Datatypes with H5Ocopy was removed. * \version 1.8.9 #H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG added in this release. * * \since 1.8.0 @@ -6890,9 +9246,7 @@ H5_DLL herr_t H5Pset_copy_object(hid_t plist_id, unsigned copy_options); * \li H5Pget_mcdt_search_cb() * \li H5Pset_copy_object() * \li H5Pset_mcdt_search_cb() - * - * \todo Link removed to "Copying Committed Datatypes with H5Ocopy" in Advanced Topics in HDF5 - * \todo Programming Note for C++ Developers Using C Functions: + * \li \ref_h5ocopy * * \since 1.8.9 * @@ -6911,38 +9265,316 @@ H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, v #define H5P_NO_CLASS H5P_ROOT /* Typedefs */ +/** + * \ingroup GPLOA + * + * \brief Registers a permanent property with a property list class + * + * \plistcls_id{cls_id} + * \param[in] name Name of property to register + * \param[in] size Size of property in bytes + * \param[in] def_value Default value for property in newly created + * property lists + * \param[in] prp_create Callback routine called when a property list is + * being created and the property value will be + * initialized + * \param[in] prp_set Callback routine called before a new value is + * copied into the property's value + * \param[in] prp_get Callback routine called when a property value is + * retrieved from the property + * \param[in] prp_del Callback routine called when a property is deleted + * from a property list + * \param[in] prp_copy Callback routine called when a property is copied + * from a property list + * \param[in] prp_close Callback routine called when a property list is + * being closed and the property value will be + * disposed of + * + * \return \herr_t + * + * \deprecated As of HDF5-1.8 this function was deprecated in favor of + * H5Pregister2() or the macro H5Pregister(). + * + * \details H5Pregister1() registers a new property with a property list + * class. The property will exist in all property list objects + * of that class after this routine is finished. The name of + * the property must not already exist. The default property + * value must be provided and all new property lists created + * with this property will have the property value set to the + * default provided. Any of the callback routines may be set + * to NULL if they are not needed. + * + * Zero-sized properties are allowed and do not store any data in + * the property list. These may be used as flags to indicate the + * presence or absence of a particular piece of information. The + * default pointer for a zero-sized property may be set to NULL. + * The property \p prp_create and \p prp_close callbacks are called for + * zero-sized properties, but the \p prp_set and \p prp_get callbacks + * are never called. + * + * The \p prp_create routine is called when a new property list with + * this property is being created. The #H5P_prp_create_func_t + * callback function is defined as #H5P_prp_cb1_t. + * + * The \p prp_create routine may modify the value to be set and those + * changes will be stored as the initial value of the property. + * If the \p prp_create routine returns a negative value, the new + * property value is not copied into the property and the + * \p prp_create routine returns an error value. + * + * The \p prp_set routine is called before a new value is copied into + * the property. The #H5P_prp_set_func_t callback function is defined + * as #H5P_prp_cb2_t. + * + * The \p prp_set routine may modify the value pointer to be set and + * those changes will be used when setting the property's value. + * If the \p prp_set routine returns a negative value, the new property + * value is not copied into the property and the \p prp_set routine + * returns an error value. The \p prp_set routine will not be called + * for the initial value; only the \p prp_create routine will be + * called. + * + * \b Note: The \p prp_set callback function may be useful to range + * check the value being set for the property or may perform some + * transformation or translation of the value set. The \p prp_get + * callback would then reverse the transformation or translation. + * A single \p prp_get or \p prp_set callback could handle multiple + * properties by performing different actions based on the property + * name or other properties in the property list. + * + * The \p prp_get routine is called when a value is retrieved from a + * property value. The #H5P_prp_get_func_t callback function is + * defined as #H5P_prp_cb2_t. + * + * The \p prp_get routine may modify the value to be returned from the + * query and those changes will be returned to the calling routine. + * If the \p prp_set routine returns a negative value, the query + * routine returns an error value. + * + * The \p prp_del routine is called when a property is being + * deleted from a property list. The #H5P_prp_delete_func_t + * callback function is defined as #H5P_prp_cb2_t. + * + * The \p prp_del routine may modify the value passed in, but the + * value is not used by the library when the \p prp_del routine + * returns. If the \p prp_del routine returns a negative value, + * the property list deletion routine returns an error value but + * the property is still deleted. + * + * The \p prp_copy routine is called when a new property list with + * this property is being created through a \p prp_copy operation. + * The #H5P_prp_copy_func_t callback function is defined as + * #H5P_prp_cb1_t. + * + * The \p prp_copy routine may modify the value to be set and those + * changes will be stored as the new value of the property. If + * the \p prp_copy routine returns a negative value, the new + * property value is not copied into the property and the \p prp_copy + * routine returns an error value. + * + * The \p prp_close routine is called when a property list with this + * property is being closed. The #H5P_prp_close_func_t callback + * function is defined as #H5P_prp_cb1_t. + * + * The \p prp_close routine may modify the value passed in, but the + * value is not used by the library when the \p prp_close routine + * returns. If the \p prp_close routine returns a negative value, the + * property list close routine returns an error value but the property + * list is still closed. + * + * The #H5P_prp_cb1_t is as follows: + * \snippet this H5P_prp_cb1_t_snip + * + * The #H5P_prp_cb2_t is as follows: + * \snippet this H5P_prp_cb2_t_snip + * + * + * \cpp_c_api_note + * + */ /* Function prototypes */ H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *def_value, H5P_prp_create_func_t prp_create, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close); +/** + * \ingroup GPLOA + * + * \brief Registers a temporary property with a property list + * + * \plist_id + * \param[in] name Name of property to create + * \param[in] size Size of property in bytes + * \param[in] value Initial value for the property + * \param[in] prp_set Callback routine called before a new value is copied + * into the property's value + * \param[in] prp_get Callback routine called when a property value is + * retrieved from the property + * \param[in] prp_delete Callback routine called when a property is deleted + * from a property list + * \param[in] prp_copy Callback routine called when a property is copied + * from an existing property list + * \param[in] prp_close Callback routine called when a property list is + * being closed and the property value will be disposed + * of + * + * \return \herr_t + * + * \deprecated As of HDF5-1.8 this function was deprecated in favor of + * H5Pinsert2() or the macro H5Pinsert(). + * + * \details H5Pinsert1() creates a new property in a property + * list. The property will exist only in this property list and + * copies made from it. + * + * The initial property value must be provided in \p value and + * the property value will be set accordingly. + * + * The name of the property must not already exist in this list, + * or this routine will fail. + * + * The \p prp_set and \p prp_get callback routines may be set to NULL + * if they are not needed. + * + * Zero-sized properties are allowed and do not store any data + * in the property list. The default value of a zero-size + * property may be set to NULL. They may be used to indicate the + * presence or absence of a particular piece of information. + * + * The \p prp_set routine is called before a new value is copied + * into the property. The #H5P_prp_set_func_t callback function + * is defined as #H5P_prp_cb2_t. + * The \p prp_set routine may modify the value pointer to be set and + * those changes will be used when setting the property's value. + * If the \p prp_set routine returns a negative value, the new property + * value is not copied into the property and the \p set routine + * returns an error value. The \p prp_set routine will be called for + * the initial value. + * + * \b Note: The \p prp_set callback function may be useful to range + * check the value being set for the property or may perform some + * transformation or translation of the value set. The \p prp_get + * callback would then reverse the transformation or translation. + * A single \p prp_get or \p prp_set callback could handle multiple + * properties by performing different actions based on the + * property name or other properties in the property list. + * + * The \p prp_get routine is called when a value is retrieved from + * a property value. The #H5P_prp_get_func_t callback function + * is defined as #H5P_prp_cb2_t. + * + * The \p prp_get routine may modify the value to be returned from + * the query and those changes will be preserved. If the \p prp_get + * routine returns a negative value, the query routine returns + * an error value. + * + * The \p prp_delete routine is called when a property is being + * deleted from a property list. The #H5P_prp_delete_func_t + * callback function is defined as #H5P_prp_cb2_t. + * + * The \p prp_copy routine is called when a new property list with + * this property is being created through a \p prp_copy operation. + * The #H5P_prp_copy_func_t callback function is defined as + * #H5P_prp_cb1_t. + * + * The \p prp_copy routine may modify the value to be set and those + * changes will be stored as the new value of the property. If the + * \p prp_copy routine returns a negative value, the new property value + * is not copied into the property and the prp_copy routine returns an + * error value. + * + * The \p prp_close routine is called when a property list with this + * property is being closed. + * The #H5P_prp_close_func_t callback function is defined as + * #H5P_prp_cb1_t. + * + * The \p prp_close routine may modify the value passed in, the + * value is not used by the library when the close routine + * returns. If the \p prp_close routine returns a negative value, + * the property list \p prp_close routine returns an error value + * but the property list is still closed. + * + * \b Note: There is no \p prp_create callback routine for temporary + * property list objects; the initial value is assumed to + * have any necessary setup already performed on it. + * + * The #H5P_prp_cb1_t is as follows: + * \snippet this H5P_prp_cb1_t_snip + * + * The #H5P_prp_cb2_t is as follows: + * \snippet this H5P_prp_cb2_t_snip + + * \cpp_c_api_note + */ H5_DLL herr_t H5Pinsert1(hid_t plist_id, const char *name, size_t size, void *value, H5P_prp_set_func_t prp_set, H5P_prp_get_func_t prp_get, H5P_prp_delete_func_t prp_delete, H5P_prp_copy_func_t prp_copy, H5P_prp_close_func_t prp_close); +/** + * \ingroup GPLO + * + * \brief Encodes the property values in a property list into a binary + * buffer + * + * \plist_id + * \param[out] buf Buffer into which the property list will be encoded. + * If the provided buffer is NULL, the size of the + * buffer required is returned through \p nalloc; the + * function does nothing more. + * \param[out] nalloc The size of the required buffer + * + * \return \herr_t + * + * \deprecated As of HDF5-1.12 this function has been deprecated in favor of + * H5Pencode2() or the macro H5Pencode(). + * + * \details H5Pencode1() encodes the property list \p plist_id into the + * binary buffer \p buf. + * + * If the required buffer size is unknown, \p buf can be passed + * in as NULL and the function will set the required buffer size + * in \p nalloc. The buffer can then be created and the property + * list encoded with a subsequent H5Pencode1() call. + * + * If the buffer passed in is not big enough to hold the encoded + * properties, the H5Pencode1() call can be expected to fail with + * a segmentation fault. + * + * Properties that do not have encode callbacks will be skipped. + * There is currently no mechanism to register an encode callback for + * a user-defined property, so user-defined properties cannot currently + * be encoded. + * + * Some properties cannot be encoded, particularly properties that are + * reliant on local context. + * + * \since 1.10.0 + * + */ H5_DLL herr_t H5Pencode1(hid_t plist_id, void *buf, size_t *nalloc); /** - * \ingroup OCPL + * \ingroup DCPL * * \brief Returns information about a filter in a pipeline (DEPRECATED) * - * \todo H5Pget_filter1() prototype does not match source in H5Pocpl.c. - * Also, it is not in a deprecated file. Is that okay? + * * * \plist_id{plist_id} - * \param[in] filter Sequence number within the filter pipeline of the filter - * for which information is sought - * \param[out] flags Bit vector specifying certain general properties of - * the filter + * \param[in] filter Sequence number within the filter pipeline of + * the filter for which information is sought + * \param[out] flags Bit vector specifying certain general properties + * of the filter * \param[in,out] cd_nelmts Number of elements in \p cd_values - * \param[out] cd_values Auxiliary data for the filter - * \param[in] namelen Anticipated number of characters in \p name - * \param[out] name Name of the filter + * \param[out] cd_values Auxiliary data for the filter + * \param[in] namelen Anticipated number of characters in \p name + * \param[out] name Name of the filter * * \return Returns the filter identifier if successful; Otherwise returns * a negative value. See: #H5Z_filter_t * + * \deprecated When was this function deprecated? + * * \details H5Pget_filter1() returns information about a filter, specified * by its filter number, in a filter pipeline, specified by the * property list with which it is associated. @@ -6977,13 +9609,127 @@ H5_DLL herr_t H5Pencode1(hid_t plist_id, void *buf, size_t *nalloc); H5_DLL H5Z_filter_t H5Pget_filter1(hid_t plist_id, unsigned filter, unsigned int *flags /*out*/, size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, char name[]); -H5_DLL herr_t H5Pget_filter_by_id1(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/, - size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, - char name[] /*out*/); -H5_DLL herr_t H5Pget_version(hid_t plist_id, unsigned *boot /*out*/, unsigned *freelist /*out*/, - unsigned *stab /*out*/, unsigned *shhdr /*out*/); -H5_DLL herr_t H5Pset_file_space(hid_t plist_id, H5F_file_space_type_t strategy, hsize_t threshold); -H5_DLL herr_t H5Pget_file_space(hid_t plist_id, H5F_file_space_type_t *strategy, hsize_t *threshold); +/** + * \ingroup DCPL + * + * \brief Returns information about the specified filter + * + * \plist_id{plist_id} + * \param[in] id Filter identifier + * \param[out] flags Bit vector specifying certain general properties + * of the filter + * \param[in,out] cd_nelmts Number of elements in \p cd_values + * \param[out] cd_values Auxiliary data for the filter + * \param[in] namelen Anticipated number of characters in \p name + * \param[out] name Name of the filter + * + * + * \return Returns a non-negative value if successful; Otherwise returns + * a negative value. + * + * \deprecated As of HDF5-1.8 this function was deprecated in favor of + * H5Pget_filter_by_id2() or the macro H5Pget_filter_by_id(). + * + * \details H5Pget_filter_by_id1() returns information about a filter, specified + * in \p id, a filter identifier. + * + * \p plist_id must be a dataset or group creation property list and + * \p id must be in the associated filter pipeline. + * + * The \p id and \p flags parameters are used in the same + * manner as described in the discussion of H5Pset_filter(). + * + * Aside from the fact that they are used for output, the parameters + * \p cd_nelmts and \p cd_values[] are used in the same manner as + * described in the discussion of H5Pset_filter(). + * On input, the \p cd_nelmts parameter indicates the number of entries + * in the \p cd_values[] array allocated by the calling program; + * on exit it contains the number of values defined by the filter. + * + * On input, the \p namelen parameter indicates the number of + * characters allocated for the filter name by the calling program + * in the array \p name[]. On exit \p name[] contains the name of the + * filter with one character of the name in each element of the array. + * + * If the filter specified in \p id is not set for the property + * list, an error will be returned and this function will fail. + * + * + * \version 1.8.5 Function extended to work with group creation property + * lists. + * \version 1.8.0 Function H5Pget_filter_by_id() renamed to + * H5Pget_filter_by_id1() and deprecated in this release. + * \version 1.6.0 Function introduced in this release. + */ +H5_DLL herr_t H5Pget_filter_by_id1(hid_t plist_id, H5Z_filter_t id, unsigned int *flags /*out*/, + size_t *cd_nelmts /*out*/, unsigned cd_values[] /*out*/, size_t namelen, + char name[] /*out*/); +/** + * \ingroup FCPL + * + * \brief Retrieves the version information of various objects + * for a file creation property list(deprecated) + * + * \plist_id + * \param[out] boot Pointer to location to return super block version number + * \param[out] freelist Pointer to location to return global freelist version number + * \param[out] stab Pointer to location to return symbol table version number + * \param[out] shhdr Pointer to location to return shared object header version + * number + * + * \return \herr_t + * + * \deprecated Deprecated in favor of the function H5Fget_info() + * + * \details H5Pget_version() retrieves the version information of various objects + * for a file creation property list. Any pointer parameters which are + * passed as NULL are not queried. + * + * \version 1.6.4 \p boot, \p freelist, \p stab, \p shhdr parameter types + * changed to unsigned. + * + */ +H5_DLL herr_t H5Pget_version(hid_t plist_id, unsigned *boot /*out*/, unsigned *freelist /*out*/, + unsigned *stab /*out*/, unsigned *shhdr /*out*/); +/** + * \ingroup FCPL + * + * \brief Sets the file space handling strategy and the free-space section + * size threshold. + * + * \fcpl_id{plist_id} + * \param[in] strategy The file space handling strategy to be used. See: + * #H5F_fspace_strategy_t + * \param[in] threshold The smallest free-space section size that the free + * space manager will track + * + * \return \herr_t + * + * \deprecated When was this function deprecated? + * + * \details Maps to the function H5Pset_file_space_strategy(). + * + */ +H5_DLL herr_t H5Pset_file_space(hid_t plist_id, H5F_file_space_type_t strategy, hsize_t threshold); +/** + * \ingroup FCPL + * + * \brief Retrieves the file space handling strategy, and threshold value for + * a file creation property list + * + * \fcpl_id{plist_id} + * \param[out] strategy Pointer to the file space handling strategy + * \param[out] threshold Pointer to the free-space section size threshold value + * + * \return \herr_t + * + * \deprecated When was this function deprecated? + * + * \details Maps to the function H5Pget_file_space_strategy() + * + * + */ +H5_DLL herr_t H5Pget_file_space(hid_t plist_id, H5F_file_space_type_t *strategy, hsize_t *threshold); #endif /* H5_NO_DEPRECATED_SYMBOLS */ #ifdef __cplusplus diff --git a/src/H5Rpublic.h b/src/H5Rpublic.h index 5d356e9..b33960e 100644 --- a/src/H5Rpublic.h +++ b/src/H5Rpublic.h @@ -40,40 +40,54 @@ /* Public Typedefs */ /*******************/ -/* +//! <!-- [H5R_type_t_snip] --> +/** * Reference types allowed. - * DO NOT CHANGE THE ORDER or VALUES as reference type values are encoded into - * the datatype message header. + * + * \internal DO NOT CHANGE THE ORDER or VALUES as reference type values are + * encoded into the datatype message header. */ typedef enum { - H5R_BADTYPE = (-1), /* Invalid reference type */ - H5R_OBJECT1 = 0, /* Backward compatibility (object) */ - H5R_DATASET_REGION1 = 1, /* Backward compatibility (region) */ - H5R_OBJECT2 = 2, /* Object reference */ - H5R_DATASET_REGION2 = 3, /* Region reference */ - H5R_ATTR = 4, /* Attribute Reference */ - H5R_MAXTYPE = 5 /* Highest type (invalid) */ + H5R_BADTYPE = (-1), /**< Invalid reference type */ + H5R_OBJECT1 = 0, /**< Backward compatibility (object) */ + H5R_DATASET_REGION1 = 1, /**< Backward compatibility (region) */ + H5R_OBJECT2 = 2, /**< Object reference */ + H5R_DATASET_REGION2 = 3, /**< Region reference */ + H5R_ATTR = 4, /**< Attribute Reference */ + H5R_MAXTYPE = 5 /**< Highest type (invalid) */ } H5R_type_t; +//! <!-- [H5R_type_t_snip] --> /* Deprecated types are kept for backward compatibility with previous versions */ +//! <!-- [hobj_ref_t_snip] --> /** - * Deprecated object reference type that is used with deprecated reference APIs. - * Note! This type can only be used with the "native" HDF5 VOL connector. + * \deprecated Deprecated object reference type that is used with deprecated + * reference APIs. + * + * \note This type can only be used with the "native" HDF5 VOL connector. */ typedef haddr_t hobj_ref_t; +//! <!-- [hobj_ref_t_snip] --> +//! <!-- [hdset_reg_ref_t_snip] --> /** - * Dataset region reference type that is used with deprecated reference APIs. - * (Buffer to store heap ID and index) - * This needs to be large enough to store largest haddr_t in a worst case + * Buffer to store heap ID and index + * + * This needs to be large enough to store largest #haddr_t in a worst case * machine (8 bytes currently) plus an int. - * Note! This type can only be used with the "native" HDF5 VOL connector. + * + * \deprecated Dataset region reference type that is used with deprecated + * reference APIs. + * + * \note This type can only be used with the "native" HDF5 VOL connector. */ typedef struct { uint8_t __data[H5R_DSET_REG_REF_BUF_SIZE]; } hdset_reg_ref_t; +//! <!-- [hdset_reg_ref_t_snip] --> +//! <!-- [H5R_ref_t_snip] --> /** * Opaque reference type. The same reference type is used for object, * dataset region and attribute references. This is the type that @@ -81,10 +95,11 @@ typedef struct { */ typedef struct { union { - uint8_t __data[H5R_REF_BUF_SIZE]; /* opaque data */ - int64_t align; /* ensures alignment */ + uint8_t __data[H5R_REF_BUF_SIZE]; /**< opaque data */ + int64_t align; /**< ensures alignment */ } u; } H5R_ref_t; +//! <!-- [H5R_ref_t_snip] --> /********************/ /* Public Variables */ @@ -121,8 +136,8 @@ extern "C" { * must be of the same type as the object being referenced, that is * a group, dataset or committed datatype property list. * - * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char - * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * \ref H5R_ref_t is defined in H5Rpublic.h as: + * \snippet this H5R_ref_t_snip * * H5Rdestroy() should be used to release the resource from the * reference. @@ -157,14 +172,12 @@ H5_DLL herr_t H5Rcreate_object(hid_t loc_id, const char *name, hid_t oapl_id, H5 * must be of the same type as the object being referenced, that is * a dataset property list in this case. * - * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char - * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * \ref H5R_ref_t is defined in H5Rpublic.h as: + * \snippet this H5R_ref_t_snip * * H5Rdestroy() should be used to release the resource from the * reference. * - * \see function_name() - * */ H5_DLL herr_t H5Rcreate_region(hid_t loc_id, const char *name, hid_t space_id, hid_t oapl_id, H5R_ref_t *ref_ptr); @@ -196,8 +209,8 @@ H5_DLL herr_t H5Rcreate_region(hid_t loc_id, const char *name, hid_t space_id, h * as that object, that is a group, dataset or committed datatype * property list. * - * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char - * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * \ref H5R_ref_t is defined in H5Rpublic.h as: + * \snippet this H5R_ref_t_snip * * H5Rdestroy() should be used to release the resource from the * reference. @@ -216,12 +229,12 @@ H5_DLL herr_t H5Rcreate_attr(hid_t loc_id, const char *name, const char *attr_na * * \return \herr_t * - * \details Given a reference, ref_ptr, to an object, region or attribute - * attached to an object, H5R_DESTROY releases allocated resources + * \details Given a reference, \p ref_ptr, to an object, region or attribute + * attached to an object, H5Rdestroy() releases allocated resources * from a previous create call. * - * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char - * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * \ref H5R_ref_t is defined in H5Rpublic.h as: + * \snippet this H5R_ref_t_snip * */ H5_DLL herr_t H5Rdestroy(H5R_ref_t *ref_ptr); @@ -236,23 +249,20 @@ H5_DLL herr_t H5Rdestroy(H5R_ref_t *ref_ptr); * * \param[in] ref_ptr Pointer to reference * - * \return Returns a valid reference type if successful; otherwise returns #H5R_UNKNOWN. + * \return Returns a valid reference type if successful; otherwise returns #H5R_BADTYPE . * * \details Given a reference, \p ref_ptr, H5Rget_type() returns the * type of the reference. * * Valid returned reference types are: + * \snippet this H5R_type_t_snip * - * #H5R_OBJECT2 Object reference version 2 - * #H5R_DATASET_REGION2 Region reference version 2 - * #H5R_ATTRIBUTE Attribute reference - * - * Note that #H5R_OBJECT1 and #H5R_DATASET REGION1 can never be - * associated to an H5R_ref_t reference and can therefore never be + * Note that #H5R_OBJECT1 and #H5R_DATASET_REGION1 can never be + * associated to an \ref H5R_ref_t reference and can therefore never be * returned through that function. * - * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char - * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * \ref H5R_ref_t is defined in H5Rpublic.h as: + * \snippet this H5R_ref_t_snip * */ H5_DLL H5R_type_t H5Rget_type(const H5R_ref_t *ref_ptr); @@ -273,8 +283,8 @@ H5_DLL H5R_type_t H5Rget_type(const H5R_ref_t *ref_ptr); * \details H5Requal() determines whether two references point to the * same object, region or attribute. * - * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char - * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * \ref H5R_ref_t is defined in H5Rpublic.h as: + * \snippet this H5R_ref_t_snip * */ H5_DLL htri_t H5Requal(const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr); @@ -320,8 +330,8 @@ H5_DLL herr_t H5Rcopy(const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr); * must be of the same type as the object being referenced, that is * a group or dataset property list. * - * H5R_ref_t is defined in H5Rpublic.h as: typedef unsigned char - * H5R_ref_t[#H5R_REF_BUF_SIZE]; + * \ref H5R_ref_t is defined in H5Rpublic.h as: + * \snippet this H5R_ref_t_snip * * The object opened with this function should be closed when it * is no longer needed so that resource leaks will not develop. Use @@ -333,22 +343,8 @@ H5_DLL hid_t H5Ropen_object(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); /** * -------------------------------------------------------------------------- - * \ingroup H5R - * - * \brief Asynchronous version of H5Ropen_object() - * - * \app_file - * \app_func - * \app_line - * \param[out] ref_ptr Pointer to reference to open - * \rapl_id - * \oapl_id - * \es_id - * - * \return \hid_t{object} - * - * \see H5Ropen_object() - * + * \ingroup ASYNC + * \async_variant_of{H5Ropen} */ H5_DLL hid_t H5Ropen_object_async(const char *app_file, const char *app_func, unsigned app_line, H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, hid_t es_id); @@ -388,22 +384,8 @@ H5_DLL hid_t H5Ropen_region(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); /** * -------------------------------------------------------------------------- - * \ingroup H5R - * - * \brief Asynchronous version of H5Ropen_region() - * - * \app_file - * \app_func - * \app_line - * \param[in] ref_ptr Pointer to reference to open - * \rapl_id - * \oapl_id - * \es_id - * - * \return \hid_t{dataspace} - * - * \see H5Ropen_region() - * + * \ingroup ASYNC + * \async_variant_of{H5Ropen_region} */ H5_DLL hid_t H5Ropen_region_async(const char *app_file, const char *app_func, unsigned app_line, H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, hid_t es_id); @@ -440,22 +422,8 @@ H5_DLL hid_t H5Ropen_attr(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id); /** * -------------------------------------------------------------------------- - * \ingroup H5R - * - * \brief Asynchronous version of H5Ropen_attr() - * - * \app_file - * \app_func - * \app_line - * \param[in] ref_ptr Pointer to reference to open - * \rapl_id - * \aapl_id - * \es_id - * - * \return \hid_t{attribute} - * - * \see H5Ropen_attr() - * + * \ingroup ASYNC + * \async_variant_of{H5Ropen_attr} */ H5_DLL hid_t H5Ropen_attr_async(const char *app_file, const char *app_func, unsigned app_line, H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id, hid_t es_id); @@ -485,10 +453,7 @@ H5_DLL hid_t H5Ropen_attr_async(const char *app_file, const char *app_func, unsi * Upon success, the function returns in \p obj_type the type of * the object that the reference points to. Valid values for this * referenced object type are as followed (defined in H5Opublic.h): - * - * H5O_TYPE_GROUP Object is a group - * H5O_TYPE_DATASET Object is a dataset - * H5O_TYPE_NAMED_DATATYPE Object is a named datatype + * \snippet H5Opublic.h H5O_type_t_snip * */ H5_DLL herr_t H5Rget_obj_type3(H5R_ref_t *ref_ptr, hid_t rapl_id, H5O_type_t *obj_type); @@ -540,12 +505,12 @@ H5_DLL ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *name, size_t siz * \details H5Rget_obj_name() retrieves the object name for the object, * region or attribute reference pointed to by \p ref_ptr. * - * The parameter \p rapl id is a reference access property list + * The parameter \p rapl_id is a reference access property list * identifier for the reference. The access property list can * be used to access external files that the reference points to * (through a file access property list). * - * Up to size characters of the name are returned in name; additional + * Up to size characters of the name are returned in \p name; additional * characters, if any, are not returned to the user application. If * the length of the name, which determines the required value of * \p size, is unknown, a preliminary call to H5Rget_obj_name() call @@ -553,8 +518,8 @@ H5_DLL ssize_t H5Rget_file_name(const H5R_ref_t *ref_ptr, char *name, size_t siz * object name. That value can then be passed in for \p size in the * second call to H5Rget_obj_name(), which will retrieve the actual * name. If there is no name associated with the object identifier - * or if the name is #NULL, H5Rget_obj_name() returns the size of - * the name buffer (the size does not include the #NULL terminator). + * or if the name is NULL, H5Rget_obj_name() returns the size of + * the name buffer (the size does not include the \c \0 terminator). * * If \p ref_ptr is an object reference, \p name will be returned with * a name for the referenced object. If \p ref_ptr is a dataset region @@ -624,15 +589,334 @@ H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t siz /* Function prototypes */ #ifndef H5_NO_DEPRECATED_SYMBOLS +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Retrieves the type of object that an object reference points to + * + * \param[in] id The dataset containing the reference object or the group + * containing that dataset + * \param[in] ref_type Type of reference to query + * \param[in] ref Reference to query + * + * \return Returns a valid object type if successful; otherwise returns a + * negative value (#H5G_UNKNOWN). + * + * \deprecated This function has been renamed from H5Rget_obj_type() and is + * deprecated in favor of the macro H5Rget_obj_type() or the + * function H5Rget_obj_type2(). + * + * \details Given an object reference, \p ref, H5Rget_obj_type1() returns the + * type of the referenced object. + * + * A \Emph{reference type} is the type of reference, either an object + * reference or a dataset region reference. An \Emph{object reference} + * points to an HDF5 object while a \Emph{dataset region reference} + * points to a defined region within a dataset. + * + * The \Emph{referenced object} is the object the reference points + * to. The \Emph{referenced object type}, or the type of the referenced + * object, is the type of the object that the reference points to. + * + * The location identifier, \p id, is the identifier for either the + * dataset containing the object reference or the group containing that + * dataset. + * + * Valid reference types, to pass in as \p ref_type, include the + * following: + * \snippet this H5R_type_t_snip + * + * If the application does not already know the object reference type, + * that can be determined with three preliminary calls: + * + * \li Call H5Dget_type() on the dataset containing the reference to + * get a datatype identifier for the dataset’s datatype. + * \li Using that datatype identifier, H5Tget_class() returns a datatype + * class.\n If the datatype class is #H5T_REFERENCE, H5Tequal() can + * then be used to determine whether the reference’s datatype is + * #H5T_STD_REF_OBJ or #H5T_STD_REF_DSETREG: + * - If the datatype is #H5T_STD_REF_OBJ, the reference object type + * is #H5R_OBJECT. + * - If the datatype is #H5T_STD_REF_DSETREG, the reference object + * type is #H5R_DATASET_REGION. + * + * When the function completes successfully, it returns one of the + * following valid object type values (defined in H5Gpublic.h): + * \snippet H5Gpublic.h H5G_obj_t_snip + * + * \version 1.8.0 Function H5Rget_obj_type() renamed to H5Rget_obj_type1() and + * deprecated in this release. + * \since 1.6.0 + * + */ H5_DLL H5G_obj_t H5Rget_obj_type1(hid_t id, H5R_type_t ref_type, const void *ref); -H5_DLL hid_t H5Rdereference1(hid_t obj_id, H5R_type_t ref_type, const void *ref); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Opens the HDF5 object referenced + * + * \obj_id + * \param[in] ref_type The reference type of \p ref + * \param[in] ref Reference to open + * + * \return Returns identifier of referenced object if successful; otherwise + * returns a negative value. + * + * \deprecated This function has been renamed from H5Rdereference() and is + * deprecated in favor of the macro H5Rdereference() or the function + * H5Rdereference2(). + * + * \details Given a reference, \p ref, to an object or a region in an object, + * H5Rdereference1() opens that object and returns an identifier. + * + * The parameter \p obj_id must be a valid identifier for an object in + * the HDF5 file containing the referenced object, including the file + * identifier. + * + * The parameter \p ref_type specifies the reference type of the + * reference \p ref. \p ref_type may contain either of the following + * values: + * - #H5R_OBJECT + * - #H5R_DATASET_REGION + * + * The object opened with this function should be closed when it is no + * longer needed so that resource leaks will not develop. Use the + * appropriate close function such as H5Oclose() or H5Dclose() for + * datasets. + * + * \version 1.10.0 Function H5Rdereference() renamed to H5Rdereference1() and + * deprecated in this release. + * \since 1.8.0 + * + */ +H5_DLL hid_t H5Rdereference1(hid_t obj_id, H5R_type_t ref_type, const void *ref); #endif /* H5_NO_DEPRECATED_SYMBOLS */ -H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id); -H5_DLL herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *ref, H5O_type_t *obj_type); -H5_DLL hid_t H5Rdereference2(hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref); -H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref); +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Creates a reference + * + * \param[out] ref Reference created by the function call + * \param[in] loc_id Location identifier used to locate the object being pointed to + * \param[in] name Name of object at location \p loc_id + * \param[in] ref_type Type of reference + * \param[in] space_id Dataspace identifier with selection. Used only for + * dataset region references; pass as -1 if reference is + * an object reference, i.e., of type #H5R_OBJECT + * + * \return \herr_t + * + * \details H5Rcreate() creates the reference, \p ref, of the type specified in + * \p ref_type, pointing to the object \p name located at \p loc_id. + * + * The HDF5 library maps the void type specified above for \p ref to + * the type specified in \p ref_type, which will be one of the following: + * \snippet this H5R_type_t_snip + * + * The parameters \p loc_id and \p name are used to locate the object. + * + * The parameter \p space_id identifies the dataset region that a + * dataset region reference points to. This parameter is used only with + * dataset region references and should be set to -1 if the reference + * is an object reference, #H5R_OBJECT. + * + * \since 1.8.0 + */ +H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t ref_type, hid_t space_id); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Retrieves the type of object that an object reference points to + * + * \param[in] id The dataset containing the reference object or the group + * containing that dataset + * \param[in] ref_type Type of reference to query + * \param[in] ref Reference to query + * \param[out] obj_type Type of referenced object + * + * \return \herr_t + * + * \details Given an object reference, \p ref, H5Rget_obj_type2() returns the + * type of the referenced object in \p obj_type. + * + * A \Emph{reference type} is the type of reference, either an object + * reference or a dataset region reference. An \Emph{object reference} + * points to an HDF5 object while a \Emph{dataset region reference} + * points to a defined region within a dataset. + * + * The \Emph{referenced object} is the object the reference points + * to. The \Emph{referenced object type}, or the type of the referenced + * object, is the type of the object that the reference points to. + * + * The location identifier, \p id, is the identifier for either the + * dataset containing the object reference or the group containing that + * dataset. + * + * Valid reference types, to pass in as \p ref_type, include the + * following: + * \snippet this H5R_type_t_snip + * + * If the application does not already know the object reference type, + * that can be determined with three preliminary calls: + * + * \li Call H5Dget_type() on the dataset containing the reference to + * get a datatype identifier for the dataset’s datatype. + * \li Using that datatype identifier, H5Tget_class() returns a datatype + * class.\n If the datatype class is #H5T_REFERENCE, H5Tequal() can + * then be used to determine whether the reference’s datatype is + * #H5T_STD_REF_OBJ or #H5T_STD_REF_DSETREG: + * - If the datatype is #H5T_STD_REF_OBJ, the reference object type + * is #H5R_OBJECT. + * - If the datatype is #H5T_STD_REF_DSETREG, the reference object + * type is #H5R_DATASET_REGION. + * + * When the function completes successfully, it returns one of the + * following valid object type values (defined in H5Opublic.h): + * \snippet H5Opublic.h H5O_type_t_snip + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *ref, H5O_type_t *obj_type); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Opens the HDF5 object referenced + * + * \obj_id + * \oapl_id + * \param[in] ref_type The reference type of \p ref + * \param[in] ref Reference to open + * + * \return Returns identifier of referenced object if successful; otherwise + * returns a negative value. + * + * \details Given a reference, \p ref, to an object or a region in an object, + * H5Rdereference2() opens that object and returns an identifier. + * + * The parameter \p obj_id must be a valid identifier for the HDF5 file + * containing the referenced object or for any object in that HDF5 + * file. + * + * The parameter \p oapl_id is an object access property list + * identifier for the referenced object. The access property list must + * be of the same type as the object being referenced, that is a group, + * dataset, or datatype property list. + * + * The parameter \p ref_type specifies the reference type of the + * reference \p ref. \p ref_type may contain either of the following + * values: + * - #H5R_OBJECT + * - #H5R_DATASET_REGION + * + * The object opened with this function should be closed when it is no + * longer needed so that resource leaks will not develop. Use the + * appropriate close function such as H5Oclose() or H5Dclose() for + * datasets. + * + * \since 1.10.0 + * + */ +H5_DLL hid_t H5Rdereference2(hid_t obj_id, hid_t oapl_id, H5R_type_t ref_type, const void *ref); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Sets up a dataspace and selection as specified by a region reference + * + * \param[in] dataset File identifier or identifier for any object in the file + * containing the referenced region + * \param[in] ref_type Reference type of \p ref, which must be #H5R_DATASET_REGION + * \param[in] ref Region reference to open + * + * \return Returns a valid dataspace identifier if successful; otherwise returns + * a negative value. + * + * \details H5Rget_region() creates a copy of the dataspace of the dataset + * pointed to by a region reference, \p ref, and defines a selection + * matching the selection pointed to by ref within the dataspace copy. + * + * \p dataset is used to identify the file containing the referenced + * region; it can be a file identifier or an identifier for any object + * in the file. + * + * The parameter \p ref_type specifies the reference type of \p ref and + * must contain the value #H5R_DATASET_REGION. + * + * Use H5Sclose() to release the dataspace identifier returned by this + * function when the identifier is no longer needed. + * + */ +H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5R + * + * \brief Retrieves a name for a referenced object + * + * \param[in] loc_id Identifier for the file containing the reference or for + * any object in that file + * \param[in] ref_type Type of reference + * \param[in] ref An object or dataset region reference + * \param[out] name A buffer to place the name of the referenced object or + * dataset region. If \c NULL, then this call will return the + * size in bytes of the name. + * \param[in] size The size of the \p name buffer. When the size is passed in, + * the \c NULL terminator needs to be included. + * + * \return Returns the length of the name if successful, returning 0 (zero) if + * no name is associated with the identifier. Otherwise returns a + * negative value. + * + * \details H5Rget_name() retrieves a name for the object identified by \p ref.\n + * \p loc_id is used to identify the file containing the reference. It + * can be the file identifier for the file containing the reference or + * an identifier for any object in that file. + * + * \ref H5R_type_t is the reference type of \p ref. Valid values + * include the following: + * \snippet this H5R_type_t_snip + * + * \p ref is the reference for which the target object’s name is + * sought. + * + * If \p ref is an object reference, \p name will be returned with a + * name for the referenced object. If \p ref is a dataset region + * reference, \p name will contain a name for the object containing the + * referenced region. + * + * Up to \p size characters of the name are returned in \p name; + * additional characters, if any, are not returned to the user + * application. + * + * If the length of the name, which determines the required value of \p + * size, is unknown, a preliminary H5Rget_name() call can be made. The + * return value of this call will be the size of the object name. That + * value can then be assigned to \p size for a second H5Rget_name() + * call, which will retrieve the actual name. + * + * If there is no name associated with the object identifier or if the + * \p name is \c NULL, H5Rget_name() returns the size of the \p name + * buffer (the size does not include the \p NULL terminator). + * + * Note that an object in an HDF5 file may have multiple paths if there + * are multiple links pointing to it. This function may return any one + * of these paths. + * + * \since 1.8.0 + */ H5_DLL ssize_t H5Rget_name(hid_t loc_id, H5R_type_t ref_type, const void *ref, char *name, size_t size); #ifdef __cplusplus diff --git a/src/H5Spublic.h b/src/H5Spublic.h index 5037e0a..fd85dcc 100644 --- a/src/H5Spublic.h +++ b/src/H5Spublic.h @@ -364,10 +364,8 @@ H5_DLL hid_t H5Sdecode(const void *buf); * * \note Motivation: This function was introduced in HDF5-1.12 as part of the * H5Sencode() format change to enable 64-bit selection encodings and - * a dataspace selection that is tied to a file. See the New Features - * in HDF5 Release 1.12 as well as the H5Sencode() / H5Sdecode() Format Change RFC. - * - * \todo Fix the references. + * a dataspace selection that is tied to a file. See the \ref_news_112 + * as well as the \ref_sencode_fmt_change. * * \since 1.12.0 * @@ -1069,7 +1067,7 @@ H5_DLL herr_t H5Sselect_copy(hid_t dst_id, hid_t src_id); * buffer as: * \n 0 0 0 0 13 5 11 17 7 21 29 21 * - * \version 1.6.4 C coord parameter type changed to \p const #hsize_t. + * \version 1.6.4 C coord parameter type changed to \p const hsize_t. * \version 1.6.4 Fortran \p coord parameter type changed to \p INTEGER(HSIZE_T). * \since 1.0.0 * diff --git a/src/H5Tmodule.h b/src/H5Tmodule.h index 4f9edde..c489edc 100644 --- a/src/H5Tmodule.h +++ b/src/H5Tmodule.h @@ -44,12 +44,8 @@ * \ingroup H5T * \defgroup ENUM Enumeration Datatypes * \ingroup H5T - * \defgroup GTO General Datatype Operations - * \ingroup H5T * \defgroup OPAQUE Opaque Datatypes * \ingroup H5T - * \defgroup STRING String Datatypes - * \ingroup H5T * \defgroup VLEN Variable-length Sequence Datatypes * \ingroup H5T * diff --git a/src/H5Tpublic.h b/src/H5Tpublic.h index 1457053..5301ea2 100644 --- a/src/H5Tpublic.h +++ b/src/H5Tpublic.h @@ -28,7 +28,7 @@ * internal If this goes over 16 types (0-15), the file format will need to * change. */ -//! [H5T_class_t_snip] +//! <!-- [H5T_class_t_snip] --> typedef enum H5T_class_t { H5T_NO_CLASS = -1, /**< error */ H5T_INTEGER = 0, /**< integer types */ @@ -45,12 +45,12 @@ typedef enum H5T_class_t { H5T_NCLASSES /**< sentinel: this must be last */ } H5T_class_t; -//! [H5T_class_t_snip] +//! <!-- [H5T_class_t_snip] --> /** * Byte orders */ -//! [H5T_order_t_snip] +//! <!-- [H5T_order_t_snip] --> typedef enum H5T_order_t { H5T_ORDER_ERROR = -1, /**< error */ H5T_ORDER_LE = 0, /**< little endian */ @@ -60,12 +60,12 @@ typedef enum H5T_order_t { H5T_ORDER_NONE = 4 /**< no particular order (strings, bits,..) */ /*H5T_ORDER_NONE must be last */ } H5T_order_t; -//! [H5T_order_t_snip] +//! <!-- [H5T_order_t_snip] --> /** * Types of integer sign schemes */ -//! [H5T_sign_t_snip] +//! <!-- [H5T_sign_t_snip] --> typedef enum H5T_sign_t { H5T_SGN_ERROR = -1, /**< error */ H5T_SGN_NONE = 0, /**< this is an unsigned type */ @@ -73,12 +73,12 @@ typedef enum H5T_sign_t { H5T_NSGN = 2 /** sentinel: this must be last! */ } H5T_sign_t; -//! [H5T_sign_t_snip] +//! <!-- [H5T_sign_t_snip] --> /** * Floating-point normalization schemes */ -//! [H5T_norm_t_snip] +//! <!-- [H5T_norm_t_snip] --> typedef enum H5T_norm_t { H5T_NORM_ERROR = -1, /**< error */ H5T_NORM_IMPLIED = 0, /**< msb of mantissa isn't stored, always 1 */ @@ -86,7 +86,7 @@ typedef enum H5T_norm_t { H5T_NORM_NONE = 2 /**< not normalized */ /*H5T_NORM_NONE must be last */ } H5T_norm_t; -//! [H5T_norm_t_snip] +//! <!-- [H5T_norm_t_snip] --> /** * Character set to use for text strings. @@ -141,7 +141,7 @@ typedef enum H5T_str_t { /** * Type of padding to use in other atomic types */ -//! [H5T_pad_t_snip] +//! <!-- [H5T_pad_t_snip] --> typedef enum H5T_pad_t { H5T_PAD_ERROR = -1, /**< error */ H5T_PAD_ZERO = 0, /**< always set to zero */ @@ -150,7 +150,7 @@ typedef enum H5T_pad_t { H5T_NPAD = 3 /**< sentinal: THIS MUST BE LAST */ } H5T_pad_t; -//! [H5T_pad_t_snip] +//! <!-- [H5T_pad_t_snip] --> /** * Commands sent to conversion functions @@ -173,14 +173,14 @@ typedef enum H5T_bkg_t { /** * Type conversion client data */ -//! [H5T_cdata_t_snip] +//! <!-- [H5T_cdata_t_snip] --> typedef struct H5T_cdata_t { H5T_cmd_t command; /**< what should the conversion function do? */ H5T_bkg_t need_bkg; /**< is the background buffer needed? */ hbool_t recalc; /**< recalculate private data */ void * priv; /**< private data */ } H5T_cdata_t; -//! [H5T_cdata_t_snip] +//! <!-- [H5T_cdata_t_snip] --> /** * Conversion function persistence @@ -194,25 +194,32 @@ typedef enum H5T_pers_t { /** * The order to retrieve atomic native datatype */ -//! [H5T_direction_t_snip] +//! <!-- [H5T_direction_t_snip] --> typedef enum H5T_direction_t { H5T_DIR_DEFAULT = 0, /**< default direction is inscendent */ H5T_DIR_ASCEND = 1, /**< in inscendent order */ H5T_DIR_DESCEND = 2 /**< in descendent order */ } H5T_direction_t; -//! [H5T_direction_t_snip] +//! <!-- [H5T_direction_t_snip] --> /** * The exception type passed into the conversion callback function */ typedef enum H5T_conv_except_t { - H5T_CONV_EXCEPT_RANGE_HI = 0, /**< source value is greater than destination's range */ - H5T_CONV_EXCEPT_RANGE_LOW = 1, /**< source value is less than destination's range */ - H5T_CONV_EXCEPT_PRECISION = 2, /**< source value loses precision in destination */ - H5T_CONV_EXCEPT_TRUNCATE = 3, /**< source value is truncated in destination */ - H5T_CONV_EXCEPT_PINF = 4, /**< source value is positive infinity(floating number) */ - H5T_CONV_EXCEPT_NINF = 5, /**< source value is negative infinity(floating number) */ - H5T_CONV_EXCEPT_NAN = 6 /**< source value is NaN(floating number) */ + H5T_CONV_EXCEPT_RANGE_HI = 0, + /**< Source value is greater than destination's range */ + H5T_CONV_EXCEPT_RANGE_LOW = 1, + /**< Source value is less than destination's range */ + H5T_CONV_EXCEPT_PRECISION = 2, + /**< Source value loses precision in destination */ + H5T_CONV_EXCEPT_TRUNCATE = 3, + /**< Source value is truncated in destination */ + H5T_CONV_EXCEPT_PINF = 4, + /**< Source value is positive infinity */ + H5T_CONV_EXCEPT_NINF = 5, + /**< Source value is negative infinity */ + H5T_CONV_EXCEPT_NAN = 6 + /**< Source value is \c NaN (not a number, including \c QNaN and \c SNaN) */ } H5T_conv_except_t; /** @@ -254,17 +261,31 @@ extern "C" { /** * All datatype conversion functions are... */ -//! [H5T_conv_t_snip] +//! <!-- [H5T_conv_t_snip] --> typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, size_t nelmts, size_t buf_stride, size_t bkg_stride, void *buf, void *bkg, hid_t dset_xfer_plist); -//! [H5T_conv_t_snip] +//! <!-- [H5T_conv_t_snip] --> +//! <!-- [H5T_conv_except_func_t_snip] --> /** - * Exception handler. If an exception like overflow happenes during conversion, - * this function is called if it's registered through H5Pset_type_conv_cb(). + * \brief Exception handler. + * + * \param[in] except_type The kind of exception that occurred + * \param[in] src_id Source datatype identifier + * \param[in] dst_id Destination datatype identifier + * \param[in] src_buf Source data buffer + * \param[in,out] dst_buf Destination data buffer + * \param[in,out] user_data Callback context + * \returns Valid callback function return values are #H5T_CONV_ABORT, + * #H5T_CONV_UNHANDLED and #H5T_CONV_HANDLED. + * + * \details If an exception like overflow happenes during conversion, this + * function is called if it's registered through H5Pset_type_conv_cb(). + * */ typedef H5T_conv_ret_t (*H5T_conv_except_func_t)(H5T_conv_except_t except_type, hid_t src_id, hid_t dst_id, void *src_buf, void *dst_buf, void *user_data); +//! <!-- [H5T_conv_except_func_t_snip] --> /* When this header is included from a private header, don't make calls to H5open() */ #undef H5OPEN @@ -1061,7 +1082,7 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g; * predefined datatype. * * When creating a variable-length string datatype, \p size must - * be #H5T_VARIABLE. + * be #H5T_VARIABLE; see \ref_vlen_strings. * * When creating a fixed-length string datatype, \p size will * be the length of the string in bytes. The length of the @@ -1075,13 +1096,9 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g; * The datatype identifier returned from this function should be * released with H5Tclose or resource leaks will result. * - * \since 1.2.0 - * * \see H5Tclose() * - * \todo Original has a reference to “Creating variable-length string - * datatypes”. - * \todo Create an example for H5Tcreate. + * \since 1.2.0 * */ H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size); @@ -1106,8 +1123,6 @@ H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size); * The returned datatype identifier should be released with H5Tclose() * to prevent resource leak. * - * \todo Create an example for H5Tcopy(). - * */ H5_DLL hid_t H5Tcopy(hid_t type_id); /** @@ -1130,8 +1145,6 @@ H5_DLL herr_t H5Tclose(hid_t type_id); * * \brief Asynchronous version of H5Tclose(). * - * \todo Create an example for H5Tclose_async(). - * */ H5_DLL herr_t H5Tclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t type_id, hid_t es_id); @@ -1222,8 +1235,6 @@ H5_DLL herr_t H5Tcommit2(hid_t loc_id, const char *name, hid_t type_id, hid_t lc * * \brief Asynchronous version of H5Tcommit2(). * - * \todo Create an example for H5Tcommit_async(). - * */ H5_DLL herr_t H5Tcommit_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id, @@ -1257,8 +1268,6 @@ H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id); * * \brief Asynchronous version of H5Topen2(). * - * \todo Create an example for H5Topen_async(). - * */ H5_DLL hid_t H5Topen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t loc_id, const char *name, hid_t tapl_id, hid_t es_id); @@ -1503,8 +1512,6 @@ H5_DLL herr_t H5Trefresh(hid_t type_id); * * \since 1.2.0 * - * \todo Create example for H5Tinsert - * */ H5_DLL herr_t H5Tinsert(hid_t parent_id, const char *name, size_t offset, hid_t member_id); /** @@ -1663,10 +1670,7 @@ H5_DLL herr_t H5Tenum_valueof(hid_t type, const char *name, void *value /*out*/) * character base type creates a variable-length sequence of strings * (a variable-length, 1-dimensional array), with each element of * the array being of the string or character base type.\n - * To create a variable-length string datatype, see "Creating - * variable-length string datatypes." - * - * \todo Fix the reference. + * To create a variable-length string datatype, see \ref_vlen_strings. * */ H5_DLL hid_t H5Tvlen_create(hid_t base_id); @@ -1870,13 +1874,9 @@ H5_DLL htri_t H5Tdetect_class(hid_t type_id, H5T_class_t cls); * actual data and a size value. This function does not return the * size of actual variable-length sequence data. * - * \since 1.2.0 - * * \see H5Tset_size() * - * \todo Original has a reference to “Creating variable-length string datatypes”. - * \todo Create an example for H5Tget_size(). - * + * \since 1.2.0 */ H5_DLL size_t H5Tget_size(hid_t type_id); /** @@ -2090,7 +2090,7 @@ H5_DLL H5T_pad_t H5Tget_inpad(hid_t type_id); */ H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id); /** - * \ingroup COMPOUND + * \ingroup COMPOUND ENUM * * \brief Retrieves the number of elements in a compound or enumeration datatype * @@ -2107,7 +2107,7 @@ H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id); */ H5_DLL int H5Tget_nmembers(hid_t type_id); /** - * \ingroup COMPOUND + * \ingroup COMPOUND ENUM * * \brief Retrieves the name of a compound or enumeration datatype member * @@ -2134,7 +2134,7 @@ H5_DLL int H5Tget_nmembers(hid_t type_id); */ H5_DLL char *H5Tget_member_name(hid_t type_id, unsigned membno); /** - * \ingroup COMPOUND + * \ingroup COMPOUND ENUM * * \brief Retrieves the index of a compound or enumeration datatype member * @@ -2406,6 +2406,7 @@ H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction); * * \li Variable-length string datatypes: If \p dtype_id is a * variable-length string, size must normally be set to #H5T_VARIABLE. + * See \ref_vlen_strings. * * \li Compound datatypes: This function may be used to increase or * decrease the size of a compound datatype, but the function will @@ -2416,12 +2417,9 @@ H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction); * variable-length array datatypes (#H5T_VLEN), or reference datatypes * (#H5T_REFERENCE). * - * \since 1.2.0 - * * \see H5Tget_size() * - *\todo Create an example for H5Tset_size(). - *\todo Original has a reference to “Creating variable-length string datatypes”. + * \since 1.2.0 * */ H5_DLL herr_t H5Tset_size(hid_t type_id, size_t size); @@ -2873,7 +2871,7 @@ H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id); * enough to hold the larger of the input and output data. * * \version 1.6.3 \p nelmts parameter type changed to size_t. - * \version 1.4.0 \p nelmts parameter type changed to \ref hsize_t. + * \version 1.4.0 \p nelmts parameter type changed to hsize_t. * */ H5_DLL herr_t H5Tconvert(hid_t src_id, hid_t dst_id, size_t nelmts, void *buf, void *background, diff --git a/src/H5VLconnector.h b/src/H5VLconnector.h index ac40e70..2a8ef6e 100644 --- a/src/H5VLconnector.h +++ b/src/H5VLconnector.h @@ -458,7 +458,7 @@ typedef struct H5VL_token_class_t { * \ingroup H5VLDEV * Class information for each VOL connector */ -//! [H5VL_class_t_snip] +//! <!-- [H5VL_class_t_snip] --> typedef struct H5VL_class_t { /* Overall connector fields & callbacks */ unsigned version; /**< VOL connector class struct version # */ @@ -492,7 +492,7 @@ typedef struct H5VL_class_t { herr_t (*optional)(void *obj, int op_type, hid_t dxpl_id, void **req, va_list arguments); /**< Optional callback */ } H5VL_class_t; -//! [H5VL_class_t_snip] +//! <!-- [H5VL_class_t_snip] --> /********************/ /* Public Variables */ @@ -529,15 +529,14 @@ extern "C" { * uncommon, as most VOL-specific properties are added to the file * access property list via the connector's API calls which set the * VOL connector for the file open/create. For more information, see - * the VOL documentation. + * the \ref_vol_doc. * * H5VL_class_t is defined in H5VLconnector.h in the source code. It * contains class information for each VOL connector: * \snippet this H5VL_class_t_snip * - * \todo Fix the reference to VOL documentation. - * * \since 1.12.0 + * */ H5_DLL hid_t H5VLregister_connector(const H5VL_class_t *cls, hid_t vipl_id); /** diff --git a/src/H5VLmodule.h b/src/H5VLmodule.h index 78c5986..009c0e5 100644 --- a/src/H5VLmodule.h +++ b/src/H5VLmodule.h @@ -32,6 +32,10 @@ * \brief Virtual Object Layer Interface * \todo Describe concisely what the functions in this module are about. * + * \defgroup ASYNC Asynchronous Functions + * \brief Asynchronous Functions + * \todo Describe concisely what the functions in this module are about. + * * \defgroup H5VLDEF Definitions * \ingroup H5VL * \defgroup H5VLDEV VOL Developer diff --git a/src/H5VLpublic.h b/src/H5VLpublic.h index ce50653..c5f85dc 100644 --- a/src/H5VLpublic.h +++ b/src/H5VLpublic.h @@ -93,9 +93,9 @@ * connectors. Subsequent values should be obtained from the HDF5 * development team at mailto:help@hdfgroup.org. */ -//! [H5VL_class_value_t_snip] +//! <!-- [H5VL_class_value_t_snip] --> typedef int H5VL_class_value_t; -//! [H5VL_class_value_t_snip] +//! <!-- [H5VL_class_value_t_snip] --> /** * \ingroup H5VLDEF @@ -153,11 +153,10 @@ extern "C" { * uncommon, as most VOL-specific properties are added to the file * access property list via the connector's API calls which set the * VOL connector for the file open/create. For more information, see - * the VOL documentation. - * - * \todo Fix the reference to VOL documentation. + * \ref_vol_doc. * * \since 1.12.0 + * */ H5_DLL hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vipl_id); /** @@ -192,11 +191,10 @@ H5_DLL hid_t H5VLregister_connector_by_name(const char *connector_name, hid_t vi * uncommon, as most VOL-specific properties are added to the file * access property list via the connector's API calls which set the * VOL connector for the file open/create. For more information, see - * the VOL documentation. - * - * \todo Fix the reference to VOL documentation. + * the \ref_vol_doc. * * \since 1.12.0 + * */ H5_DLL hid_t H5VLregister_connector_by_value(H5VL_class_value_t connector_value, hid_t vipl_id); /** diff --git a/src/H5Zmodule.h b/src/H5Zmodule.h index 25007b3..76a2380 100644 --- a/src/H5Zmodule.h +++ b/src/H5Zmodule.h @@ -77,11 +77,9 @@ * Custom filters that have been registered with the library will have * additional unique identifiers. * - * See \Emph{HDF5 Dynamically Loaded Filters} for more information on - * how an HDF5 application can apply a filter that is not registered - * with the HDF5 library. - * - * \todo Fix the reference. + * See \ref_dld_filters for more information on how an HDF5 + * application can apply a filter that is not registered with the HDF5 + * library. * * \defgroup H5ZPRE Predefined Filters * \ingroup H5Z diff --git a/src/H5Zpublic.h b/src/H5Zpublic.h index 4c9b006..90277cf 100644 --- a/src/H5Zpublic.h +++ b/src/H5Zpublic.h @@ -230,16 +230,18 @@ typedef enum H5Z_EDC_t { * Return values for filter callback function */ typedef enum H5Z_cb_return_t { - H5Z_CB_ERROR = -1, - H5Z_CB_FAIL = 0, /**< I/O should fail if filter fails. */ - H5Z_CB_CONT = 1, /**< I/O continues if filter fails. */ - H5Z_CB_NO = 2 + H5Z_CB_ERROR = -1, /**< error value */ + H5Z_CB_FAIL = 0, /**< I/O should fail if filter fails. */ + H5Z_CB_CONT = 1, /**< I/O continues if filter fails. */ + H5Z_CB_NO = 2 /**< sentinel */ } H5Z_cb_return_t; +//! <!-- [H5Z_filter_func_t_snip] --> /** * Filter callback function definition */ typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void *buf, size_t buf_size, void *op_data); +//! <!-- [H5Z_filter_func_t_snip] --> /** * Structure for filter callback property @@ -254,58 +256,93 @@ extern "C" { #endif /** - * \details Before a dataset gets created, the \c can_apply callbacks for any - * filters used in the dataset creation property list are called with - * the dataset's dataset creation property list, the dataset's - * datatype and a dataspace describing a chunk (for chunked dataset - * storage). + * \brief This callback determines if a filter can be applied to the dataset + * with the characteristics provided * - * The \c can_apply callback must determine if the combination of the - * dataset creation property list setting, the datatype and the - * dataspace represent a valid combination to apply this filter to. - * For example, some cases of invalid combinations may involve the - * filter not operating correctly on certain datatypes (or certain - * datatype sizes), or certain sizes of the chunk dataspace. + * \dcpl_id + * \type_id + * \space_id * - * The \c can_apply callback can be the NULL pointer, in which case, - * the library will assume that it can apply to any combination of - * dataset creation property list values, datatypes and dataspaces. + * \return \htri_t * - * The \c can_apply callback returns positive a valid combination, - * zero for an invalid combination and negative for an error. - */ -//! [H5Z_can_apply_func_t_snip] + * \details Before a dataset gets created, the \ref H5Z_can_apply_func_t + * callbacks for any filters used in the dataset creation property list + * are called with the dataset's dataset creation property list, the + * dataset's datatype and a dataspace describing a chunk (for chunked + * dataset storage). + * + * The \ref H5Z_can_apply_func_t callback must determine if the + * combination of the dataset creation property list setting, the + * datatype and the dataspace represent a valid combination to apply + * this filter to. For example, some cases of invalid combinations may + * involve the filter not operating correctly on certain datatypes (or + * certain datatype sizes), or certain sizes of the chunk dataspace. + * + * The \ref H5Z_can_apply_func_t callback can be the NULL pointer, in + * which case, the library will assume that it can apply to any + * combination of dataset creation property list values, datatypes and + * dataspaces. + * + * The \ref H5Z_can_apply_func_t callback returns positive a valid + * combination, zero for an invalid combination and negative for an + * error. + */ +//! <!-- [H5Z_can_apply_func_t_snip] --> typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); -//! [H5Z_can_apply_func_t_snip] -/** - * \details After the "can_apply" callbacks are checked for new datasets, the - * \c set_local callbacks for any filters used in the dataset creation - * property list are called. These callbacks receive the dataset's - * private copy of the dataset creation property list passed in to - * H5Dcreate() (i.e. not the actual property list passed in to - * H5Dcreate()) and the datatype ID passed in to H5Dcreate() (which is - * not copied and should not be modified) and a dataspace describing - * the chunk (for chunked dataset storage) (which should also not be - * modified). - * - * The \c set_local callback must set any parameters that are specific - * to this dataset, based on the combination of the dataset creation - * property list values, the datatype and the dataspace. For example, - * some filters perform different actions based on different datatypes - * (or datatype sizes) or different number of dimensions or dataspace - * sizes. +//! <!-- [H5Z_can_apply_func_t_snip] --> +/** + * \brief The filter operation callback function, defining a filter's operation + * on data * - * The \c set_local callback can be the NULL pointer, in which case, - * the library will assume that there are no dataset-specific settings - * for this filter. + * \dcpl_id + * \type_id + * \space_id * - * The \c set_local callback must return non-negative on success and - * negative for an error. - */ -//! [H5Z_set_local_func_t_snip] + * \return \herr_t + * + * \details After the \ref H5Z_can_apply_func_t callbacks are checked for new + * datasets, the \ref H5Z_set_local_func_t callbacks for any filters + * used in the dataset creation property list are called. These + * callbacks receive the dataset's private copy of the dataset creation + * property list passed in to H5Dcreate() (i.e. not the actual property + * list passed in to H5Dcreate()) and the datatype ID passed in to + * H5Dcreate() (which is not copied and should not be modified) and a + * dataspace describing the chunk (for chunked dataset storage) (which + * should also not be modified). + * + * The \ref H5Z_set_local_func_t callback must set any parameters that + * are specific to this dataset, based on the combination of the + * dataset creation property list values, the datatype and the + * dataspace. For example, some filters perform different actions based + * on different datatypes (or datatype sizes) or different number of + * dimensions or dataspace sizes. + * + * The \ref H5Z_set_local_func_t callback can be the NULL pointer, in + * which case, the library will assume that there are no + * dataset-specific settings for this filter. + * + * The \ref H5Z_set_local_func_t callback must return non-negative on + * success and negative for an error. + */ +//! <!-- [H5Z_set_local_func_t_snip] --> typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); -//! [H5Z_set_local_func_t_snip] +//! <!-- [H5Z_set_local_func_t_snip] --> + /** + * \brief The filter operation callback function, defining a filter's operation + * on data + * + * \param[in] flags Bit vector specifying certain general properties of the filter + * \param[in] cd_nelmts Number of elements in \p cd_values + * \param[in] cd_values Auxiliary data for the filter + * \param[in] nbytes The number of valid bytes in \p buf to be filtered + * \param[in,out] buf_size The size of \p buf + * \param[in,out] buf The filter buffer + * + * \return Returns the number of valid bytes of data contained in \p buf. In the + * case of failure, the return value is 0 (zero) and all pointer + * arguments are left unchanged. + * * \details A filter gets definition flags and invocation flags (defined * above), the client data array and size defined when the filter was * added to the pipeline, the size in bytes of the data on which to @@ -321,15 +358,15 @@ typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space * output buffer. If an error occurs then the function should return * zero and leave all pointer arguments unchanged. */ -//! [H5Z_func_t_snip] +//! <!-- [H5Z_func_t_snip] --> typedef size_t (*H5Z_func_t)(unsigned int flags, size_t cd_nelmts, const unsigned int cd_values[], size_t nbytes, size_t *buf_size, void **buf); -//! [H5Z_func_t_snip] +//! <!-- [H5Z_func_t_snip] --> /** * The filter table maps filter identification numbers to structs that * contain a pointers to the filter function and timing statistics. */ -//! [H5Z_class2_t_snip] +//! <!-- [H5Z_class2_t_snip] --> typedef struct H5Z_class2_t { int version; /**< Version number of the H5Z_class_t struct */ H5Z_filter_t id; /**< Filter ID number */ @@ -340,7 +377,7 @@ typedef struct H5Z_class2_t { H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter */ H5Z_func_t filter; /**< The actual filter function */ } H5Z_class2_t; -//! [H5Z_class2_t_snip] +//! <!-- [H5Z_class2_t_snip] --> /** * \ingroup H5Z @@ -635,7 +672,7 @@ H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_confi * The filter table maps filter identification numbers to structs that * contain a pointers to the filter function and timing statistics. */ -//! [H5Z_class1_t_snip] +//! <!-- [H5Z_class1_t_snip] --> typedef struct H5Z_class1_t { H5Z_filter_t id; /**< Filter ID number */ const char * name; /**< Comment for debugging */ @@ -643,7 +680,7 @@ typedef struct H5Z_class1_t { H5Z_set_local_func_t set_local; /**< The "set local" callback for a filter */ H5Z_func_t filter; /**< The actual filter function */ } H5Z_class1_t; -//! [H5Z_class1_t_snip] +//! <!-- [H5Z_class1_t_snip] --> #endif /* H5_NO_DEPRECATED_SYMBOLS */ diff --git a/src/H5public.h b/src/H5public.h index b319550..751abbe 100644 --- a/src/H5public.h +++ b/src/H5public.h @@ -95,50 +95,130 @@ extern "C" { #define H5_NO_EXPAND(x) (x) /* Version numbers */ -#define H5_VERS_MAJOR 1 /* For major interface/format changes */ -#define H5_VERS_MINOR 13 /* For minor interface/format changes */ -#define H5_VERS_RELEASE 0 /* For tweaks, bug-fixes, or development */ -#define H5_VERS_SUBRELEASE "" /* For pre-releases like snap0 */ -/* Empty string for real releases. */ -#define H5_VERS_INFO "HDF5 library version: 1.13.0" /* Full version string */ +/** + * For major interface/format changes + */ +#define H5_VERS_MAJOR 1 +/** + * For minor interface/format changes + */ +#define H5_VERS_MINOR 13 +/** + * For tweaks, bug-fixes, or development + */ +#define H5_VERS_RELEASE 0 +/** + * For pre-releases like \c snap0. Empty string for official releases. + */ +#define H5_VERS_SUBRELEASE "" +/** + * Full version string + */ +#define H5_VERS_INFO "HDF5 library version: 1.13.0" #define H5check() H5check_version(H5_VERS_MAJOR, H5_VERS_MINOR, H5_VERS_RELEASE) /* macros for comparing the version */ +/** + * \brief Determines whether the version of the library being used is greater + * than or equal to the specified version + * + * \param[in] Maj Major version number - A non-negative integer value + * \param[in] Min Minor version number - A non-negative integer value + * \param[in] Rel Release version number - A non-negative integer value + * \returns A value of 1 is returned if the library version is greater than + * or equal to the version number specified.\n + * A value of 0 is returned if the library version is less than the + * version number specified.\n + * A library version is greater than the specified version number if + * its major version is larger than the specified major version + * number. If the major version numbers are the same, it is greater + * than the specified version number if its minor version is larger + * than the specified minor version number. If the minor version + * numbers are the same, then a library version would be greater than + * the specified version number if its release number is larger than + * the specified release number. + * + * \details The #H5_VERSION_GE and #H5_VERSION_LE macros are used at compile + * time to conditionally include or exclude code based on the version + * of the HDF5 library against which an application will be linked. + * + * The #H5_VERSION_GE macro compares the version of the HDF5 library + * being used against the version number specified in the parameters. + * + * For more information about release versioning, see \ref_h5lib_relver. + * + * \since 1.8.7 + * + */ #define H5_VERSION_GE(Maj, Min, Rel) \ (((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR == Min) && (H5_VERS_RELEASE >= Rel)) || \ ((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR > Min)) || (H5_VERS_MAJOR > Maj)) +/** + * \brief Determines whether the version of the library being used is less + * than or equal to the specified version + * + * \param[in] Maj Major version number - A non-negative integer value + * \param[in] Min Minor version number - A non-negative integer value + * \param[in] Rel Release version number - A non-negative integer value + * \returns A value of 1 is returned if the library version is less than + * or equal to the version number specified.\n + * A value of 0 is returned if the library version is greater than the + * version number specified.\n + * A library version is less than the specified version number if + * its major version is smaller than the specified major version + * number. If the major version numbers are the same, it is smaller + * than the specified version number if its minor version is smaller + * than the specified minor version number. If the minor version + * numbers are the same, then a library version would be smaller than + * the specified version number if its release number is smaller than + * the specified release number. + * + * \details The #H5_VERSION_GE and #H5_VERSION_LE macros are used at compile + * time to conditionally include or exclude code based on the version + * of the HDF5 library against which an application will be linked. + * + * The #H5_VERSION_LE macro compares the version of the HDF5 library + * being used against the version number specified in the parameters. + * + * For more information about release versioning, see \ref_h5lib_relver. + * + * \since 1.8.7 + * + */ #define H5_VERSION_LE(Maj, Min, Rel) \ (((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR == Min) && (H5_VERS_RELEASE <= Rel)) || \ ((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR < Min)) || (H5_VERS_MAJOR < Maj)) -/* +/** * Status return values. Failed integer functions in HDF5 result almost * always in a negative value (unsigned failing functions sometimes return * zero for failure) while successful return is non-negative (often zero). * The negative failure value is most commonly -1, but don't bet on it. The * proper way to detect failure is something like: - * - * if((dset = H5Dopen2(file, name)) < 0) - * fprintf(stderr, "unable to open the requested dataset\n"); + * \code + * if((dset = H5Dopen2(file, name)) < 0) + * fprintf(stderr, "unable to open the requested dataset\n"); + * \endcode */ typedef int herr_t; -/* +/** * Boolean type. Successful return values are zero (false) or positive * (true). The typical true value is 1 but don't bet on it. Boolean - * functions cannot fail. Functions that return `htri_t' however return zero + * functions cannot fail. Functions that return #htri_t however return zero * (false), positive (true), or negative (failure). The proper way to test - * for truth from a htri_t function is: - * - * if ((retval = H5Tcommitted(type)) > 0) { - * printf("data type is committed\n"); - * } else if (!retval) { - * printf("data type is not committed\n"); - * } else { - * printf("error determining whether data type is committed\n"); - * } + * for truth from a #htri_t function is: + * \code + * if ((retval = H5Tcommitted(type)) > 0) { + * printf("data type is committed\n"); + * } else if (!retval) { + * printf("data type is not committed\n"); + * } else { + * printf("error determining whether data type is committed\n"); + * } + * \endcode */ #ifdef H5_HAVE_STDBOOL_H #include <stdbool.h> @@ -307,8 +387,7 @@ typedef unsigned long uint32_t; #error "nothing appropriate for uint32_t" #endif -//! [H5_iter_order_t_snip] - +//! <!-- [H5_iter_order_t_snip] --> /** * Common iteration orders */ @@ -319,8 +398,7 @@ typedef enum { H5_ITER_NATIVE, /**< No particular order, whatever is fastest */ H5_ITER_N /**< Number of iteration orders */ } H5_iter_order_t; - -//! [H5_iter_order_t_snip] +//! <!-- [H5_iter_order_t_snip] --> /* Iteration callback values */ /* (Actually, any positive value will cause the iterator to stop and pass back @@ -330,8 +408,7 @@ typedef enum { #define H5_ITER_CONT (0) #define H5_ITER_STOP (1) -//! [H5_index_t_snip] - +//! <!-- [H5_index_t_snip] --> /** * The types of indices on links in groups/attributes on objects. * Primarily used for "<do> <foo> by index" routines and for iterating over @@ -343,18 +420,17 @@ typedef enum H5_index_t { H5_INDEX_CRT_ORDER, /**< Index on creation order */ H5_INDEX_N /**< Number of indices defined */ } H5_index_t; - -//! [H5_index_t_snip] +//! <!-- [H5_index_t_snip] --> /** * Storage info struct used by H5O_info_t and H5F_info_t */ -//! [H5_ih_info_t_snip] +//! <!-- [H5_ih_info_t_snip] --> typedef struct H5_ih_info_t { hsize_t index_size; /**< btree and/or list */ hsize_t heap_size; } H5_ih_info_t; -//! [H5_ih_info_t_snip] +//! <!-- [H5_ih_info_t_snip] --> /** * The maximum size allowed for tokens @@ -364,17 +440,17 @@ typedef struct H5_ih_info_t { */ #define H5O_MAX_TOKEN_SIZE (16) -//! [H5O_token_t_snip] - +//! <!-- [H5O_token_t_snip] --> /** + * Type for object tokens + * * \internal (Hoisted here, since it's used by both the - * H5Lpublic.h and H5Opublic.h headers) */ -/* Type for object tokens */ + * H5Lpublic.h and H5Opublic.h headers) + */ typedef struct H5O_token_t { uint8_t __data[H5O_MAX_TOKEN_SIZE]; } H5O_token_t; - -//! [H5O_token_t_snip] +//! <!-- [H5O_token_t_snip] --> /** * Allocation statistics info struct |