diff --git a/libs/windows/bin/hdf5.dll b/libs/windows/bin/hdf5.dll index 0f3ca28..1454db8 100644 Binary files a/libs/windows/bin/hdf5.dll and b/libs/windows/bin/hdf5.dll differ diff --git a/libs/windows/bin/hdf5_cpp.dll b/libs/windows/bin/hdf5_cpp.dll index a42f707..1d646eb 100644 Binary files a/libs/windows/bin/hdf5_cpp.dll and b/libs/windows/bin/hdf5_cpp.dll differ diff --git a/libs/windows/include/H5ACpublic.h b/libs/windows/include/H5ACpublic.h index f8f4f28..71292b6 100644 --- a/libs/windows/include/H5ACpublic.h +++ b/libs/windows/include/H5ACpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -14,23 +13,16 @@ /*------------------------------------------------------------------------- * * Created: H5ACpublic.h - * Jul 10 1997 - * Robb Matzke * - * Purpose: Public include file for cache functions. + * Purpose: Public include file for cache functions * *------------------------------------------------------------------------- */ #ifndef H5ACpublic_H #define H5ACpublic_H -/* Public headers needed by this file */ -#include "H5public.h" -#include "H5Cpublic.h" - -#ifdef __cplusplus -extern "C" { -#endif +#include "H5public.h" /* Generic Functions */ +#include "H5Cpublic.h" /* Cache */ /**************************************************************************** * @@ -76,15 +68,15 @@ extern "C" { * * *** DEPRECATED *** Use H5Fstart/stop logging functions instead * - * The trace file is a debuging feature that allow the capture of + * The trace file is a debugging feature that allow the capture of * top level metadata cache requests for purposes of debugging and/or - * optimization. This field should normally be set to FALSE, as + * optimization. This field should normally be set to false, as * trace file collection imposes considerable overhead. * - * This field should only be set to TRUE when the trace_file_name + * This field should only be set to true when the 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 close_trace_file - * field is also TRUE. + * field is also true. * * close_trace_file: Boolean field indicating whether the current trace * file (if any) should be closed. @@ -92,11 +84,11 @@ extern "C" { * *** DEPRECATED *** Use H5Fstart/stop logging functions instead * * See the above comments on the open_trace_file field. This field - * should be set to FALSE unless there is an open trace file on the + * should be set to false unless there is an open trace file on the * cache that you wish to close. * * trace_file_name: Full path of the trace file to be opened if the - * open_trace_file field is TRUE. + * open_trace_file field is true. * * *** DEPRECATED *** Use H5Fstart/stop logging functions instead * @@ -123,12 +115,12 @@ extern "C" { * H5C_incr__off ) && ( decr_mode == H5C_decr__off )). There * is no logical reason why this should be so, but it simplifies * implementation and testing, and I can't think of any reason - * why it would be desireable. If you can think of one, I'll + * why it would be desirable. If you can think of one, I'll * revisit the issue. * * set_initial_size: Boolean flag indicating whether the size of the * initial size of the cache is to be set to the value given in - * the initial_size field. If set_initial_size is FALSE, the + * the initial_size field. If set_initial_size is false, the * initial_size field is ignored. * * initial_size: If enabled, this field contain the size the cache is @@ -396,7 +388,7 @@ extern "C" { * * When the sync point is reached (or when there is a user generated * flush), process zero flushes sufficient entries to bring it into - * complience with its min clean size (or flushes all dirty entries in + * compliance with its min clean size (or flushes all dirty entries in * the case of a user generated flush), broad casts the list of * entries just cleaned to all the other processes, and then exits * the sync point. @@ -471,7 +463,7 @@ typedef struct H5AC_cache_config_t { /* general configuration fields: */ //! int version; - /**< Integer field indicating the the version of the H5AC_cache_config_t + /**< Integer field indicating 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). */ @@ -567,7 +559,7 @@ typedef struct H5AC_cache_config_t { * 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 -- HDF5 User’s Guide + * “Metadata Caching in HDF5” section of the -- \ref UG * for details. */ size_t max_size; @@ -576,7 +568,7 @@ typedef struct H5AC_cache_config_t { 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. */ + * adaptive cache resize code can select as the minimum cache * size. */ long int epoch_length; /**< Number of cache accesses between runs of the adaptive cache resize @@ -708,13 +700,13 @@ typedef struct H5AC_cache_config_t { * 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, + * must be consistent 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 + * are:\n #H5AC_METADATA_WRITE_STRATEGY__PROCESS_0_ONLY: Specifies the 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 @@ -764,7 +756,7 @@ typedef struct H5AC_cache_image_config_t { * 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 + * imposed on number of times a prefetched entry can appear in subsequent * cache images. * * A value of 0 prevents prefetched entries from being included in cache @@ -783,7 +775,4 @@ typedef struct H5AC_cache_image_config_t { //! -#ifdef __cplusplus -} -#endif #endif diff --git a/libs/windows/include/H5AbstractDs.h b/libs/windows/include/H5AbstractDs.h index b84867b..49bcfeb 100644 --- a/libs/windows/include/H5AbstractDs.h +++ b/libs/windows/include/H5AbstractDs.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * diff --git a/libs/windows/include/H5Alltypes.h b/libs/windows/include/H5Alltypes.h index 7a14774..b18add8 100644 --- a/libs/windows/include/H5Alltypes.h +++ b/libs/windows/include/H5Alltypes.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * diff --git a/libs/windows/include/H5Apublic.h b/libs/windows/include/H5Apublic.h index 0198668..232ae0a 100644 --- a/libs/windows/include/H5Apublic.h +++ b/libs/windows/include/H5Apublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -17,10 +16,10 @@ #ifndef H5Apublic_H #define H5Apublic_H -/* Public headers needed by this file */ -#include "H5Ipublic.h" /* IDs */ -#include "H5Opublic.h" /* Object Headers */ -#include "H5Tpublic.h" /* Datatypes */ +#include "H5public.h" /* Generic Functions */ +#include "H5Ipublic.h" /* Identifiers */ +#include "H5Opublic.h" /* Object Headers */ +#include "H5Tpublic.h" /* Datatypes */ //! /** @@ -40,8 +39,8 @@ typedef struct { * \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 + * \param[in] ainfo The attribute's info struct + * \param[in,out] op_data A pointer to the operator data passed into * H5Aiterate2() or H5Aiterate_by_name() * \returns The return values from an operator are: * \li Zero causes the iterator to continue, returning zero when @@ -78,17 +77,28 @@ extern "C" { * * \return \herr_t * - * \details H5Aclose() terminates access to the attribute specified by - * \p attr_id by releasing the identifier. + * \details H5Aclose() terminates access to the attribute through + * \p attr_id and releases the identifier. * - * \attention Further use of a released attribute identifier is illegal; a - * function using such an identifier will generate an error. + * \par Example + * \snippet H5A_examples.c create * * \since 1.0.0 * * \see H5Acreate(), H5Aopen() */ H5_DLL herr_t H5Aclose(hid_t attr_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Aclose} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Aclose_async(hid_t attr_id, hid_t es_id); +#endif /* --------------------------------------------------------------------------*/ /** * \ingroup H5A @@ -110,26 +120,18 @@ H5_DLL herr_t H5Aclose(hid_t attr_id); * The attribute name, \p attr_name, must be unique for the object. * * The attribute is created with the specified datatype and dataspace, - * \p type_id and \p space_id, which are created with the H5T and - * H5S interfaces, respectively. + * \p type_id and \p space_id. * - * If \p type_id is either a fixed-length or variable-length string, - * it is important to set the string length when defining the - * datatype. String datatypes are derived from #H5T_C_S1 (or - * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in - * size. See H5Tset_size() and Creating variable-length string - * datatypes. - * - * The access property list is currently unused, but will be used in - * the future. This property list should currently be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * The attribute identifier returned by this function must be released - * with H5Aclose() resource leaks will develop. + * with H5Aclose() or resource leaks will develop. * - * \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 to + * that file's root group. * - * \note If \p loc_id is a file identifier, the attribute will be attached - * that file’s root group. + * \par Example + * \snippet H5A_examples.c create * * \since 1.8.0 * @@ -138,6 +140,20 @@ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Acreate_async(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); +#endif + /*--------------------------------------------------------------------------*/ /** * \ingroup H5A @@ -160,33 +176,40 @@ H5_DLL hid_t H5Acreate2(hid_t loc_id, const char *attr_name, hid_t type_id, hid_ * attached to the object specified by \p loc_id and \p obj_name. * * \p loc_id is a location identifier; \p obj_name is the object - * name relative to \p loc_id. If \p loc_id fully specifies the - * object to which the attribute is to be attached, \p obj_name - * should be '.' (a dot). + * name relative to \p loc_id. * * The attribute name, \p attr_name, must be unique for the object. * * The attribute is created with the specified datatype and - * dataspace, \p type_id and \p space_id, which are created with - * the H5T and H5S interfaces respectively. + * dataspace, \p type_id and \p space_id. * - * The attribute creation and access property lists are currently - * unused, but will be used in the future for optional attribute - * creation and access properties. These property lists should - * currently be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access * the object, \p obj_name. * - * The attribute identifier returned by this function must be - * released with H5close() or resource leaks will develop. - * * \since 1.8.0 * */ H5_DLL hid_t H5Acreate_by_name(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); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Acreate_by_name} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Acreate_by_name_async(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); +#endif + /*-------------------------------------------------------------------------*/ /** * \ingroup H5A @@ -200,10 +223,14 @@ H5_DLL hid_t H5Acreate_by_name(hid_t loc_id, const char *obj_name, const char *a * * \details H5Adelete() removes the attribute specified by its name, * \p attr_name, from a file, dataset, group, or named datatype. - * This function should not be used when attribute identifiers - * are open on \p loc_id as it may cause the internal indexes of - * the attributes to change and future writes to the open - * attributes to produce incorrect results. + * + * \attention This function should not be used when other attribute identifiers + * are open on \p loc_id. This may cause the internal indexes of + * the attributes to change and future writes to the open + * attributes to produce incorrect results. + * + * \par Example + * \snippet H5A_examples.c delete * * \since 1.0.0 * @@ -219,38 +246,27 @@ H5_DLL herr_t H5Adelete(hid_t loc_id, const char *attr_name); * \param[in] obj_name Name of object, relative to location, from which * attribute is to be removed * \param[in] idx_type Type of index - * \param[in] order Order in which to iterate over index - * \param[in] n Offset within index + * \param[in] order Order in which to iterate over the index + * \param[in] n Offset within the index * \lapl_id * * \return \herr_t * - * \details H5Adelete_by_idx() removes an attribute, specified by its + * \details H5Adelete_by_idx() removes an attribute specified by its * location in an index, from an object. * * The object from which the attribute is to be removed is * specified by a location identifier and name, \p loc_id and - * \p obj_name, respectively. If \p loc_id fully specifies the - * object from which the attribute is to be removed, \p obj_name - * should be '.' (a dot). + * \p obj_name, respectively. * * The attribute to be removed is specified by a position in an - * index, \p n. The type of index is specified by \p idx_type and - * may be #H5_INDEX_NAME, for an alpha-numeric index by name, or - * #H5_INDEX_CRT_ORDER, for an index by creation order. The order - * in which the index is to be traversed is specified by \p order - * and may be #H5_ITER_INC (increment) for top-down iteration, - * #H5_ITER_DEC (decrement) for bottom-up iteration, or - * #H5_ITER_NATIVE, in which case HDF5 will iterate in the - * fastest-available order. For example, if \p idx_type, \p order, + * index, \p n. The type of index is specified by \p idx_type. + * The order in which the index is to be traversed is specified by + * \p order. For example, if \p idx_type, \p order, * and \p n are set to #H5_INDEX_NAME, #H5_ITER_INC, and 5, - * respectively, the fifth attribute by alpha-numeric order of + * respectively, the fifth attribute in the lexicographic order of * attribute names will be removed. * - * For a discussion of \p idx_type and \p order, the valid values - * of those parameters, and the use of \p n, see the description - * of H5Aiterate2(). - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access * the object, \p obj_name. @@ -278,9 +294,6 @@ H5_DLL herr_t H5Adelete_by_idx(hid_t loc_id, const char *obj_name, H5_index_t id * from an object specified by location and name, \p loc_id and * \p obj_name, respectively. * - * If \p loc_id fully specifies the object from which the - * attribute is to be removed, \p obj_name should be '.' (a dot). - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to * access the object, \p obj_name. @@ -308,6 +321,18 @@ H5_DLL herr_t H5Adelete_by_name(hid_t loc_id, const char *obj_name, const char * * */ H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Aexists} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Aexists_async(hid_t obj_id, const char *attr_name, hbool_t *exists, hid_t es_id); +#endif + /*-------------------------------------------------------------------------*/ /** * \ingroup H5A @@ -329,9 +354,7 @@ H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name); * \p loc_id specifies a location in the file containing the object. * \p obj_name is the name of the object to which the attribute is * attached and can be a relative name, relative to \p loc_id, - * or an absolute name, based in the root group of the file. If - * \p loc_id fully specifies the object, \p obj_name should be '.' - * (a dot). + * or an absolute name, based on the root group of the file. * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -341,6 +364,20 @@ H5_DLL htri_t H5Aexists(hid_t obj_id, const char *attr_name); * */ H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char *attr_name, hid_t lapl_id); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Aexists_by_name} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Aexists_by_name_async(hid_t loc_id, const char *obj_name, const char *attr_name, + hbool_t *exists, hid_t lapl_id, hid_t es_id); +#endif + /*-------------------------------------------------------------------------*/ /** * \ingroup H5A @@ -356,7 +393,7 @@ H5_DLL htri_t H5Aexists_by_name(hid_t obj_id, const char *obj_name, const char * * by \p attr_id. * * The creation property list identifier should be released with - * H5Pclose(). + * H5Pclose() to prevent resource leaks. * * \since 1.8.0 * @@ -366,7 +403,7 @@ H5_DLL hid_t H5Aget_create_plist(hid_t attr_id); /** * \ingroup H5A * - * \brief Retrieves attribute information, by attribute identifier + * \brief Retrieves attribute information by attribute identifier * * \attr_id * \param[out] ainfo Attribute information struct @@ -374,32 +411,9 @@ H5_DLL hid_t H5Aget_create_plist(hid_t attr_id); * \return \herr_t * * \details H5Aget_info() retrieves attribute information, locating the - * attribute with an attribute identifier, \p attr_id, which is - * the identifier returned by H5Aopen() or H5Aopen_by_idx(). The + * attribute with an attribute identifier, \p attr_id. The * attribute information is returned in the \p ainfo struct. * - * The \p ainfo struct is defined as follows: - * \snippet this H5A_info_t_snip - * - * \p corder_valid indicates whether the creation order data is - * valid for this attribute. Note that if creation order is not - * being tracked, no creation order data will be valid. Valid - * values are \c TRUE and \c FALSE. - * - * \p corder is a positive integer containing the creation - * order of the attribute. This value is 0-based, so, for - * example, the third attribute created will have a \p corder - * value of 2. - * - * \p cset indicates the character set used for the attribute’s - * name; valid values are defined in H5Tpublic.h and include - * the following: - * \csets - * This value is set with H5Pset_char_encoding(). - * - * \p data_size indicates the size, in the number of characters, - * of the attribute. - * * \since 1.8.0 * */ @@ -415,7 +429,7 @@ H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/); * relative to location * \param[in] idx_type Type of index * \param[in] order Index traversal order - * \param[in] n Attribute’s position in index + * \param[in] n Attribute's position in index * \param[out] ainfo Struct containing returned attribute information * \lapl_id * @@ -424,19 +438,12 @@ H5_DLL herr_t H5Aget_info(hid_t attr_id, H5A_info_t *ainfo /*out*/); * \details H5Aget_info_by_idx() retrieves information for an attribute * that is attached to an object, which is specified by its * location and name, \p loc_id and \p obj_name, respectively. - * The attribute is located by its index position and the attribute + * The attribute is located by its index position, and the attribute * information is returned in the \p ainfo struct. * - * If \p loc_id fully specifies the object to which the attribute - * is attached, \p obj_name should be '.' (a dot). - * * The attribute is located by means of an index type, an index * traversal order, and a position in the index, \p idx_type, - * \p order and \p n, respectively. These parameters and their - * valid values are discussed in the description of H5Aiterate2(). - * - * The \p ainfo struct, which will contain the returned attribute - * information, is described in H5Aget_info(). + * \p order and \p n, respectively. * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -451,11 +458,10 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t /** * \ingroup H5A * - * \brief Retrieves attribute information, by attribute name + * \brief Retrieves attribute information by attribute name * * \fgdt_loc_id - * - * \param[in] obj_name Name of object to which attribute is attached, + * \param[in] obj_name Name of the object to which an attribute is attached, * relative to location * \param[in] attr_name Attribute name * \param[out] ainfo Struct containing returned attribute information @@ -468,11 +474,6 @@ H5_DLL herr_t H5Aget_info_by_idx(hid_t loc_id, const char *obj_name, H5_index_t * location and name, \p loc_id and \p obj_name, respectively. * The attribute information is returned in the \p ainfo struct. * - * If \p loc_id fully specifies the object to which the attribute - * is attached, \p obj_name should be '.' (a dot). - * - * The \p ainfo struct is described in H5Aget_info(). - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to * access the object, \p obj_name. @@ -493,7 +494,7 @@ H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char * \param[out] buf Buffer to store name in * * \return Returns the length of the attribute's name, which may be longer - * than \p buf_size, if successful. Otherwise returns a negative + * than \p buf_size, if successful. Otherwise, returns a negative * value. * * \details H5Aget_name() retrieves the name of an attribute specified by @@ -503,8 +504,8 @@ H5_DLL herr_t H5Aget_info_by_name(hid_t loc_id, const char *obj_name, const char * string terminator is stored in the last position of the buffer * to properly terminate the string. * - * If the user only wants to find out the size of this name, the - * values 0 and NULL can be passed in for the parameters + * If the user only wants to retrieve the name length, the + * values 0 and NULL should be passed for the parameters * \p bufsize and \p buf. * * \since 1.0.0 @@ -515,20 +516,20 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf); /** * \ingroup H5A * - * \brief Gets an attribute name, by attribute index position + * \brief Gets an attribute name by attribute index position * * \fgdt_loc_id * \param[in] obj_name Name of object to which attribute is attached, * relative to location * \param[in] idx_type Type of index * \param[in] order Index traversal order - * \param[in] n Attribute’s position in index + * \param[in] n Attribute's position in index * \param[out] name Attribute name * \param[in] size Size, in bytes, of attribute name * \lapl_id * * \return Returns attribute name size, in bytes, if successful; - * otherwise returns a negative value. + * otherwise, returns a negative value. * * \details H5Aget_name_by_idx() retrieves the name of an attribute that is * attached to an object, which is specified by its location and @@ -536,17 +537,13 @@ H5_DLL ssize_t H5Aget_name(hid_t attr_id, size_t buf_size, char *buf); * located by its index position, the size of the name is specified * in \p size, and the attribute name is returned in \p name. * - * If \p loc_id fully specifies the object to which the attribute - * is attached, \p obj_name should be '.' (a dot). - * * The attribute is located by means of an index type, an index * traversal order, and a position in the index, \p idx_type, - * \p order and \p n, respectively. These parameters and their - * valid values are discussed in the description of H5Aiterate2(). + * \p order and \p n, respectively. * - * If the attribute name’s size is unknown, the values 0 and NULL + * If the attribute name's size is unknown, the values 0 and NULL * can be passed in for the parameters \p size and \p name. The - * function’s return value will provide the correct value for + * function's return value will provide the correct value for * \p size. * * The link access property list, \p lapl_id, may provide @@ -582,12 +579,12 @@ H5_DLL hid_t H5Aget_space(hid_t attr_id); /** * \ingroup H5A * - * \brief Returns the amount of storage required for an attribute + * \brief Returns the amount of storage used to store an attribute * * \attr_id * * \return Returns the amount of storage size allocated for the attribute; - * otherwise returns 0 (zero). + * otherwise, returns 0 (zero). * * \details H5Aget_storage_size() returns the amount of storage that is * required for the specified attribute, \p attr_id. @@ -600,17 +597,16 @@ H5_DLL hsize_t H5Aget_storage_size(hid_t attr_id); /** * \ingroup H5A * - * \brief Gets an attribute datatype + * \brief Gets an attribute's datatype * * \attr_id * * \return \hid_t{datatype} * - * \details H5Aget_type() retrieves a copy of the datatype for an attribute. + * \details H5Aget_type() retrieves a copy of the attribute's datatype. * The datatype is reopened if it is a named type before returning * it to the application. The datatypes returned by this function - * are always read-only. If an error occurs when atomizing the - * return datatype, then the datatype is closed. + * are always read-only. * * The datatype identifier returned from this function must be * released with H5Tclose() or resource leaks will develop. @@ -623,7 +619,7 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); /** * \ingroup H5A * - * \brief Calls user-defined function for each attribute on an object + * \brief Calls a user-defined function for each attribute on an object * * \fgdt_loc_id * \param[in] idx_type Type of index @@ -642,32 +638,21 @@ H5_DLL hid_t H5Aget_type(hid_t attr_id); * \details H5Aiterate2() iterates over the attributes attached to a * dataset, named datatype, or group, as specified by \p loc_id. * For each attribute, user-provided data, \p op_data, with - * additional information as defined below, is passed to a + * additional information, as defined below, is passed to a * user-defined function, \p op, which operates on that * attribute. * * The order of the iteration and the attributes iterated over * are specified by three parameters: the index type, * \p idx_type; the order in which the index is to be traversed, - * \p order; and the attribute’s position in the index, \p idx. - * - * The type of index specified by \p idx_type can be one of the - * following: - * - * \indexes - * - * The order in which the index is to be traversed, as specified - * by \p order, can be one of the following: - * - * \orders - * + * \p order; and the attribute's position in the index, \p idx. * The next attribute to be operated on is specified by \p idx, * a position in the index. * * For example, if \p idx_type, \p order, and \p idx are set to * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute * in question is the fifth attribute from the beginning of the - * alpha-numeric index of attribute names. If \p order were set to + * alphanumeric index of attribute names. If \p order were set to * #H5_ITER_DEC, it would be the fifth attribute from the end of * the index. * @@ -677,13 +662,11 @@ 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. * - * \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. * + * \warning Adding or removing attributes to the object during iteration + * will lead to undefined behavior. + * * \since 1.8.0 * */ @@ -707,41 +690,27 @@ H5_DLL herr_t H5Aiterate2(hid_t loc_id, H5_index_t idx_type, H5_iter_order_t ord * * \return \herr_t * Further note that this function returns the return value of - * the last operator if it was non-zero, which can be a negative + * the last operator if it is non-zero, which can be a negative * value, zero if all attributes were processed, or a positive value * indicating short-circuit success. * * \details H5Aiterate_by_name() iterates over the attributes attached * to the dataset or group specified with \p loc_id and \p obj_name. * For each attribute, user-provided data, \p op_data, with - * additional information as defined below, is passed to a + * additional information, as defined below, is passed to a * user-defined function, \p op, which operates on that attribute. * - * If \p loc_id fully specifies the object to which these - * attributes are attached, \p obj_name should be '.' (a dot). - * * The order of the iteration and the attributes iterated over * are specified by three parameters: the index type, \p idx_type; * the order in which the index is to be traversed, \p order; - * and the attribute’s position in the index, \p idx. - * - * The type of index specified by \p idx_type can be one of the - * following: - * - * \indexes - * - * The order in which the index is to be traversed, as specified - * by \p order, can be one of the following: - * - * \orders - * + * and the attribute's position in the index, \p idx. * The next attribute to be operated on is specified by \p idx, * a position in the index. * * For example, if \p idx_type, \p order, and \p idx are set to * #H5_INDEX_NAME, #H5_ITER_INC, and 5, respectively, the attribute * in question is the fifth attribute from the beginning of the - * alpha-numeric index of attribute names. If \p order were set to + * alphanumeric index of attribute names. If \p order were set to * #H5_ITER_DEC, it would be the fifth attribute from the end of * the index. * @@ -751,29 +720,13 @@ 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. * - * \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: - * - * \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. - * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access * the object, \p obj_name. * + * \warning Adding or removing attributes to the object during iteration + * will lead to undefined behavior. + * * \since 1.8.0 * */ @@ -794,10 +747,9 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t * \return \hid_tv{attribute} * * \details H5Aopen() opens an existing attribute, \p attr_name, that is - * attached to object specified by an object identifier, \p obj_id. + * attached to the object specified by an object identifier, \p obj_id. * - * The attribute access property list, \p aapl_id, is currently unused - * and should be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * This function, H5Aopen_by_idx() or H5Aopen_by_name() must be called * before the attribute can be accessed for any further purpose, @@ -806,12 +758,26 @@ H5_DLL herr_t H5Aiterate_by_name(hid_t loc_id, const char *obj_name, H5_index_t * The attribute identifier returned by this function must be released * with H5Aclose() or resource leaks will develop. * + * \par Example + * \snippet H5A_examples.c read + * * \since 1.8.0 * * \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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Aopen_async(hid_t obj_id, const char *attr_name, hid_t aapl_id, hid_t es_id); +#endif +/*--------------------------------------------------------------------------*/ /** * \ingroup H5A * @@ -822,7 +788,7 @@ H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id); * relative to location * \param[in] idx_type Type of index * \param[in] order Index traversal order - * \param[in] n Attribute’s position in index + * \param[in] n Attribute's position in index * \aapl_id * \lapl_id * @@ -830,17 +796,13 @@ H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id); * * \details H5Aopen_by_idx() opens an existing attribute that is attached * to an object specified by location and name, \p loc_id and - * \p obj_name, respectively. If \p loc_id fully specifies the - * object to which the attribute is attached, \p obj_name, should - * be '.' (a dot). + * \p obj_name, respectively. * * The attribute is identified by an index type, an index traversal * order, and a position in the index, \p idx_type, \p order and - * \p n, respectively. These parameters and their valid values are - * discussed in the description of H5Aiterate2(). + * \p n, respectively. * - * The attribute access property list, \p aapl_id, is currently - * unused and should currently be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -859,6 +821,20 @@ H5_DLL hid_t H5Aopen(hid_t obj_id, const char *attr_name, hid_t aapl_id); 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Aopen_by_idx_async(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); +#endif +/*--------------------------------------------------------------------------*/ /** * \ingroup H5A * @@ -879,11 +855,9 @@ H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_t * * \p loc_id specifies a location from which the target object can * be located and \p obj_name is an object name relative to - * \p loc_id. If \p loc_id fully specifies the object to which the - * attribute is attached, \p obj_name should be '.' (a dot). + * \p loc_id. * - * The attribute access property list, \p aapl_id, is currently - * unused and should currently be #H5P_DEFAULT. + * \plist_unused{aapl_id} * * The link access property list, \p lapl_id, may provide * information regarding the properties of links required to access @@ -901,6 +875,20 @@ H5_DLL hid_t H5Aopen_by_idx(hid_t loc_id, const char *obj_name, H5_index_t idx_t */ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Aopen_by_name_async(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t aapl_id, + hid_t lapl_id, hid_t es_id); +#endif + /*-------------------------------------------------------------------------- */ /** * \ingroup H5A @@ -920,6 +908,9 @@ H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *att * Datatype conversion takes place at the time of a read or write and * is automatic. * + * \par Example + * \snippet H5A_examples.c read + * * \version 1.8.8 Fortran updated to Fortran2003. * \version 1.4.2 The \p dims parameter was added to the Fortran API in this * release. @@ -929,6 +920,17 @@ H5_DLL hid_t H5Aopen_by_name(hid_t loc_id, const char *obj_name, const char *att * */ H5_DLL herr_t H5Aread(hid_t attr_id, hid_t type_id, void *buf); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Aread} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Aread_async(chid_t attr_id, hid_t dtype_id, void *buf, hid_t es_id); +#endif /*-------------------------------------------------------------------------*/ /** * \ingroup H5A @@ -952,6 +954,30 @@ 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{H5Arename} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Arename_async(hid_t loc_id, const char *old_name, const char *new_name, hid_t es_id); +#endif +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Arename_by_name} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Arename_by_name_async(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); +#endif +/*--------------------------------------------------------------------------*/ /** * \ingroup H5A * @@ -967,15 +993,12 @@ H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name * attribute's in-memory datatype is specified with \p type_id. * The entire attribute is written from \p buf to the file. * - * If \p type_id is either a fixed-length or variable-length string, - * it is important to set the string length when defining the datatype. - * String datatypes are derived from #H5T_C_S1 (or #H5T_FORTRAN_S1 for - * Fortran codes), which defaults to 1 character in size. - * See H5Tset_size() and Creating variable-length string datatypes. - * * Datatype conversion takes place at the time of a read or write and * is automatic. * + * \par Example + * \snippet H5A_examples.c update + * * \version 1.8.8 Fortran updated to Fortran2003. * \version 1.4.2 Fortran \p dims parameter added in this release * \since 1.0.0 @@ -983,6 +1006,17 @@ H5_DLL herr_t H5Arename(hid_t loc_id, const char *old_name, const char *new_name * */ H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf); +/*--------------------------------------------------------------------------*/ +/** + * \ingroup ASYNC + * \async_variant_of{H5Awrite} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Awrite_async(hid_t attr_id, hid_t type_id, const void *buf, hid_t es_id); +#endif /*-------------------------------------------------------------------------*/ /** * \ingroup H5A @@ -1009,6 +1043,42 @@ H5_DLL herr_t H5Awrite(hid_t attr_id, hid_t type_id, const void *buf); 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); +/// \cond DEV +/* API Wrappers for async routines */ +/* (Must be defined _after_ the function prototype) */ +/* (And must only defined when included in application code, not the library) */ +#ifndef H5A_MODULE +#define H5Acreate_async(...) H5Acreate_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Acreate_by_name_async(...) H5Acreate_by_name_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Aopen_async(...) H5Aopen_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Aopen_by_name_async(...) H5Aopen_by_name_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Aopen_by_idx_async(...) H5Aopen_by_idx_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Awrite_async(...) H5Awrite_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Aread_async(...) H5Aread_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Arename_async(...) H5Arename_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Arename_by_name_async(...) H5Arename_by_name_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Aexists_async(...) H5Aexists_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Aexists_by_name_async(...) H5Aexists_by_name_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Aclose_async(...) H5Aclose_async(__FILE__, __func__, __LINE__, __VA_ARGS__) + +/* Define "wrapper" versions of function calls, to allow compile-time values to + * be passed in by language wrapper or library layer on top of HDF5. + */ +#define H5Acreate_async_wrap H5_NO_EXPAND(H5Acreate_async) +#define H5Acreate_by_name_async_wrap H5_NO_EXPAND(H5Acreate_by_name_async) +#define H5Aopen_async_wrap H5_NO_EXPAND(H5Aopen_async) +#define H5Aopen_by_name_async_wrap H5_NO_EXPAND(H5Aopen_by_name_async) +#define H5Aopen_by_idx_async_wrap H5_NO_EXPAND(H5Aopen_by_idx_async) +#define H5Awrite_async_wrap H5_NO_EXPAND(H5Awrite_async) +#define H5Aread_async_wrap H5_NO_EXPAND(H5Aread_async) +#define H5Arename_async_wrap H5_NO_EXPAND(H5Arename_async) +#define H5Arename_by_name_async_wrap H5_NO_EXPAND(H5Arename_by_name_async) +#define H5Aexists_async_wrap H5_NO_EXPAND(H5Aexists_async) +#define H5Aexists_by_name_async_wrap H5_NO_EXPAND(H5Aexists_by_name_async) +#define H5Aclose_async_wrap H5_NO_EXPAND(H5Aclose_async) +#endif /* H5A_MODULE */ +/// \endcond + /* Symbols defined for compatibility with previous versions of the HDF5 API. * * Use of these symbols is deprecated. @@ -1026,7 +1096,7 @@ H5_DLL herr_t H5Arename_by_name(hid_t loc_id, const char *obj_name, const char * * \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 + * \param[in,out] operator_data A pointer to the operator data passed into * H5Aiterate1() * \returns The return values from an operator are: * \li Zero causes the iterator to continue, returning zero when @@ -1057,9 +1127,9 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam * * \return \hid_tv{attribute} * - * \note The \p acpl parameters is currently not used; specify #H5P_DEFAULT. + * \deprecation_note{H5Acreate2()} * - * \deprecated Deprecated in favor of H5Acreate2() + * \plist_unused{acpl} * * \details H5Acreate1() creates an attribute, \p name, which is attached * to the object specified by the identifier \p loc_id. @@ -1067,18 +1137,7 @@ typedef herr_t (*H5A_operator1_t)(hid_t location_id /*in*/, const char *attr_nam * The attribute name, \p name, must be unique for the object. * * The attribute is created with the specified datatype and dataspace, - * \p type_id and \p space_id, which are created with the H5T and - * H5S interfaces, respectively. - * - * If \p type_id is either a fixed-length or variable-length string, - * it is important to set the string length when defining the - * datatype. String datatypes are derived from #H5T_C_S1 (or - * #H5T_FORTRAN_S1 for Fortran), which defaults to 1 character in - * size. See H5Tset_size() and Creating variable-length string - * datatypes. - * - * The attribute identifier returned by this function must be released - * with H5Aclose() resource leaks will develop. + * \p type_id and \p space_id. * * \since 1.8.0 * @@ -1097,11 +1156,10 @@ H5_DLL hid_t H5Acreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa * * \fgdt_loc_id * - * \return Returns the number of attributes if successful; otherwise returns + * \return Returns the number of attributes if successful; otherwise, returns * a negative value. * - * \deprecated This function is deprecated in favor of the functions - * H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx(). + * \deprecation_note{H5Oget_info(), H5Oget_info_by_name(), and H5Oget_info_by_idx()} * * \details H5Aget_num_attrs() returns the number of attributes attached to * the object specified by its identifier, \p loc_id. @@ -1114,18 +1172,17 @@ H5_DLL int H5Aget_num_attrs(hid_t loc_id); /** * \ingroup H5A * - * \brief Calls a user’s function for each attribute on an object + * \brief Calls a user's function for each attribute on an object * * \loc_id * \param[in,out] idx Starting (in) and ending (out) attribute index * \param[in] op User's function to pass each attribute to - * \param[in,out] op_data User's data to pass through to iterator operator + * \param[in,out] op_data User's data to pass through to the iterator operator * function * * \return \herr_t * - * \deprecated This function is deprecated in favor of the function - * H5Aiterate2(). + * \deprecation_note{H5Aiterate2()} * * \details H5Aiterate1() iterates over the attributes of the object * specified by its identifier, \p loc_id. The object can be a @@ -1137,9 +1194,8 @@ 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. * - * \p op is a user-defined function whose prototype is defined as follows: - * \snippet this H5A_operator1_t_snip - * \click4more + * \warning Adding or removing attributes to the object during iteration + * will lead to undefined behavior. * * \version 1.8.0 The function \p H5Aiterate was renamed to H5Aiterate1() * and deprecated in this release. @@ -1158,14 +1214,13 @@ H5_DLL herr_t H5Aiterate1(hid_t loc_id, unsigned *idx, H5A_operator1_t op, void * * \return \hid_tv{attribute} * - * \deprecated This function is deprecated in favor of the function - * H5Aopen_by_idx(). + * \deprecation_note{H5Aopen_by_idx()} * - * \details H5Aopen_idx() opens an attribute which is attached to the - * object specified with \p loc_id . The location object may be + * \details H5Aopen_idx() opens an attribute that is attached to the + * object specified with \p loc_id. The location object may be * either a group, dataset, or named datatype, all of which may * have any sort of attribute. The attribute specified by the index, - * \p idx , indicates the attribute to access. The value of \p idx + * \p idx, indicates the attribute to access. The value of \p idx * is a 0-based, non-negative integer. The attribute identifier * returned from this function must be released with H5Aclose() * or resource leaks will develop. @@ -1185,8 +1240,7 @@ H5_DLL hid_t H5Aopen_idx(hid_t loc_id, unsigned idx); * * \return \hid_tv{attribute} * - * \deprecated This function is deprecated in favor of the function - * H5Aopen_by_name(). + * \deprecation_note{H5Aopen_by_name()} * * \details H5Aopen_name() opens an attribute specified by its name, * \p name, which is attached to the object specified with diff --git a/libs/windows/include/H5ArrayType.h b/libs/windows/include/H5ArrayType.h index 4302352..e9afb9c 100644 --- a/libs/windows/include/H5ArrayType.h +++ b/libs/windows/include/H5ArrayType.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -37,7 +36,7 @@ class H5_DLLCPP ArrayType : public DataType { // Returns an ArrayType object via DataType* by decoding the // binary object description of this type. - virtual DataType *decode() const; + virtual DataType *decode() const override; // Returns the number of dimensions of this array datatype. int getArrayNDims() const; @@ -49,7 +48,7 @@ class H5_DLLCPP ArrayType : public DataType { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("ArrayType"); } @@ -61,7 +60,7 @@ class H5_DLLCPP ArrayType : public DataType { ArrayType(const hid_t existing_id); // Noop destructor - virtual ~ArrayType(); + virtual ~ArrayType() override; // Default constructor ArrayType(); diff --git a/libs/windows/include/H5AtomType.h b/libs/windows/include/H5AtomType.h index 84da5e9..bb2cf48 100644 --- a/libs/windows/include/H5AtomType.h +++ b/libs/windows/include/H5AtomType.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -58,7 +57,7 @@ class H5_DLLCPP AtomType : public DataType { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("AtomType"); } @@ -68,7 +67,7 @@ class H5_DLLCPP AtomType : public DataType { AtomType(const AtomType &original); // Noop destructor - virtual ~AtomType(); + virtual ~AtomType() override; #endif // DOXYGEN_SHOULD_SKIP_THIS protected: diff --git a/libs/windows/include/H5Attribute.h b/libs/windows/include/H5Attribute.h index 41e5a31..6851e1a 100644 --- a/libs/windows/include/H5Attribute.h +++ b/libs/windows/include/H5Attribute.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -38,7 +37,7 @@ class H5_DLLCPP Attribute : public AbstractDs, public H5Location { Attribute(const hid_t attr_id); // Closes this attribute. - virtual void close(); + virtual void close() override; // Gets the name of this attribute. ssize_t getName(char *attr_name, size_t buf_size = 0) const; @@ -50,13 +49,13 @@ class H5_DLLCPP Attribute : public AbstractDs, public H5Location { ssize_t getName(size_t buf_size, H5std_string &attr_name) const; // Gets a copy of the dataspace for this attribute. - virtual DataSpace getSpace() const; + virtual DataSpace getSpace() const override; // Returns the amount of storage size required for this attribute. - virtual hsize_t getStorageSize() const; + virtual hsize_t getStorageSize() const override; // Returns the in memory size of this attribute's data. - virtual size_t getInMemDataSize() const; + virtual size_t getInMemDataSize() const override; // Reads data from this attribute. void read(const DataType &mem_type, void *buf) const; @@ -68,21 +67,21 @@ class H5_DLLCPP Attribute : public AbstractDs, public H5Location { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("Attribute"); } // Gets the attribute id. - virtual hid_t getId() const; + virtual hid_t getId() const override; // Destructor: properly terminates access to this attribute. - virtual ~Attribute(); + virtual ~Attribute() override; #ifndef DOXYGEN_SHOULD_SKIP_THIS protected: // Sets the attribute id. - virtual void p_setId(const hid_t new_id); + virtual void p_setId(const hid_t new_id) override; #endif // DOXYGEN_SHOULD_SKIP_THIS private: @@ -92,7 +91,7 @@ class H5_DLLCPP Attribute : public AbstractDs, public H5Location { // getTypeClass and various API functions getXxxType // defined in AbstractDs for generic datatype and specific // sub-types - virtual hid_t p_get_type() const; + virtual hid_t p_get_type() const override; // Reads variable or fixed len strings from this attribute. void p_read_variable_len(const DataType &mem_type, H5std_string &strg) const; diff --git a/libs/windows/include/H5Classes.h b/libs/windows/include/H5Classes.h index 7820ce2..b4a0670 100644 --- a/libs/windows/include/H5Classes.h +++ b/libs/windows/include/H5Classes.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * diff --git a/libs/windows/include/H5CommonFG.h b/libs/windows/include/H5CommonFG.h index d87f9ca..e675617 100644 --- a/libs/windows/include/H5CommonFG.h +++ b/libs/windows/include/H5CommonFG.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * diff --git a/libs/windows/include/H5CompType.h b/libs/windows/include/H5CompType.h index 6a4c093..0675d20 100644 --- a/libs/windows/include/H5CompType.h +++ b/libs/windows/include/H5CompType.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -45,7 +44,7 @@ class H5_DLLCPP CompType : public DataType { // Returns a CompType object via DataType* by decoding the binary // object description of this type. - virtual DataType *decode() const; + virtual DataType *decode() const override; // Returns the type class of the specified member of this compound // datatype. It provides to the user a way of knowing what type @@ -108,13 +107,13 @@ class H5_DLLCPP CompType : public DataType { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("CompType"); } // Noop destructor. - virtual ~CompType(); + virtual ~CompType() override; private: // Contains common code that is used by the member functions diff --git a/libs/windows/include/H5Cpp.h b/libs/windows/include/H5Cpp.h index 9272bdb..34fdef2 100644 --- a/libs/windows/include/H5Cpp.h +++ b/libs/windows/include/H5Cpp.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -48,14 +47,4 @@ #include "H5File.h" #include "H5Library.h" -/* Some C++ compilers do not have offsetof macro; define to bypass the problem - - BMR- -EIP- 2007/08/01 -*/ -#ifndef H5_CXX_HAVE_OFFSETOF -#ifdef HOFFSET -#undef HOFFSET -#endif -#define HOFFSET(TYPE, MEMBER) ((size_t) & ((TYPE *)0)->MEMBER) -#endif - #endif // H5Cpp_H diff --git a/libs/windows/include/H5CppDoc.h b/libs/windows/include/H5CppDoc.h index 4337a6f..37bd8a5 100644 --- a/libs/windows/include/H5CppDoc.h +++ b/libs/windows/include/H5CppDoc.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * diff --git a/libs/windows/include/H5Cpublic.h b/libs/windows/include/H5Cpublic.h index 79ece10..69c86cd 100644 --- a/libs/windows/include/H5Cpublic.h +++ b/libs/windows/include/H5Cpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -13,23 +12,16 @@ /*------------------------------------------------------------------------- * - * Created: H5Cpublic.h - * June 4, 2005 - * John Mainzer + * Created: H5Cpublic.h * - * Purpose: Public include file for cache functions. + * Purpose: Public header file for cache functions * *------------------------------------------------------------------------- */ #ifndef H5Cpublic_H #define H5Cpublic_H -/* Public headers needed by this file */ -#include "H5public.h" - -#ifdef __cplusplus -extern "C" { -#endif +#include "H5public.h" /* Generic Functions */ enum H5C_cache_incr_mode { H5C_incr__off, @@ -61,7 +53,4 @@ enum H5C_cache_decr_mode { /**Bypassing default HDF5 behavior in order to optimize for specific + * use cases (H5DO) + * + * HDF5 functions described is this section are implemented in the HDF5 High-level + * library as optimized functions. These functions generally require careful setup + * and testing as they enable an application to bypass portions of the HDF5 + * library's I/O pipeline for performance purposes. + * + * These functions are distributed in the standard HDF5 distribution and are + * available any time the HDF5 High-level library is available. + * + * - \ref H5DOappend + * \n Appends data to a dataset along a specified dimension. + * - \ref H5DOread_chunk + * \n Reads a raw data chunk directly from a dataset in a file into a buffer (DEPRECATED) + * - \ref H5DOwrite_chunk + * \n Writes a raw data chunk from a buffer directly to a dataset in a file (DEPRECATED) + * + */ + /*------------------------------------------------------------------------- * * "Optimized dataset" routines. @@ -25,6 +50,48 @@ extern "C" { *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5DO + * + * \brief Appends data to a dataset along a specified dimension. + * + * \param[in] dset_id Dataset identifier + * \param[in] dxpl_id Dataset transfer property list identifier + * \param[in] axis Dataset Dimension (0-based) for the append + * \param[in] extension Number of elements to append for the + * axis-th dimension + * \param[in] memtype The memory datatype identifier + * \param[in] buf Buffer with data for the append + * + * \return \herr_t + * + * \details The H5DOappend() routine extends a dataset by \p extension + * number of elements along a dimension specified by a + * dimension \p axis and writes \p buf of elements to the + * dataset. Dimension \p axis is 0-based. Elements’ type + * is described by \p memtype. + * + * This routine combines calling H5Dset_extent(), + * H5Sselect_hyperslab(), and H5Dwrite() into a single routine + * that simplifies application development for the common case + * of appending elements to an existing dataset. + * + * For a multi-dimensional dataset, appending to one dimension + * will write a contiguous hyperslab over the other dimensions. + * For example, if a 3-D dataset has dimension sizes (3, 5, 8), + * extending the 0th dimension (currently of size 3) by 3 will + * append 3*5*8 = 120 elements (which must be pointed to by the + * \p buffer parameter) to the dataset, making its final + * dimension sizes (6, 5, 8). + * + * If a dataset has more than one unlimited dimension, any of + * those dimensions may be appended to, although only along + * one dimension per call to H5DOappend(). + * + * \since 1.10.0 + * + */ H5_HLDLL herr_t H5DOappend(hid_t dset_id, hid_t dxpl_id, unsigned axis, size_t extension, hid_t memtype, const void *buf); @@ -35,8 +102,142 @@ H5_HLDLL herr_t H5DOappend(hid_t dset_id, hid_t dxpl_id, unsigned axis, size_t e #ifndef H5_NO_DEPRECATED_SYMBOLS /* Compatibility wrappers for functionality moved to H5D */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5DO + * + * \brief Writes a raw data chunk from a buffer directly to a dataset in a file. + * + * \param[in] dset_id Identifier for the dataset to write to + * \param[in] dxpl_id Transfer property list identifier for + * this I/O operation + * \param[in] filters Mask for identifying the filters in use + * \param[in] offset Logical position of the chunk's first element + * in the dataspace + * \param[in] data_size Size of the actual data to be written in bytes + * \param[in] buf Buffer containing data to be written to the chunk + * + * \return \herr_t + * + * \deprecated This function was deprecated in favor of the function + * H5Dwrite_chunk() of HDF5-1.10.3. + * The functionality of H5DOwrite_chunk() was moved + * to H5Dwrite_chunk(). + * \deprecated For compatibility, this API call has been left as a stub which + * simply calls H5Dwrite_chunk(). New code should use H5Dwrite_chunk(). + * + * \details The H5DOwrite_chunk() writes a raw data chunk as specified by its + * logical \p offset in a chunked dataset \p dset_id from the application + * memory buffer \p buf to the dataset in the file. Typically, the data + * in \p buf is preprocessed in memory by a custom transformation, such as + * compression. The chunk will bypass the library's internal data + * transfer pipeline, including filters, and will be written directly to the file. + * + * \p dxpl_id is a data transfer property list identifier. + * + * \p filters is a mask providing a record of which filters are used + * with the chunk. The default value of the mask is zero (\c 0), + * indicating that all enabled filters are applied. A filter is skipped + * if the bit corresponding to the filter's position in the pipeline + * (0 ≤ position < 32) is turned on. This mask is saved + * with the chunk in the file. + * + * \p offset is an array specifying the logical position of the first + * element of the chunk in the dataset's dataspace. The length of the + * offset array must equal the number of dimensions, or rank, of the + * dataspace. The values in \p offset must not exceed the dimension limits + * and must specify a point that falls on a dataset chunk boundary. + * + * \p data_size is the size in bytes of the chunk, representing the number of + * bytes to be read from the buffer \p buf. If the data chunk has been + * precompressed, \p data_size should be the size of the compressed data. + * + * \p buf is the memory buffer containing data to be written to the chunk in the file. + * + * \attention Exercise caution when using H5DOread_chunk() and H5DOwrite_chunk(), + * as they read and write data chunks directly in a file. + * H5DOwrite_chunk() bypasses hyperslab selection, the conversion of data + * from one datatype to another, and the filter pipeline to write the chunk. + * Developers should have experience with these processes before + * using this function. Please see + * + * Using the Direct Chunk Write Function + * for more information. + * + * \note H5DOread_chunk() and H5DOwrite_chunk() are not + * supported under parallel and do not support variable length types. + * + * \par Example + * The following code illustrates the use of H5DOwrite_chunk to write + * an entire dataset, chunk by chunk: + * \snippet H5DO_examples.c H5DOwrite + * + * \version 1.10.3 Function deprecated in favor of H5Dwrite_chunk. + * + * \since 1.8.11 + */ H5_HLDLL herr_t H5DOwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, const hsize_t *offset, size_t data_size, const void *buf); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5DO + * + * \brief Reads a raw data chunk directly from a dataset in a file into a buffer. + * + * \param[in] dset_id Identifier for the dataset to be read + * \param[in] dxpl_id Transfer property list identifier for + * this I/O operation + * \param[in] offset Logical position of the chunk's first + element in the dataspace + * \param[in,out] filters Mask for identifying the filters used + * with the chunk + * \param[in] buf Buffer containing the chunk read from + * the dataset + * + * \return \herr_t + * + * \deprecated This function was deprecated in favor of the function + * H5Dread_chunk() as of HDF5-1.10.3. + * In HDF5 1.10.3, the functionality of H5DOread_chunk() + * was moved to H5Dread_chunk(). + * \deprecated For compatibility, this API call has been left as a stub which + * simply calls H5Dread_chunk(). New code should use H5Dread_chunk(). + * + * \details The H5DOread_chunk() reads a raw data chunk as specified + * by its logical \p offset in a chunked dataset \p dset_id + * from the dataset in the file into the application memory + * buffer \p buf. The data in \p buf is read directly from the file + * bypassing the library's internal data transfer pipeline, + * including filters. + * + * \p dxpl_id is a data transfer property list identifier. + * + * The mask \p filters indicates which filters are used with the + * chunk when written. A zero value indicates that all enabled filters + * are applied on the chunk. A filter is skipped if the bit corresponding + * to the filter's position in the pipeline + * (0 ≤ position < 32) is turned on. + * + * \p offset is an array specifying the logical position of the first + * element of the chunk in the dataset's dataspace. The length of the + * offset array must equal the number of dimensions, or rank, of the + * dataspace. The values in \p offset must not exceed the dimension + * limits and must specify a point that falls on a dataset chunk boundary. + * + * \p buf is the memory buffer containing the chunk read from the dataset + * in the file. + * + * \par Example + * The following code illustrates the use of H5DOread_chunk() + * to read a chunk from a dataset: + * \snippet H5DO_examples.c H5DOread + * + * \version 1.10.3 Function deprecated in favor of H5Dread_chunk. + * + * \since 1.10.2, 1.8.19 + */ H5_HLDLL herr_t H5DOread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, uint32_t *filters /*out*/, void *buf /*out*/); diff --git a/libs/windows/include/H5DSpublic.h b/libs/windows/include/H5DSpublic.h index 7306cbc..edbebdb 100644 --- a/libs/windows/include/H5DSpublic.h +++ b/libs/windows/include/H5DSpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -19,31 +18,392 @@ #define REFERENCE_LIST "REFERENCE_LIST" #define DIMENSION_LABELS "DIMENSION_LABELS" +/** + * \brief Prototype for H5DSiterate_scales() operator + * + */ +//! typedef herr_t (*H5DS_iterate_t)(hid_t dset, unsigned dim, hid_t scale, void *visitor_data); +//! #ifdef __cplusplus extern "C" { #endif +/** \page H5DS_UG The HDF5 High Level Dimension Scales + * @todo Under Construction + */ + +/**\defgroup H5DS HDF5 Dimension Scales APIs (H5DS) + * + * Creating and manipulating HDF5 datasets that are associated with + * the dimension of another HDF5 dataset (H5DS) + * + * \note \Bold{Programming hints:} + * \note To use any of these functions or subroutines, + * you must first include the relevant include file (C) or + * module (Fortran) in your application. + * \note The following line includes the HDF5 Dimension Scale package, + * H5DS, in C applications: + * \code #include "hdf5_hl.h" \endcode + * \note This line includes the H5DS module in Fortran applications: + * \code use h5ds \endcode + * + * - \ref H5DSwith_new_ref + * \n Determines if new references are used with dimension scales. + * - \ref H5DSattach_scale + * \n Attach dimension scale dsid to dimension idx of dataset did. + * - \ref H5DSdetach_scale + * \n Detach dimension scale dsid from the dimension idx of Dataset did. + * - \ref H5DSget_label + * \n Read the label for dimension idx of did into buffer label. + * - \ref H5DSget_num_scales + * \n Determines how many Dimension Scales are attached + * to dimension idx of did. + * - \ref H5DSget_scale_name + * \n Retrieves name of scale did into buffer name. + * - \ref H5DSis_attached + * \n Report if dimension scale dsid is currently attached + * to dimension idx of dataset did. + * - \ref H5DSis_scale + * \n Determines whether dset is a Dimension Scale. + * - \ref H5DSiterate_scales + * \n Iterates the operation visitor through the scales + * attached to dimension dim. + * - \ref H5DSset_label + * \n Set label for the dimension idx of did to the value label. + * - \ref H5DSset_scale + * \n Convert dataset dsid to a dimension scale, + * with optional name, dimname. + * + */ + +/* THIS IS A NEW ROUTINE NOT ON OLD PORTAL */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Determines if new references are used with dimension scales. + * + * \param[in] obj_id Object identifier + * \param[out] with_new_ref New references are used or not + * + * \return \herr_t + * + * \details H5DSwith_new_ref() takes any object identifier and checks + * if new references are used for dimension scales. Currently, + * new references are used when non-native VOL connector is + * used or when H5_DIMENSION_SCALES_WITH_NEW_REF is set up + * via configure option. + * + */ +H5_HLDLL herr_t H5DSwith_new_ref(hid_t obj_id, hbool_t *with_new_ref); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Attach dimension scale \p dsid to dimension \p idx of + * dataset did. + * + * \param[in] did The dataset + * \param[in] dsid The scale to be attached + * \param[in] idx The dimension of \p did that \p dsid is associated with + * + * \return \herr_t + * + * \details Define Dimension Scale \p dsid to be associated with + * dimension \p idx of dataset \p did. + * + * Entries are created in the #DIMENSION_LIST and + * #REFERENCE_LIST attributes, as defined in section 4.2 of + * + * HDF5 Dimension Scale Specification. + * + * Fails if: + * - Bad arguments + * - If \p dsid is not a Dimension Scale + * - If \p did is a Dimension Scale + * (A Dimension Scale cannot have scales.) + * + * \note The Dimension Scale \p dsid can be attached to the + * same dimension more than once, which has no effect. + */ H5_HLDLL herr_t H5DSattach_scale(hid_t did, hid_t dsid, unsigned int idx); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Detach dimension scale \p dsid from the dimension \p idx of dataset \p did. + * + * \param[in] did The dataset + * \param[in] dsid The scale to be detached + * \param[in] idx The dimension of \p did to detach + * + * \return \herr_t + * + * \details If possible, deletes association of Dimension Scale \p dsid with + * dimension \p idx of dataset \p did. This deletes the entries in the + * #DIMENSION_LIST and #REFERENCE_LIST attributes, + * as defined in section 4.2 of + * + * HDF5 Dimension Scale Specification. + * + * Fails if: + * - Bad arguments + * - The dataset \p did or \p dsid do not exist + * - The \p dsid is not a Dimension Scale + * - \p dsid is not attached to \p did + * + * \note A scale may be associated with more than dimension of the + * same dataset. If so, the detach operation only deletes one + * of the associations, for \p did. + * + */ H5_HLDLL herr_t H5DSdetach_scale(hid_t did, hid_t dsid, unsigned int idx); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Convert dataset \p dsid to a dimension scale, + * with optional name, \p dimname. + * + * \param[in] dsid The dataset to be made a Dimemsion Scale + * \param[in] dimname The dimension name (optional), NULL if the + * dimension has no name. + * + * \return \herr_t + * + * \details The dataset \p dsid is converted to a Dimension Scale dataset, + * as defined above. Creates the CLASS attribute, set to the value + * "DIMENSION_SCALE" and an empty #REFERENCE_LIST attribute, + * as described in + * + * HDF5 Dimension Scale Specification. + * (PDF, see section 4.2). + * + * If \p dimname is specified, then an attribute called NAME + * is created, with the value \p dimname. + * + * Fails if: + * - Bad arguments + * - If \p dsid is already a scale + * - If \p dsid is a dataset which already has dimension scales + * + * If the dataset was created with the Table, Image, or Palette interface [9], + * it is not recommended to convert to a Dimension Scale. + * (These Datasets will have a CLASS Table, Image, or Palette.) + * + * \todo what is [9] after Palette interface? + */ H5_HLDLL herr_t H5DSset_scale(hid_t dsid, const char *dimname); -H5_HLDLL int H5DSget_num_scales(hid_t did, unsigned int dim); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Determines how many Dimension Scales are attached + * to dimension \p idx of \p did. + * + * \param[in] did The dataset to query + * \param[in] idx The dimension of \p did to query + * + * \return Returns the number of Dimension Scales associated + * with \p did, if successful, otherwise returns a + * negative value. + * + * \details H5DSget_num_scales() determines how many Dimension + * Scales are attached to dimension \p idx of + * dataset \p did. + * + */ +H5_HLDLL int H5DSget_num_scales(hid_t did, unsigned int idx); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Set label for the dimension \p idx of \p did + * to the value \p label. + * + * \param[in] did The dataset + * \param[in] idx The dimension + * \param[in] label The label + * + * \return \herr_t + * + * \details Sets the #DIMENSION_LABELS for dimension \p idx of + * dataset \p did. If the dimension had a label, + * the new value replaces the old. + * + * Fails if: + * - Bad arguments + * + */ H5_HLDLL herr_t H5DSset_label(hid_t did, unsigned int idx, const char *label); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Read the label for dimension \p idx of \p did into buffer \p label. + * + * \param[in] did The dataset + * \param[in] idx The dimension + * \param[out] label The label + * \param[in] size The length of the label buffer + * + * \return Upon success, size of label or zero if no label found. + * Negative if fail. + * + * \details Returns the value of the #DIMENSION_LABELS for + * dimension \p idx of dataset \p did, if set. + * Up to \p size characters of the name are copied into + * the buffer \p label. If the label is longer than + * \p size, it will be truncated to fit. The parameter + * \p size is set to the size of the returned \p label. + * + * If \p did has no label, the return value of + * \p label is NULL. + * + * Fails if: + * - Bad arguments + * + */ H5_HLDLL ssize_t H5DSget_label(hid_t did, unsigned int idx, char *label, size_t size); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Retrieves name of scale \p did into buffer \p name. + * + * \param[in] did Dimension scale identifier + * \param[out] name Buffer to contain the returned name + * \param[in] size Size in bytes, of the \p name buffer + * + * \return Upon success, the length of the scale name or zero if no name found. + * Negative if fail. + * + * \details H5DSget_scale_name() retrieves the name attribute + * for scale \p did. + * + * Up to \p size characters of the scale 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 H5DSget_scale_name() call can + * be made by setting \p name to NULL. The return value of this call + * will be the size of the scale name; that value plus one (1) can then + * be assigned to \p size for a second H5DSget_scale_name() call, + * which will retrieve the actual name. (The value passed in with the + * parameter \p size must be one greater than size in bytes of the actual + * name in order to accommodate the null terminator; + * if \p size is set to the exact size of the name, the last byte + * passed back will contain the null terminator and the last character + * will be missing from the name passed back to the calling application.) + */ H5_HLDLL ssize_t H5DSget_scale_name(hid_t did, char *name, size_t size); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Determines whether \p did is a Dimension Scale. + * + * \param[in] did The dataset to query + * + * \return \htri_t + * + * \details H5DSis_scale() determines if \p did is a Dimension Scale, + * i.e., has class="DIMENSION_SCALE"). + * + */ H5_HLDLL htri_t H5DSis_scale(hid_t did); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Iterates the operation visitor through the scales + * attached to dimension \p dim. + * + * \param[in] did The dataset + * \param[in] dim The dimension of dataset \p did + * \param[in,out] idx Input the index to start iterating, + * output the next index to visit. + * If NULL, start at the first position. + * \param[in] visitor The visitor function + * \param[in] visitor_data Arbitrary data to pass to the + * visitor function + * + * \return Returns the return value of the last operator if it was + * non-zero, or zero if all scales were processed. + * + * \details H5DSiterate_scales() iterates over the scales attached to + * dimension \p dim of dataset \p did. For each scale in the + * list, the \p visitor_data and some additional information, + * specified below, are passed to the \p visitor 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. + * + * The prototype for \ref H5DS_iterate_t is: + * \snippet this H5DS_iterate_t_snip + * + * The operation receives the Dimension Scale dataset + * identifier, \p scale, and the pointer to the operator + * data passed in to H5DSiterate_scales(), \p visitor_data. + * + * The return values from an operator are: + * + * - Zero causes the iterator to continue, returning zero + * when all group members have been processed. + * - Positive causes the iterator to immediately return that + * positive value, indicating short-circuit success. + * The iterator can be restarted at the next group member. + * - Negative causes the iterator to immediately return + * that value, indicating failure. The iterator can be + * restarted at the next group member. + * + * H5DSiterate_scales() assumes that the scales of the + * dimension identified by \p dim remain unchanged through + * the iteration. If the membership changes during the iteration, + * the function's behavior is undefined. + */ H5_HLDLL herr_t H5DSiterate_scales(hid_t did, unsigned int dim, int *idx, H5DS_iterate_t visitor, void *visitor_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5DS + * + * \brief Report if dimension scale \p dsid is currently attached to + * dimension \p idx of dataset \p did. + * + * \param[in] did The dataset + * \param[in] dsid The scale to be attached + * \param[in] idx The dimension of \p did that \p dsid is associated with + * + * \return \htri_t + * + * \details Report if dimension scale \p dsid is currently attached to + * dimension \p idx of dataset \p did. + * + * Fails if: + * - Bad arguments + * - If \p dsid is not a Dimension Scale + * - The \p dsid is not a Dimension Scale + * - If \p did is a Dimension Scale (A Dimension Scale cannot have scales.) + * + */ H5_HLDLL htri_t H5DSis_attached(hid_t did, hid_t dsid, unsigned int idx); #ifdef __cplusplus diff --git a/libs/windows/include/H5DaccProp.h b/libs/windows/include/H5DaccProp.h index 7d6b250..bb404ce 100644 --- a/libs/windows/include/H5DaccProp.h +++ b/libs/windows/include/H5DaccProp.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -38,7 +37,7 @@ class H5_DLLCPP DSetAccPropList : public LinkAccPropList { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("DSetAccPropList"); } @@ -51,7 +50,7 @@ class H5_DLLCPP DSetAccPropList : public LinkAccPropList { DSetAccPropList(const hid_t plist_id); // Noop destructor. - virtual ~DSetAccPropList(); + virtual ~DSetAccPropList() override; #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/libs/windows/include/H5DataSet.h b/libs/windows/include/H5DataSet.h index 333ed7a..3992350 100644 --- a/libs/windows/include/H5DataSet.h +++ b/libs/windows/include/H5DataSet.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -28,7 +27,7 @@ namespace H5 { class H5_DLLCPP DataSet : public H5Object, public AbstractDs { public: // Close this dataset. - virtual void close(); + virtual void close() override; // Extends the dataset with unlimited dimension. void extend(const hsize_t *size) const; @@ -53,16 +52,16 @@ class H5_DLLCPP DataSet : public H5Object, public AbstractDs { haddr_t getOffset() const; // Gets the dataspace of this dataset. - virtual DataSpace getSpace() const; + virtual DataSpace getSpace() const override; // Determines whether space has been allocated for a dataset. void getSpaceStatus(H5D_space_status_t &status) const; // Returns the amount of storage size required for this dataset. - virtual hsize_t getStorageSize() const; + virtual hsize_t getStorageSize() const override; // Returns the in memory size of this attribute's data. - virtual size_t getInMemDataSize() const; + virtual size_t getInMemDataSize() const override; // Returns the number of bytes required to store VL data. hsize_t getVlenBufSize(const DataType &type, const DataSpace &space) const; @@ -78,20 +77,20 @@ class H5_DLLCPP DataSet : public H5Object, public AbstractDs { // The memory and file dataspaces and the transferring property list // can be defaults. void read(void *buf, const DataType &mem_type, const DataSpace &mem_space = DataSpace::ALL, - const DataSpace & file_space = DataSpace::ALL, + const DataSpace &file_space = DataSpace::ALL, const DSetMemXferPropList &xfer_plist = DSetMemXferPropList::DEFAULT) const; void read(H5std_string &buf, const DataType &mem_type, const DataSpace &mem_space = DataSpace::ALL, - const DataSpace & file_space = DataSpace::ALL, + const DataSpace &file_space = DataSpace::ALL, const DSetMemXferPropList &xfer_plist = DSetMemXferPropList::DEFAULT) const; // Writes the buffered data to this dataset. // The memory and file dataspaces and the transferring property list // can be defaults. void write(const void *buf, const DataType &mem_type, const DataSpace &mem_space = DataSpace::ALL, - const DataSpace & file_space = DataSpace::ALL, + const DataSpace &file_space = DataSpace::ALL, const DSetMemXferPropList &xfer_plist = DSetMemXferPropList::DEFAULT) const; void write(const H5std_string &buf, const DataType &mem_type, const DataSpace &mem_space = DataSpace::ALL, - const DataSpace & file_space = DataSpace::ALL, + const DataSpace &file_space = DataSpace::ALL, const DSetMemXferPropList &xfer_plist = DSetMemXferPropList::DEFAULT) const; // Iterates the selected elements in the specified dataspace - not implemented in C++ style yet @@ -100,7 +99,7 @@ class H5_DLLCPP DataSet : public H5Object, public AbstractDs { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("DataSet"); } @@ -124,15 +123,15 @@ class H5_DLLCPP DataSet : public H5Object, public AbstractDs { DataSet(const hid_t existing_id); // Gets the dataset id. - virtual hid_t getId() const; + virtual hid_t getId() const override; // Destructor: properly terminates access to this dataset. - virtual ~DataSet(); + virtual ~DataSet() override; protected: #ifndef DOXYGEN_SHOULD_SKIP_THIS // Sets the dataset id. - virtual void p_setId(const hid_t new_id); + virtual void p_setId(const hid_t new_id) override; #endif // DOXYGEN_SHOULD_SKIP_THIS private: @@ -142,7 +141,7 @@ class H5_DLLCPP DataSet : public H5Object, public AbstractDs { // getTypeClass and various API functions getXxxType // defined in AbstractDs for generic datatype and specific // sub-types - virtual hid_t p_get_type() const; + virtual hid_t p_get_type() const override; // Reads variable or fixed len strings from this dataset. void p_read_fixed_len(const hid_t mem_type_id, const hid_t mem_space_id, const hid_t file_space_id, diff --git a/libs/windows/include/H5DataSpace.h b/libs/windows/include/H5DataSpace.h index 470de74..136a8ea 100644 --- a/libs/windows/include/H5DataSpace.h +++ b/libs/windows/include/H5DataSpace.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -43,7 +42,7 @@ class H5_DLLCPP DataSpace : public IdComponent { DataSpace &operator=(const DataSpace &rhs); // Closes this dataspace. - virtual void close() H5_OVERRIDE; + virtual void close() override; // Makes copy of an existing dataspace. void copy(const DataSpace &like_space); @@ -115,25 +114,25 @@ class H5_DLLCPP DataSpace : public IdComponent { ///\brief Returns this class name. virtual H5std_string - fromClass() const H5_OVERRIDE + fromClass() const override { return ("DataSpace"); } // Gets the dataspace id. - virtual hid_t getId() const H5_OVERRIDE; + virtual hid_t getId() const override; // Deletes the global constant static void deleteConstants(); // Destructor: properly terminates access to this dataspace. - virtual ~DataSpace(); + virtual ~DataSpace() override; #ifndef DOXYGEN_SHOULD_SKIP_THIS protected: // Sets the dataspace id. - virtual void p_setId(const hid_t new_id) H5_OVERRIDE; + virtual void p_setId(const hid_t new_id) override; #endif // DOXYGEN_SHOULD_SKIP_THIS diff --git a/libs/windows/include/H5DataType.h b/libs/windows/include/H5DataType.h index 49f5348..7cc1d31 100644 --- a/libs/windows/include/H5DataType.h +++ b/libs/windows/include/H5DataType.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -47,7 +46,7 @@ class H5_DLLCPP DataType : public H5Object { // PropList& plist = PropList::DEFAULT); // Closes this datatype. - virtual void close(); + virtual void close() override; // Copies an existing datatype to this datatype object. void copy(const DataType &like_type); @@ -133,7 +132,7 @@ class H5_DLLCPP DataType : public H5Object { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("DataType"); } @@ -148,10 +147,10 @@ class H5_DLLCPP DataType : public H5Object { bool hasBinaryDesc() const; // Gets the datatype id. - virtual hid_t getId() const; + virtual hid_t getId() const override; // Destructor: properly terminates access to this datatype. - virtual ~DataType(); + virtual ~DataType() override; protected: #ifndef DOXYGEN_SHOULD_SKIP_THIS @@ -162,7 +161,7 @@ class H5_DLLCPP DataType : public H5Object { hid_t p_decode() const; // Sets the datatype id. - virtual void p_setId(const hid_t new_id); + virtual void p_setId(const hid_t new_id) override; // Opens a datatype and returns the id. hid_t p_opentype(const H5Location &loc, const char *dtype_name) const; diff --git a/libs/windows/include/H5DcreatProp.h b/libs/windows/include/H5DcreatProp.h index 3c032ee..94ecbb5 100644 --- a/libs/windows/include/H5DcreatProp.h +++ b/libs/windows/include/H5DcreatProp.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -128,7 +127,7 @@ class H5_DLLCPP DSetCreatPropList : public ObjCreatPropList { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("DSetCreatPropList"); } @@ -141,7 +140,7 @@ class H5_DLLCPP DSetCreatPropList : public ObjCreatPropList { DSetCreatPropList(const hid_t plist_id); // Noop destructor. - virtual ~DSetCreatPropList(); + virtual ~DSetCreatPropList() override; #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/libs/windows/include/H5Dpublic.h b/libs/windows/include/H5Dpublic.h index b73e62d..a4c60cd 100644 --- a/libs/windows/include/H5Dpublic.h +++ b/libs/windows/include/H5Dpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -17,22 +16,21 @@ #ifndef H5Dpublic_H #define H5Dpublic_H -/* System headers needed by this file */ - -/* Public headers needed by this file */ -#include "H5public.h" -#include "H5Ipublic.h" +#include "H5public.h" /* Generic Functions */ +#include "H5Ipublic.h" /* Identifiers */ /*****************/ /* Public Macros */ /*****************/ /* Macros used to "unset" chunk cache configuration parameters */ -#define H5D_CHUNK_CACHE_NSLOTS_DEFAULT ((size_t)-1) -#define H5D_CHUNK_CACHE_NBYTES_DEFAULT ((size_t)-1) -#define H5D_CHUNK_CACHE_W0_DEFAULT (-1.0f) +#define H5D_CHUNK_CACHE_NSLOTS_DEFAULT SIZE_MAX +#define H5D_CHUNK_CACHE_NBYTES_DEFAULT SIZE_MAX +#define H5D_CHUNK_CACHE_W0_DEFAULT (-1.0) -/* Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts() */ +/** + * Bit flags for the H5Pset_chunk_opts() and H5Pget_chunk_opts() + */ #define H5D_CHUNK_DONT_FILTER_PARTIAL_CHUNKS (0x0002u) /*******************/ @@ -44,13 +42,12 @@ * 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_LAYOUT_ERROR = -1, /**< error */ + H5D_COMPACT = 0, /**< raw data is small (< 64KB) */ + H5D_CONTIGUOUS = 1, /**< contiguous layout */ + H5D_CHUNKED = 2, /**< chunked or tiled layout */ + H5D_VIRTUAL = 3, /**< actual data is stored in other datasets */ + H5D_NLAYOUTS = 4 /**< this one must be last! */ } H5D_layout_t; //! @@ -75,11 +72,11 @@ typedef enum H5D_chunk_index_t { * Values for the space allocation time property */ typedef enum H5D_alloc_time_t { - H5D_ALLOC_TIME_ERROR = -1, - H5D_ALLOC_TIME_DEFAULT = 0, - H5D_ALLOC_TIME_EARLY = 1, - H5D_ALLOC_TIME_LATE = 2, - H5D_ALLOC_TIME_INCR = 3 + H5D_ALLOC_TIME_ERROR = -1, /**< Error */ + H5D_ALLOC_TIME_DEFAULT = 0, /**< Default (layout dependent) */ + H5D_ALLOC_TIME_EARLY = 1, /**< Allocate on creation */ + H5D_ALLOC_TIME_LATE = 2, /**< Allocate on first write */ + H5D_ALLOC_TIME_INCR = 3 /**< Allocate incrementally (by chunk) */ } H5D_alloc_time_t; //! @@ -88,10 +85,11 @@ typedef enum H5D_alloc_time_t { * 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_ERROR = -1, /**< Error */ + H5D_SPACE_STATUS_NOT_ALLOCATED = 0, /**< Space has not been allocated for this dataset. */ + H5D_SPACE_STATUS_PART_ALLOCATED = 1, /**< Space has been partially allocated for this dataset. + (Used only for datasets with chunked storage.) */ + H5D_SPACE_STATUS_ALLOCATED = 2 /**< Space has been allocated for this dataset. */ } H5D_space_status_t; //! @@ -100,10 +98,10 @@ typedef enum H5D_space_status_t { * 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_ERROR = -1, /**< Error */ + H5D_FILL_TIME_ALLOC = 0, /**< Fill on allocation */ + H5D_FILL_TIME_NEVER = 1, /**< Never write fill values */ + H5D_FILL_TIME_IFSET = 2 /**< Fill if fill-value was set */ } H5D_fill_time_t; //! @@ -112,10 +110,10 @@ typedef enum H5D_fill_time_t { * 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_ERROR = -1, /**< Error */ + H5D_FILL_VALUE_UNDEFINED = 0, /**< No fill value defined */ + H5D_FILL_VALUE_DEFAULT = 1, /**< Default fill-value */ + H5D_FILL_VALUE_USER_DEFINED = 2 /**< User-defined fill-value */ } H5D_fill_value_t; //! @@ -124,22 +122,40 @@ typedef enum H5D_fill_value_t { * 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_ERROR = -1, /**< Error */ + H5D_VDS_FIRST_MISSING = 0, /**< Include all data before the first missing mapped data */ + H5D_VDS_LAST_AVAILABLE = 1 /**< Include all available mapped data */ } H5D_vds_view_t; //! //! /** - * Callback for H5Pset_append_flush() in a dataset access property list + * \brief Callback for H5Pset_append_flush() + * + * \dset_id{dataset_id} + * \param[in] cur_dims The current extent of the dataset's dimensions + * \param[in,out] op_data User context + * + * \return \herr_t + * */ typedef herr_t (*H5D_append_cb_t)(hid_t dataset_id, hsize_t *cur_dims, void *op_data); //! //! /** - * Define the operator function pointer for H5Diterate() + * \brief Callback for H5Diterate() + * + * \param[in,out] elem Pointer to the memory buffer containing the current dataset + * element + * \param[in] type_id Datatype identifier of the elements stored in \p elem + * \param[in] ndim Number of dimensions for the \p point array + * \param[in] point Array containing the location of the element within + * the original dataspace + * \param[in,out] operator_data Pointer to any user-defined data associated with + * the operation + * \return \herr_t_iter + * */ typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const hsize_t *point, void *operator_data); @@ -147,7 +163,29 @@ typedef herr_t (*H5D_operator_t)(void *elem, hid_t type_id, unsigned ndim, const //! /** - * Define the operator function pointer for H5Dscatter() + * \brief Callback for H5Dscatter() + * + * \param[out] src_buf Pointer to the buffer holding the next set of elements to + * scatter. On entry, the value of where \p src_buf points to + * is undefined. The callback function should set \p src_buf + * to point to the next set of elements. + * \param[out] src_buf_bytes_used Pointer to the number of valid bytes in \p src_buf. + * On entry, the value where \p src_buf_bytes_used points + * to is undefined. The callback function should set + * \p src_buf_bytes_used to the of valid bytes in \p src_buf. + * This number must be a multiple of the datatype size. + * \param[in,out] op_data User-defined pointer to data required by the callback + * function. A pass-through of the \p op_data pointer provided + * with the H5Dscatter() function call. + * \return herr_t + * + * \details The callback function should always return at least one + * element in \p src_buf, and must not return more elements + * than are remaining to be scattered. This function will be + * repeatedly called until all elements to be scattered have + * been returned. The callback function should return zero (0) + * to indicate success, and a negative value to indicate failure. + * */ typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_buf_bytes_used /*out*/, void *op_data); @@ -155,11 +193,52 @@ typedef herr_t (*H5D_scatter_func_t)(const void **src_buf /*out*/, size_t *src_b //! /** - * Define the operator function pointer for H5Dgather() + * \brief Callback for H5Dgather() + * + * \param[in] dst_buf Pointer to the destination buffer which has been filled + * with the next set of elements gathered. This will always + * be identical to the \p dst_buf passed to H5Dgather() + * \param[in] dst_buf_bytes_used Pointer to the number of valid bytes in + * \p dst_buf. This number must be a multiple of + * the datatype size. + * \param[in,out] op_data User-defined pointer to data required by the callback + * function; a pass-through of the \p op_data pointer + * provided with the H5Dgather() function call. + * \returns \herr_t + * + * \details The callback function should process, store, or otherwise make use + * of the data returned in dst_buf before it returns, because the + * buffer will be overwritten unless it is the last call to the + * callback. This function will be repeatedly called until all gathered + * elements have been passed to the callback in dst_buf. The callback + * function should return zero (0) to indicate success, and a negative + * value to indicate failure. + * */ typedef herr_t (*H5D_gather_func_t)(const void *dst_buf, size_t dst_buf_bytes_used, void *op_data); //! +//! +/** + * \brief Callback for H5Dchunk_iter() + * + * \param[in] offset Logical position of the chunk's first element in units of dataset elements + * \param[in] filter_mask Bitmask indicating the filters used when the chunk was written + * \param[in] addr Chunk address in the file + * \param[in] size Chunk size in bytes, 0 if the chunk does not exist + * \param[in,out] op_data Pointer to any user-defined data associated with + * the operation. + * \returns \li Zero (#H5_ITER_CONT) causes the iterator to continue, returning + * zero when all elements have been processed. + * \li A positive value (#H5_ITER_STOP) causes the iterator to + * immediately return that value, indicating short-circuit success. + * \li A negative (#H5_ITER_ERROR) causes the iterator to immediately + * return that value, indicating failure. + */ +typedef int (*H5D_chunk_iter_op_t)(const hsize_t *offset, unsigned filter_mask, haddr_t addr, hsize_t size, + void *op_data); +//! + /********************/ /* Public Variables */ /********************/ @@ -178,7 +257,7 @@ extern "C" { * \brief Creates a new dataset and links it into the file * * \fgdta_loc_id - * \param[in] name Name of the dataset to create + * \param[in] name Name of the dataset to create * \type_id * \space_id * \lcpl_id @@ -197,39 +276,32 @@ extern "C" { * * \p loc_id may specify a file, group, dataset, named datatype, * or attribute. If an attribute, dataset, or named datatype is - * specified then the dataset will be created at the location + * specified, then the dataset will be created at the location * where the attribute, dataset, or named datatype is attached. * * \p name may be either an absolute path in the file or a relative * path from \p loc_id naming the dataset. * - * \p dtype_id specifies the datatype of each data element as stored - * in the file. If \p dtype_id is either a fixed-length or - * variable-length string, it is important to set the string length - * when defining the datatype. String datatypes are derived from - * #H5T_C_S1 (or #H5T_FORTRAN_S1 for Fortran codes), which defaults - * to 1 character in size. - * * If \p dtype_id is a committed datatype, and if the file location * associated with the committed datatype is different from the * file location where the dataset will be created, the datatype * is copied and converted to a transient type. * - * The link creation property list, \p lcpl_id, governs creation + * The link creation property list, \p lcpl_id, governs the creation * of the link(s) by which the new dataset is accessed and the - * creation of any * intermediate groups that may be missing. + * creation of any intermediate groups that may be missing. * * The datatype and dataspace properties and the dataset creation * and access property lists are attached to the dataset, so the * caller may derive new datatypes, dataspaces, and creation and * access properties from the old ones and reuse them in calls to * create additional datasets. Once created, the dataset can be - * read from or written to. Reading data from a datatset that was + * read from or written to. Reading data from a dataset that was * not previously written, the HDF5 library will return default * or user-defined fill values. * - * To conserve and release resources, the dataset should be closed - * when access is no longer required. + * \par Example + * \snippet H5D_examples.c create * * \since 1.8.0 * @@ -239,6 +311,20 @@ extern "C" { H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, hid_t dcpl_id, hid_t dapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Dcreate} + */ +#ifndef H5_DOXYGEN +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, + hid_t dapl_id, hid_t es_id); +#else +H5_DLL hid_t H5Dcreate_async(hid_t loc_id, const char *name, hid_t type_id, hid_t space_id, hid_t lcpl_id, + hid_t dcpl_id, hid_t dapl_id, hid_t es_id); +#endif + /** * -------------------------------------------------------------------------- * \ingroup H5D @@ -259,43 +345,23 @@ H5_DLL hid_t H5Dcreate2(hid_t loc_id, const char *name, hid_t type_id, hid_t spa * * \p loc_id may specify a file, group, dataset, named datatype, * or attribute. If an attribute, dataset, or named datatype is - * specified then the dataset will be created at the location + * specified, then the dataset will be created at the location * where the attribute, dataset, or named datatype is attached. * - * The dataset’s datatype and dataspace are specified by + * 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 + * datatype and dataspace of the dataset as they will exist in * the file, which may differ from the datatype and dataspace * in application memory. * - * Dataset creation property list and dataset access creation - * property list are specified by \p dcpl_id and \p dapl_id. - * * H5Dcreate_anon() returns a new dataset identifier. Using * this identifier, the new dataset must be linked into the * HDF5 file structure with H5Olink() or it will be deleted - * from the file when the file is closed. - * - * See H5Dcreate2() for further details and considerations on - * the use of H5Dcreate2() and H5Dcreate_anon(). - * - * The differences between this function and H5Dcreate2() are - * as follows: - * \li H5Dcreate_anon() explicitly includes a dataset access property - * list. H5Dcreate() always uses default dataset access properties. - * - * \li H5Dcreate_anon() neither provides the new dataset’s name nor - * links it into the HDF5 file structure; those actions must be - * performed separately through a call to H5Olink(), which offers - * greater control over linking. - * - * A dataset created with this function should be closed with - * H5Dclose() when the dataset is no longer needed so that resource - * leaks will not develop. + * when the file is closed. * * \since 1.8.0 * - * \see H5Olink(), H5Dcreate(), Using Identifiers + * \see H5Olink(), H5Dcreate() * */ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id); @@ -304,7 +370,7 @@ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t d * -------------------------------------------------------------------------- * \ingroup H5D * - * \brief Creates a new dataset and links it into the file + * \brief Opens an existing dataset * * \fgdta_loc_id * \param[in] name Name of the dataset to open @@ -321,12 +387,6 @@ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t d * specified then the dataset will be opened at the location * where the attribute, dataset, or named datatype is attached. * - * The dataset access property list, \p dapl_id, provides - * information regarding access to the dataset. - * - * To conserve and release resources, the dataset should be closed - * when access is no longer required. - * * \since 1.8.0 * * \see H5Dcreate2(), H5Dclose() @@ -334,6 +394,18 @@ H5_DLL hid_t H5Dcreate_anon(hid_t loc_id, hid_t type_id, hid_t space_id, hid_t d */ H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Dopen} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Dopen_async(hid_t loc_id, const char *name, hid_t dapl_id, hid_t es_id); +#endif + /** * -------------------------------------------------------------------------- *\ingroup H5D @@ -352,15 +424,56 @@ H5_DLL hid_t H5Dopen2(hid_t loc_id, const char *name, hid_t dapl_id); * be released with H5Sclose() when the identifier is no longer * needed so that resource leaks will not occur. * + * \par Example + * \snippet H5D_examples.c update + * * \see H5Sclose() * */ H5_DLL hid_t H5Dget_space(hid_t dset_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Dget_space} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Dget_space_async(hid_t dset_id, hid_t es_id); +#endif + /** * -------------------------------------------------------------------------- * \ingroup H5D - * \todo Document this function! + * + * \brief Determines whether space has been allocated for a dataset + * + * \dset_id + * \param[out] allocation Space allocation status + * + * \return \herr_t + * + * \details H5Dget_space_status() determines whether space has been allocated + * for the dataset \p dset_id. + * + * \note \Bold{BUG:} Prior to the HDF5 1.14.0, 1.12.2 and 1.10.9 releases, + * H5Dget_space_status() may return incorrect space allocation status + * values for datasets with filters applied to them. + * H5Dget_space_status() calculated the space allocation status by + * comparing the sum of the sizes of all the allocated chunks in the + * dataset against the total data size of the dataset, as calculated by + * the number of elements in the dataset's dataspace multiplied by the + * dataset's datatype size. If the dataset had any compression filters + * applied to it and the dataset chunks were successfully compressed, + * the sum of the sizes of the allocated dataset chunks would generally + * always be less than the total data size of the dataset, and + * H5Dget_space_status() wouldn't ever return + * `H5D_SPACE_STATUS_ALLOCATED`. + * + * \since 1.6.0 + * */ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation); @@ -379,27 +492,7 @@ H5_DLL herr_t H5Dget_space_status(hid_t dset_id, H5D_space_status_t *allocation) * * If a dataset has a named datatype, then an identifier to the * opened datatype is returned. Otherwise, the returned datatype - * is read-only. If atomization of the datatype fails, then the - * datatype is closed. - * - * A datatype identifier returned from this function should be - * released with H5Tclose() when the identifier is no longer - * needed to prevent resource leaks. - * - * \note Datatype Identifiers - * - * Please note that the datatype identifier is actually an object - * identifier or a handle returned from opening the datatype. It - * is not persistent and its value can be different from one HDF5 - * session to the next. - * - * H5Tequal() can be used to compare datatypes. - * - * HDF5 High Level APIs that may also be of interest are: - * - * H5LTdtype_to_text() creates a text description of a - * datatype. H5LTtext_to_dtype() creates an HDF5 datatype - * given a text description. + * is read-only. * */ H5_DLL hid_t H5Dget_type(hid_t dset_id); @@ -419,8 +512,8 @@ H5_DLL hid_t H5Dget_type(hid_t dset_id); * a copy of the dataset creation property list associated with * the dataset specified by \p dset_id. * - * The creation property list identifier should be released - * with H5Pclose() to prevent resource leaks. + * The creation property list identifier should be released with + * H5Pclose() to prevent resource leaks. * */ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id); @@ -450,15 +543,11 @@ H5_DLL hid_t H5Dget_create_plist(hid_t dset_id); * cache properties will be set to the default. The chunk cache * properties in the returned list are considered to be “set”, * and any use of this list will override the corresponding - * properties in the file’s file access property list. + * properties in the file's file access property list. * * All link access properties in the returned list will be set * to the default values. * - * The access property list identifier should be released with - * H5Pclose() when the identifier is no longer needed so that - * resource leaks will not develop. - * * \since 1.8.3 * */ @@ -477,11 +566,8 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id); * \details H5Dget_storage_size() returns the amount of storage, * in bytes, that is allocated in the file for the raw data of * the dataset specified by \p dset_id. - * - * \note The amount of storage in this case is the storage - * allocated in the written file, which will typically differ - * from the space required to hold a dataset in working memory. - * + * H5Dget_storage_size() reports only the space required to store + * the dataset elements, excluding any metadata. * \li For contiguous datasets, the returned size equals the current * allocated size of the raw data. * \li For unfiltered chunked datasets, the returned size is the @@ -491,21 +577,19 @@ H5_DLL hid_t H5Dget_access_plist(hid_t dset_id); * compression filter is in use, H5Dget_storage_size() will return * the total space required to store the compressed chunks. * - * H5Dget_storage_size() reports only the space required to store - * the data, not including that of any metadata. + * \note Note that H5Dget_storage_size() is not generally an + * appropriate function to use when determining the amount + * of memory required to work with a dataset. In such + * circumstances, you must determine the number of data + * points in a dataset and the size of an individual dataset + * element. H5Sget_simple_extent_npoints() and H5Tget_size() + * can be used to calculate that amount. * - * \attention H5Dget_storage_size() does not differentiate between 0 (zero), + * \warning H5Dget_storage_size() does not differentiate between 0 (zero), * the value returned for the storage size of a dataset * with no stored values, and 0 (zero), the value returned to * indicate an error. * - * \note Note that H5Dget_storage_size() is not generally an - * appropriate function to use when determining the amount - * of memory required to work with a dataset. In such - * circumstances, you must determine the number of data - * points in a dataset and the size of an individual data - * element. H5Sget_simple_extent_npoints() and H5Tget_size() - * can be used to get that information. * */ H5_DLL hsize_t H5Dget_storage_size(hid_t dset_id); @@ -562,7 +646,7 @@ H5_DLL herr_t H5Dget_chunk_storage_size(hid_t dset_id, const hsize_t *offset, hs * effect. Also, the implementation does not handle the #H5S_ALL * macro correctly. As a workaround, application can get * the dataspace for the dataset using H5Dget_space() and pass that - * in for \p fspace_id. This will be fixed in coming releases. + * in for \p fspace_id. This will be fixed in a future release. * * \since 1.10.5 * @@ -576,10 +660,10 @@ H5_DLL herr_t H5Dget_num_chunks(hid_t dset_id, hid_t fspace_id, hsize_t *nchunks * \brief Retrieves information about a chunk specified by its coordinates * * \dset_id - * \param[in] offset Logical position of the chunk’s first element - * \param[out] filter_mask Indicating filters used with the chunk when written + * \param[in] offset Logical position of the chunk's first element in units of dataset elements + * \param[out] filter_mask Bitmask indicating the filters used when the chunk was written * \param[out] addr Chunk address in the file - * \param[out] size Chunk size in bytes, 0 if chunk doesn’t exist + * \param[out] size Chunk size in bytes, 0 if the chunk does not exist * * \return \herr_t * @@ -592,8 +676,8 @@ H5_DLL herr_t H5Dget_num_chunks(hid_t dset_id, hid_t fspace_id, hsize_t *nchunks * filter_mask will not be modified. * * \p offset is a pointer to a one-dimensional array with a size - * equal to the dataset’s rank. Each element is the logical - * position of the chunk’s first element in a dimension. + * equal to the dataset's rank. Each element is the logical + * position of the chunk's first element in a dimension. * * \since 1.10.5 * @@ -601,6 +685,34 @@ H5_DLL herr_t H5Dget_num_chunks(hid_t dset_id, hid_t fspace_id, hsize_t *nchunks H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, unsigned *filter_mask, haddr_t *addr, hsize_t *size); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Iterate over all chunks of a chunked dataset + * + * \dset_id + * \param[in] dxpl_id Identifier of a transfer property list + * \param[in] cb User callback function, called for every chunk. + * \param[in] op_data User-defined pointer to data required by op + * + * \return \herr_t + * + * \details H5Dchunk_iter iterates over all chunks in the dataset, calling the + * user supplied callback with the details of the chunk and the supplied + * context \p op_data. + * + * \par Example + * For each chunk, print the allocated chunk size (0 for unallocated chunks). + * \snippet H5D_examples.c H5Dchunk_iter_cb + * Iterate over all chunked datasets and chunks in a file. + * \snippet H5D_examples.c H5Ovisit_cb + * + * \since 1.14.0 + * + */ +H5_DLL herr_t H5Dchunk_iter(hid_t dset_id, hid_t dxpl_id, H5D_chunk_iter_op_t cb, void *op_data); + /** * -------------------------------------------------------------------------- * \ingroup H5D @@ -610,39 +722,39 @@ H5_DLL herr_t H5Dget_chunk_info_by_coord(hid_t dset_id, const hsize_t *offset, u * \dset_id * \param[in] fspace_id File dataspace selection identifier (See Note below) * \param[in] chk_idx Index of the chunk - * \param[out] offset Logical position of the chunk’s first element - * \param[out] filter_mask Indicating filters used with the chunk when written + * \param[out] offset Logical position of the chunk's first element in units of dataset elements + * \param[out] filter_mask Bitmask indicating the filters used when the chunk was written * \param[out] addr Chunk address in the file - * \param[out] size Chunk size in bytes, 0 if chunk doesn’t exist + * \param[out] size Chunk size in bytes, 0 if the chunk does not exist * * \return \herr_t * - * \details H5Dget_chunk_info() retrieves the offset coordinates - * offset, filter mask filter_mask, size size and address addr for - * the dataset specified by the identifier dset_id and the chunk - * specified by the index index. The chunk belongs to a set of - * chunks in the selection specified by fspace_id. If the queried + * \details H5Dget_chunk_info() retrieves the offset coordinates, + * \p offset, filter mask, \p filter_mask, size, \p size, and address + * \p addr for the dataset specified by the identifier \p dset_id and the chunk + * specified by the index \p index. The chunk belongs to a set of + * chunks in the selection specified by \p fspace_id. If the queried * chunk does not exist in the file, the size will be set to 0 and - * 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. + * address to #HADDR_UNDEF. The value pointed to by filter_mask will + * not be modified. \c NULL can be passed in for any \p out parameters. * - * \p chk_idx is the chunk index in the selection. Index value + * \p chk_idx is the chunk index in the selection. The index value * may have a value of 0 up to the number of chunks stored in - * the file that have a nonempty intersection with the file - * dataspace selection + * the file that has a nonempty intersection with the file + * dataspace selection. * * \note As of 1.10.5, the dataspace intersection is not yet - * supported, hence, the index is of all the written chunks. + * supported. Hence, the index is of all the written chunks. * * \p fspace_id specifies the file dataspace selection. It is - * intended to take #H5S_ALL for specifying the current selection. + * intended to take #H5S_ALL to specify the current selection. * * \note Please be aware that this function currently does not - * support non-trivial selections, thus \p fspace_id has no + * support non-trivial selections; thus \p fspace_id has no * effect. Also, the implementation does not handle the #H5S_ALL - * macro correctly. As a workaround, application can get + * macro correctly. As a workaround, an application can get * the dataspace for the dataset using H5Dget_space() and pass that - * in for \p fspace_id. This will be fixed in coming releases. + * in for \p fspace_id. This will be fixed in a future release. * * \since 1.10.5 * @@ -658,7 +770,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 \c HADDR_UNDEF, + * \return Returns the offset in bytes; otherwise, returns #HADDR_UNDEF, * a negative value. * * \details H5Dget_offset() returns the address in the file of @@ -707,9 +819,8 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id); * used for the memory dataspace and the selection defined with \p * file_space_id is used for the selection within that dataspace. * - * If raw data storage space has not been allocated for the dataset - * and a fill value has been defined, the returned buffer \p buf - * is filled with the fill value. + * The number of elements selected in the memory dataspace \Emph{must} + * be equal to the number of elements selected in the file dataspace. * * The behavior of the library for the various combinations of * valid dataspace identifiers and #H5S_ALL for the \p mem_space_id @@ -754,19 +865,91 @@ H5_DLL haddr_t H5Dget_offset(hid_t dset_id); * * * - * \details Setting an #H5S_ALL selection indicates that the entire - * dataspace, as defined by the current dimensions of a dataspace, - * will be selected. The number of elements selected in the memory - * dataspace must match the number of elements selected in the - * file dataspace. + * \note If no storage space was allocated for the dataset + * and a fill value is defined, the returned buffer \p buf + * is filled with the fill value. * - * \p dxpl_id can be the constant #H5P_DEFAULT, in which case the - * default data transfer properties are used. + * \par Example + * \snippet H5D_examples.c read * */ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, void *buf /*out*/); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Reads raw data from a set of datasets into the provided buffers + * + * \param[in] count Number of datasets to read from + * \param[in] dset_id Identifiers of the datasets to read from + * \param[in] mem_type_id Identifiers of the memory datatypes + * \param[in] mem_space_id Identifiers of the memory dataspaces + * \param[in] file_space_id Identifiers of the datasets' dataspaces in the file + * \param[in] dxpl_id Identifier of a transfer property list + * \param[out] buf Buffers to receive data read from file + * + * \return \herr_t + * + * \details H5Dread_multi() reads data from \p count datasets, whose identifiers + * are listed in the \p dset_id array, from the file into multiple + * application memory buffers listed in the \p buf array. Data transfer + * properties are defined by the argument \p dxpl_id. The memory + * datatypes of each dataset are listed by identifier in the \p + * mem_type_id array. The parts of each dataset to read are listed by + * identifier in the \p file_space_id array, and the parts of each + * application memory buffer to read to are listed by identifier in the + * \p mem_space_id array. All array parameters have length \p count. + * + * This function will produce the same results as \p count calls to + * H5Dread(). Information listed in that function about the specifics + * of its behavior also applies to H5Dread_multi(). By calling + * H5Dread_multi() instead of multiple calls to H5Dread(), however, the + * library can in some cases pass information about the entire I/O + * operation to the file driver, which can improve performance. + * + * All datasets must be in the same HDF5 file, and each unique dataset + * may only be listed once. If this function is called collectively in + * parallel, each rank must pass exactly the same list of datasets in + * \p dset_id , though the other parameters may differ. + * + * \since 1.14.0 + * + * \see H5Dread() + * + */ +H5_DLL herr_t H5Dread_multi(size_t count, hid_t dset_id[], hid_t mem_type_id[], hid_t mem_space_id[], + hid_t file_space_id[], hid_t dxpl_id, void *buf[] /*out*/); + +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Dread} + */ +#ifndef H5_DOXYGEN +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, + void *buf /*out*/, hid_t es_id); +#else +H5_DLL herr_t H5Dread_async(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, + hid_t dxpl_id, void *buf /*out*/, hid_t es_id); +#endif + +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Dread_multi} + */ +#ifndef H5_DOXYGEN +H5_DLL herr_t H5Dread_multi_async(const char *app_file, const char *app_func, unsigned app_line, size_t count, + hid_t dset_id[], hid_t mem_type_id[], hid_t mem_space_id[], + hid_t file_space_id[], hid_t dxpl_id, void *buf[] /*out*/, hid_t es_id); +#else +H5_DLL herr_t H5Dread_multi_async(size_t count, hid_t dset_id[], hid_t mem_type_id[], hid_t mem_space_id[], + hid_t file_space_id[], hid_t dxpl_id, void *buf[] /*out*/, hid_t es_id); +#endif + /** * -------------------------------------------------------------------------- * \ingroup H5D @@ -865,6 +1048,8 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_ * time if the dataset's fill time is set to #H5D_FILL_TIME_IFSET * or #H5D_FILL_TIME_ALLOC. * + * \par_compr_note + * * \attention If a dataset's storage layout is 'compact', care must be * taken when writing data to the dataset in parallel. A compact * dataset's raw data is cached in memory and may be flushed @@ -872,12 +1057,90 @@ H5_DLL herr_t H5Dread(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_ * applications should always attempt to write identical data to * the dataset from all processes. * + * \par Example + * \snippet H5D_examples.c update + * * \see H5Pset_fill_time(), H5Pset_alloc_time() * */ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, const void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5D + * + * \brief Writes raw data from a set buffers to a set of datasets + * + * \param[in] count Number of datasets to write to + * \param[in] dset_id Identifiers of the datasets to write to + * \param[in] mem_type_id Identifiers of the memory datatypes + * \param[in] mem_space_id Identifiers of the memory dataspaces + * \param[in] file_space_id Identifiers of the datasets' dataspaces in the file + * \param[in] dxpl_id Identifier of a transfer property list + * \param[in] buf Buffers with data to be written to the file + * + * \return \herr_t + * + * \details H5Dwrite_multi() writes data to \p count datasets, whose identifiers + * are listed in the \p dset_id array, from multiple application memory + * buffers listed in the \p buf array. Data transfer properties are + * defined by the argument \p dxpl_id. The memory datatypes of each + * dataset are listed by identifier in the \p mem_type_id array. The + * parts of each dataset to write are listed by identifier in the \p + * file_space_id array, and the parts of each application memory buffer + * to write from are listed by identifier in the \p mem_space_id array. + * All array parameters have length \p count. + * + * This function will produce the same results as \p count calls to + * H5Dwrite(). Information listed in that function's documentation + * about the specifics of its behaviour also apply to H5Dwrite_multi(). + * By calling H5Dwrite_multi() instead of multiple calls to H5Dwrite(), + * however, the library can in some cases pass information about the + * entire I/O operation to the file driver, which can improve + * performance. + * + * All datasets must be in the same HDF5 file, and each unique dataset + * may only be listed once. If this function is called collectively in + * parallel, each rank must pass exactly the same list of datasets in + * \p dset_id , though the other parameters may differ. + * + * \since 1.14.0 + * + * \see H5Dwrite() + * + */ +H5_DLL herr_t H5Dwrite_multi(size_t count, hid_t dset_id[], hid_t mem_type_id[], hid_t mem_space_id[], + hid_t file_space_id[], hid_t dxpl_id, const void *buf[]); + +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Dwrite} + */ +#ifndef H5_DOXYGEN +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, + const void *buf, hid_t es_id); +#else +H5_DLL herr_t H5Dwrite_async(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, + hid_t dxpl_id, const void *buf, hid_t es_id); +#endif + +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Dwrite_multi} + */ +#ifndef H5_DOXYGEN +H5_DLL herr_t H5Dwrite_multi_async(const char *app_file, const char *app_func, unsigned app_line, + size_t count, hid_t dset_id[], hid_t mem_type_id[], hid_t mem_space_id[], + hid_t file_space_id[], hid_t dxpl_id, const void *buf[], hid_t es_id); +#else +H5_DLL herr_t H5Dwrite_multi_async(size_t count, hid_t dset_id[], hid_t mem_type_id[], hid_t mem_space_id[], + hid_t file_space_id[], hid_t dxpl_id, const void *buf[], hid_t es_id); +#endif + /** * -------------------------------------------------------------------------- * \ingroup H5D @@ -887,7 +1150,7 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid * \dset_id * \dxpl_id * \param[in] filters Mask for identifying the filters in use - * \param[in] offset Logical position of the chunk’s first element in the + * \param[in] offset Logical position of the chunk's first element in the * dataspace * \param[in] data_size Size of the actual data to be written in bytes * \param[in] buf Buffer containing data to be written to the chunk @@ -899,24 +1162,19 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid * from the application memory buffer \p buf to the dataset in * the file. Typically, the data in \p buf is preprocessed in * memory by a custom transformation, such as compression. The - * chunk will bypass the library’s internal data transfer + * chunk will bypass the library's internal data transfer * pipeline, including filters, and will be written directly to * the file. Only one chunk can be written with this function. * - * H5Dwrite_chunk() replaces the now deprecated H5DOwrite_chunk() - * function, which was located in the high level optimization - * library. The parameters and behavior are identical to the - * original. - * * \p filters is a mask providing a record of which filters are - * used with the the chunk. The default value of the mask is + * used with the chunk. The default value of the mask is * zero (0), indicating that all enabled filters are applied. A - * filter is skipped if the bit corresponding to the filter’s + * filter is skipped if the bit corresponding to the filter's * position in the pipeline (0 ≤ position < 32) is turned on. * This mask is saved with the chunk in the file. * * \p offset is an array specifying the logical position of the - * first element of the chunk in the dataset’s dataspace. The + * first element of the chunk in the dataset's dataspace. The * length of the offset array must equal the number of dimensions, * or rank, of the dataspace. The values in offset must not exceed * the dimension limits and must specify a point that falls on @@ -935,11 +1193,10 @@ H5_DLL herr_t H5Dwrite(hid_t dset_id, hid_t mem_type_id, hid_t mem_space_id, hid * in a file. H5Dwrite_chunk() bypasses hyperslab selection, the * conversion of data from one datatype to another, and the filter * pipeline to write the chunk. Developers should have experience - * with these processes before using this function. Please see - * Using the Direct Chunk Write Function for more information. + * with these processes before using this function. * - * \note H5Dread_chunk() and H5Dwrite_chunk() are not supported under - * parallel and do not support variable length types. + * \note H5Dread_chunk() and H5Dwrite_chunk() are currently not supported + * with parallel HDF5 and do not support variable-length types. * * \since 1.10.2 * @@ -956,10 +1213,10 @@ H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, con * * \dset_id * \dxpl_id - * \param[in] offset Logical position of the chunk’s first element in the + * \param[in] offset Logical position of the chunk's first element in the * dataspace * \param[in,out] filters Mask for identifying the filters in use - * \param[out] buf Buffer containing data to be written to the chunk + * \param[out] buf Buffer containing data to be read from the chunk * * \return \herr_t * @@ -967,20 +1224,20 @@ H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, con * its logical offset \p offset in a chunked dataset \p dset_id * from the dataset in the file into the application memory * buffer \p buf. The data in \p buf is read directly from the - * file bypassing the library’s internal data transfer pipeline, + * file bypassing the library's internal data transfer pipeline, * including filters. * * \p offset is an array specifying the logical position of the - * first element of the chunk in the dataset’s dataspace. The + * first element of the chunk in the dataset's dataspace. The * length of the \p offset array must equal the number of dimensions, * or rank, of the dataspace. The values in \p offset must not exceed * the dimension limits and must specify a point that falls on * a dataset chunk boundary. * - * The mask \p filters indicates which filters are used with the - * chunk when written. A zero value indicates that all enabled - * filters are applied on the chunk. A filter is skipped if the - * bit corresponding to the filter’s position in the pipeline + * The mask \p filters indicates which filters were used when the + * chunk was written. A zero value (all bits 0) indicates that all + * enabled filters are applied on the chunk. A filter is skipped if + * the bit corresponding to the filter's position in the pipeline * (0 ≤ position < 32) is turned on. * * \p buf is the memory buffer containing the chunk read from @@ -994,8 +1251,8 @@ H5_DLL herr_t H5Dwrite_chunk(hid_t dset_id, hid_t dxpl_id, uint32_t filters, con * with these processes before using this function. Please see * Using the Direct Chunk Write Function for more information. * - * \note H5Dread_chunk() and H5Dwrite_chunk() are not supported under - * parallel and do not support variable length types. + * \note H5Dread_chunk() and H5Dwrite_chunk() are currently not supported + * with parallel HDF5 and do not support variable-length datatypes. * * \since 1.10.2 * @@ -1025,53 +1282,12 @@ H5_DLL herr_t H5Dread_chunk(hid_t dset_id, hid_t dxpl_id, const hsize_t *offset, * in the memory buffer \p buf, executing the callback function * \p op once for each such data element. * - * The prototype of the callback function \p op is as follows - * (as defined in the source code file H5Lpublic.h): - * \snippet this H5D_operator_t_snip - * The parameters of this callback function are: - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
\c elem[in,out]Pointer to the memory buffer containing the current - * data element
\c type_id[in]Datatype identifier of the elements stored in elem
\c ndim[in]Number of dimensions for the point array
\c point[in]Array containing the location of the element within - * the original dataspace
\c operator_data[in,out]Pointer to any user-defined data associated with the - * operation
- * - * The possible return values from the callback function, and - * the effect ofeach,are as follows: - * - * \li Zero causes the iterator to continue, returning zero - * when all data elements have been processed. - * \li A positive value causes the iterator to immediately - * return that positive value, indicating short-circuit success. - * \li A negative value causes the iterator to immediately return - * that value, indicating failure. - * - * The \p operator_data parameter is a user-defined pointer to - * the data required to process dataset elements in the course - * of the iteration. If operator needs to pass data back to the - * application, such data can be returned in this same buffer. This - * pointer is passed back to each step of the iteration in the - * operator callback function’s operator_data parameter. - * - * Unlike other HDF5 iterators, this iteration operation cannot - * be restarted at the point of exit; a second H5Diterate() - * call will always restart at the beginning. + * \attention Unlike other HDF5 iterators, this iteration operation cannot + * be restarted at the point of exit; a second H5Diterate() + * call will always restart at the beginning. * + * \warning Modifying the selection of \p space_id during iteration + * will lead to undefined behavior. * * \since 1.10.2 * @@ -1120,30 +1336,25 @@ H5_DLL herr_t H5Dvlen_get_buf_size(hid_t dset_id, hid_t type_id, hid_t space_id, * * \return \herr_t * - * \details H5Dfill() fills the dataspace selection in memory, \p space_id, + * \details H5Dfill() fills the dataspace selection, \p space_id, in memory * with the fill value specified in \p fill. If \p fill is NULL, * a fill value of 0 (zero) is used. * * \p fill_type_id specifies the datatype of the fill value. - * \p buf specifies the buffer in which the dataspace elements - * will be written. - * \p buf_type_id specifies the datatype of those data elements. + * \p buf specifies the buffer in which the fill elements + * will be written. \p buf_type_id specifies the datatype of + * those data elements. * * \note Note that if the fill value datatype differs from the memory - * buffer datatype, the fill value will be converted to the memory - * buffer datatype before filling the selection. + * buffer datatype, the fill value will be converted to the memory + * buffer datatype before filling the selection. * * \note Applications sometimes write data only to portions of an - * allocated dataset. It is often useful in such cases to fill - * the unused space with a known fill value. See the following - * function for more information: - * - H5Pset_fill_value() - * - H5Pget_fill_value() - * - H5Pfill_value_defined() - * - H5Pset_fill_time() - * - H5Pget_fill_time() - * - H5Pcreate() - * - H5Pcreate_anon() + * allocated dataset. It is often useful in such cases to fill + * the unused space with a known fill value. + * + * \see H5Pset_fill_value(), H5Pget_fill_value(), H5Pfill_value_defined(), + * H5Pset_fill_time(), H5Pget_fill_time(), H5Pcreate(), H5Dcreate_anon() * */ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf_type_id, hid_t space_id); @@ -1152,7 +1363,7 @@ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf * -------------------------------------------------------------------------- * \ingroup H5D * - * \brief Changes the sizes of a dataset’s dimensions + * \brief Changes the sizes of a dataset's dimensions * * \dset_id * \param[in] size[] Array containing the new magnitude of each dimension @@ -1164,7 +1375,7 @@ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf * chunked dataset \p dset_id to the sizes specified in size. * * \p size is a 1-dimensional array with n elements, where \p n is - * the rank of the dataset’s current dataspace. + * the rank of the dataset's current dataspace. * * This function can be applied to the following datasets: * - A chunked dataset with unlimited dimensions @@ -1179,39 +1390,50 @@ H5_DLL herr_t H5Dfill(const void *fill, hid_t fill_type_id, void *buf, hid_t buf * extended only along the first dimension. * * 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. + * the dataset's space allocation time is set to #H5D_ALLOC_TIME_EARLY. * * Fill values will be written to the dataset in either of the * following situations, but not otherwise: * - * - If the dataset’s fill time is set to #H5D_FILL_TIME_IFSET and a + * - If the dataset's fill time is set to #H5D_FILL_TIME_IFSET and a * fill value is defined (see H5Pset_fill_time() and * H5Pset_fill_value()) - * - If the dataset’s fill time is set to #H5D_FILL_TIME_ALLOC + * - If the dataset's fill time is set to #H5D_FILL_TIME_ALLOC * (see H5Pset_alloc_time()) * - * \note - * \li If the sizes specified in \p size array are smaller than - * the dataset’s current dimension sizes, H5Dset_extent() will reduce - * the dataset’s dimension sizes to the specified values. It is the - * user application’s responsibility to ensure that valuable data is - * not lost as H5Dset_extent() does not check. + * \note If the sizes specified in \p size array are smaller than the dataset's + * current dimension sizes, H5Dset_extent() will reduce the dataset's + * dimension sizes to the specified values. It is the user application's + * responsibility to ensure that valuable data is not lost as + * H5Dset_extent() does not check. * - * \li Except for external datasets, H5Dset_extent() is for use with - * chunked datasets only, not contiguous datasets. + * \note Except for external datasets, H5Dset_extent() is for use with + * chunked datasets only, not contiguous datasets. * - * \li A call to H5Dset_extent() affects the dataspace of a dataset. - * If a dataspace handle was opened for a dataset prior to a call to - * H5Dset_extent() then that dataspace handle will no longer reflect - * the correct dataspace extent of the dataset. H5Dget_space() must - * be called (after closing the previous handle) to obtain the current - * dataspace extent. + * \note A call to H5Dset_extent() affects the dataspace of a dataset. If a + * dataspace handle was opened for a dataset prior to a call to + * H5Dset_extent() then that dataspace handle will no longer reflect the + * correct dataspace extent of the dataset. H5Dget_space() must be called + * (after closing the previous handle) to obtain the current dataspace + * extent. * * \since 1.8.0 * */ H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Dset_extent} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Dset_extent_async(hid_t dset_id, const hsize_t size[], hid_t es_id); +#endif + /** * -------------------------------------------------------------------------- * \ingroup H5D @@ -1232,6 +1454,8 @@ H5_DLL herr_t H5Dset_extent(hid_t dset_id, const hsize_t size[]); * open files. After that, the OS is responsible for ensuring * that the data is actually flushed to disk. * + * \since 1.10.0 + * */ H5_DLL herr_t H5Dflush(hid_t dset_id); @@ -1278,7 +1502,7 @@ H5_DLL herr_t H5Drefresh(hid_t dset_id); * \p op and scatters it to the supplied buffer \p dst_buf in a * manner similar to data being written to a dataset. * - * \p dst_space_id is a dataspace which defines the extent of \p + * \p dst_space_id is a dataspace that defines the extent of \p * dst_buf and the selection within it to scatter the data to. * * \p type_id is the datatype of the data to be scattered in both @@ -1290,40 +1514,7 @@ H5_DLL herr_t H5Drefresh(hid_t dset_id); * * To retrieve the data to be scattered, H5Dscatter() repeatedly * calls \p op, which should return a valid source buffer, until - * enough data to fill the selection has been retrieved. The - * prototype of the callback function \p op is as follows (as - * defined in the source code file H5Dpublic.h): - * \snippet this H5D_scatter_func_t_snip - * The parameters of this callback function are described below: - * - * - * - * - * - * - * - * - * - * - * - *
\c src_buf[out]Pointer to the buffer holding the next set of elements to - * scatter. On entry, the value of where \c src_buf points to - * is undefined. The callback function should set \c src_buf - * to point to the next set of elements.
\c src_buf_bytes_used[out]Pointer to the number of valid bytes in \c src_buf. On - * entry, the value where \c src_buf_bytes_used points to is - * undefined. The callback function should set - * \c src_buf_bytes_used to the of valid bytes in \c src_buf. - * This number must be a multiple of the datatype size. - *
\c op_data[in,out]User-defined pointer to data required by the callback - * function. A pass-through of the \c op_data pointer provided - * with the H5Dscatter() function call.
- * - * The callback function should always return at least one - * element in \p src_buf, and must not return more elements - * than are remaining to be scattered. This function will be - * repeatedly called until all elements to be scattered have - * been returned. The callback function should return zero (0) - * to indicate success, and a negative value to indicate failure. + * enough data to fill the selection has been retrieved. * * \since 1.10.2 * @@ -1368,34 +1559,16 @@ H5_DLL herr_t H5Dscatter(H5D_scatter_func_t op, void *op_data, hid_t type_id, hi * enough to hold all the data if the callback function \p op is * not provided. * - * \p op is a callback function which handles the gathered data. + * \p op is a callback function that handles the gathered data. * It is optional if \p dst_buf is large enough to hold all of the * gathered data; required otherwise. * * If no callback function is provided, H5Dgather() simply gathers * the data into \p dst_buf and returns. If a callback function is * provided, H5Dgather() repeatedly gathers up to \p dst_buf_size - * bytes to process the serialized data. The prototype of the - * callback function \p op is as follows (as defined in the source - * code file H5Dpublic.h): - * \snippet this H5D_gather_func_t_snip - * The parameters of this callback function are described in the - * table below. - * - * - * - * - * - * - * - *
\c dst_bufPointer to the destination buffer which has been filled - * with the next set of elements gathered. This will always be - * identical to the \p dst_buf passed to H5Dgather().
\c dst_buf_bytes_usedPointer to the number of valid bytes in \p dst_buf. - * This number must be a multiple of the datatype - * size.
\c op_dataUser-defined pointer to data required by the callback - * function; a pass-through of the \p op_data pointer - * provided with the H5Dgather() function call.
- * The callback function should process, store, or otherwise, + * bytes to process the serialized data. + * + * The callback function \p op should process, store, or otherwise, * make use of the data returned in \p dst_buf before it returns, * because the buffer will be overwritten unless it is the last * call to the callback. This function will be repeatedly called @@ -1419,11 +1592,11 @@ H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, * * \return \herr_t * - * \details H5Dclose() ends access to a dataset specified by \p dset_id - * and releases resources used by it. + * \details H5Dclose() terminates access to a dataset via the identifier + * \p dset_id and releases the underlying resources. * - * \attention Further use of a released dataset identifier is illegal; a - * function using such an identifier will generate an error. + * \par Example + * \snippet H5D_examples.c read * * \since 1.8.0 * @@ -1432,10 +1605,51 @@ H5_DLL herr_t H5Dgather(hid_t src_space_id, const void *src_buf, hid_t type_id, */ H5_DLL herr_t H5Dclose(hid_t dset_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Dclose} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Dclose_async(hid_t dset_id, hid_t es_id); +#endif +/// \cond DEV /* Internal API routines */ H5_DLL herr_t H5Ddebug(hid_t dset_id); H5_DLL herr_t H5Dformat_convert(hid_t dset_id); H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); +/// \endcond + +/// \cond DEV +/* API Wrappers for async routines */ +/* (Must be defined _after_ the function prototype) */ +/* (And must only defined when included in application code, not the library) */ +#ifndef H5D_MODULE +#define H5Dcreate_async(...) H5Dcreate_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Dopen_async(...) H5Dopen_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Dget_space_async(...) H5Dget_space_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Dread_async(...) H5Dread_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Dread_multi_async(...) H5Dread_multi_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Dwrite_async(...) H5Dwrite_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Dwrite_multi_async(...) H5Dwrite_multi_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Dset_extent_async(...) H5Dset_extent_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Dclose_async(...) H5Dclose_async(__FILE__, __func__, __LINE__, __VA_ARGS__) + +/* Define "wrapper" versions of function calls, to allow compile-time values to + * be passed in by language wrapper or library layer on top of HDF5. + */ +#define H5Dcreate_async_wrap H5_NO_EXPAND(H5Dcreate_async) +#define H5Dopen_async_wrap H5_NO_EXPAND(H5Dopen_async) +#define H5Dget_space_async_wrap H5_NO_EXPAND(H5Dget_space_async) +#define H5Dread_async_wrap H5_NO_EXPAND(H5Dread_async) +#define H5Dwrite_async_wrap H5_NO_EXPAND(H5Dwrite_async) +#define H5Dset_extent_async_wrap H5_NO_EXPAND(H5Dset_extent_async) +#define H5Dclose_async_wrap H5_NO_EXPAND(H5Dclose_async) +#endif /* H5D_MODULE */ +/// \endcond /* Symbols defined for compatibility with previous versions of the HDF5 API. * @@ -1476,8 +1690,7 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); * * \return \hid_t{dataset} * - * \deprecated This function is deprecated in favor of the function H5Dcreate2() - * or the macro H5Dcreate(). + * \deprecation_note{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 @@ -1490,7 +1703,7 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); * 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 + * 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. @@ -1506,7 +1719,7 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); * H5reate1() and initialized with various property list functions * described in Property List Interface. * - * H5Dcreate() and H5Dcreate_anon() return an error if the dataset’s + * 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 @@ -1515,10 +1728,10 @@ H5_DLL herr_t H5Dget_chunk_index_type(hid_t did, H5D_chunk_index_t *idx_type); * * 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 + * should eventually be closed by calling H5Dclose() to release the * resources it uses. * - * See H5Dcreate_anon() for discussion of the differences between + * See H5Dcreate_anon() for a discussion of the differences between * H5Dcreate() and H5Dcreate_anon(). * * The HDF5 library provides flexible means of specifying a fill value, @@ -1543,8 +1756,7 @@ H5_DLL hid_t H5Dcreate1(hid_t loc_id, const char *name, hid_t type_id, hid_t spa * * \return \hid_t{dataset} * - * \deprecated This function is deprecated in favor of the function H5Dopen2() - * or the macro H5Dopen(). + * \deprecation_note{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, @@ -1574,10 +1786,10 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name); * * \return \herr_t * - * \deprecated This function is deprecated in favor of the function H5Dset_extent(). + * \deprecation_note{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 + * extending it if necessary. The length of \p size is the same as * that of the dataspace of the dataset being changed. * * This function can be applied to the following datasets: @@ -1587,17 +1799,17 @@ H5_DLL hid_t H5Dopen1(hid_t loc_id, const char *name); * (see H5Screate_simple()) * * Space on disk is immediately allocated for the new dataset extent if - * the dataset’s space allocation time is set to + * 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 + * 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. + * used if the dataset dimension sizes are to be reduced. * - * \version 1.8.0 Function Function deprecated in this release. Parameter size + * \version 1.8.0 Function deprecated in this release. Parameter size * syntax changed to \Code{const hsize_t size[]} in this release. * */ @@ -1615,8 +1827,7 @@ H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]); * * \return \herr_t * - * \deprecated This function has been deprecated in HDF5-1.12 in favor of the - * function H5Treclaim(). + * \deprecation_note{H5Treclaim()} * * \details H5Dvlen_reclaim() reclaims memory buffers created to store VL * datatypes. @@ -1624,7 +1835,7 @@ H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]); * 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 + * list that 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 @@ -1634,7 +1845,7 @@ H5_DLL herr_t H5Dextend(hid_t dset_id, const hsize_t size[]); * frees them from the bottom up, releasing all the memory without * creating memory leaks. * - * \version 1.12.0 Routine was deprecated + * \version 1.12.0 Function was deprecated * */ H5_DLL herr_t H5Dvlen_reclaim(hid_t type_id, hid_t space_id, hid_t dxpl_id, void *buf); diff --git a/libs/windows/include/H5DxferProp.h b/libs/windows/include/H5DxferProp.h index 1e4d668..d0a65c1 100644 --- a/libs/windows/include/H5DxferProp.h +++ b/libs/windows/include/H5DxferProp.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -100,7 +99,7 @@ class H5_DLLCPP DSetMemXferPropList : public PropList { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("DSetMemXferPropList"); } @@ -113,7 +112,7 @@ class H5_DLLCPP DSetMemXferPropList : public PropList { DSetMemXferPropList(const hid_t plist_id); // Noop destructor - virtual ~DSetMemXferPropList(); + virtual ~DSetMemXferPropList() override; #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/libs/windows/include/H5ESdevelop.h b/libs/windows/include/H5ESdevelop.h new file mode 100644 index 0000000..b2facaa --- /dev/null +++ b/libs/windows/include/H5ESdevelop.h @@ -0,0 +1,52 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * This file contains public declarations for the H5ES (event set) developer + * support routines. + */ + +#ifndef H5ESdevelop_H +#define H5ESdevelop_H + +/* Include package's public header */ +#include "H5ESpublic.h" + +/*****************/ +/* Public Macros */ +/*****************/ + +/*******************/ +/* Public Typedefs */ +/*******************/ + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ + +#ifdef __cplusplus +extern "C" { +#endif + +H5_DLL herr_t H5ESinsert_request(hid_t es_id, hid_t connector_id, void *request); +H5_DLL herr_t H5ESget_requests(hid_t es_id, H5_iter_order_t order, hid_t *connector_ids, void **requests, + size_t array_len, size_t *count); + +#ifdef __cplusplus +} +#endif + +#endif /* H5ESdevelop_H */ diff --git a/libs/windows/include/H5ESpublic.h b/libs/windows/include/H5ESpublic.h index 28b41fa..b5f2af4 100644 --- a/libs/windows/include/H5ESpublic.h +++ b/libs/windows/include/H5ESpublic.h @@ -2,7 +2,7 @@ * Copyright by The HDF Group. * * All rights reserved. * * * - * This file is part of HDF5. The full HDF5 copyright notice, including * + * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * * distribution tree, or in https://www.hdfgroup.org/licenses. * @@ -17,25 +17,122 @@ #ifndef H5ESpublic_H #define H5ESpublic_H -/* Public headers needed by this file */ -#include "H5public.h" /* Generic Functions */ +#include "H5public.h" /* Generic Functions */ +#include "H5Ipublic.h" /* Identifiers */ /*****************/ /* Public Macros */ /*****************/ +/** + * Default value for "no event set" / synchronous execution. Used in + * place of a @ref hid_t identifier. + */ +#define H5ES_NONE 0 + +/* Special "wait" timeout values */ +#define H5ES_WAIT_FOREVER (UINT64_MAX) /**< Wait until all operations complete */ + +/** + * Don't wait for operations to complete, just check their status. + * (This allows @ref H5ESwait to behave like a 'test' operation) + */ +#define H5ES_WAIT_NONE (0) + /*******************/ /* Public Typedefs */ /*******************/ -/* Asynchronous operation status */ +/** + * Asynchronous operation status + */ typedef enum H5ES_status_t { - H5ES_STATUS_IN_PROGRESS, /* Operation has not yet completed */ - H5ES_STATUS_SUCCEED, /* Operation has completed, successfully */ - H5ES_STATUS_FAIL, /* Operation has completed, but failed */ - H5ES_STATUS_CANCELED /* Operation has not completed and was canceled */ + H5ES_STATUS_IN_PROGRESS, /**< Operation(s) have not yet completed */ + H5ES_STATUS_SUCCEED, /**< Operation(s) have completed, successfully */ + H5ES_STATUS_CANCELED, /**< Operation(s) has been canceled */ + H5ES_STATUS_FAIL /**< An operation has completed, but failed */ } H5ES_status_t; +/** + * Information about operations in an event set + */ +typedef struct H5ES_op_info_t { + /* API call info */ + const char *api_name; /**< Name of HDF5 API routine called */ + char *api_args; /**< "Argument string" for arguments to HDF5 API routine called */ + + /* Application info */ + const char *app_file_name; /**< Name of source file where the HDF5 API routine was called */ + const 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 */ + + /* Operation info */ + 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 */ + uint64_t op_exec_ts; /**< Timestamp for when the operation began execution */ + uint64_t op_exec_time; /**< Execution time for operation (in ns) */ +} H5ES_op_info_t; + +//! +/** + * Information about failed operations in event set + */ +typedef struct H5ES_err_info_t { + /* API call info */ + char *api_name; /**< Name of HDF5 API routine called */ + char *api_args; /**< "Argument string" for arguments to HDF5 API routine called */ + + /* Application info */ + 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 */ + + /* Operation info */ + 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 */ + uint64_t op_exec_ts; /**< Timestamp for when the operation began execution */ + uint64_t op_exec_time; /**< Execution time for operation (in ns) */ + + /* Error info */ + hid_t err_stack_id; /**< ID for error stack from failed operation */ +} H5ES_err_info_t; +//! + +/* +More Possible Info for H5ES_op_info_t: + Parent Operation's request token (*) -> "parent event count"? -- Could be + used to "prune" child operations from reported errors, with flag + to H5ESget_err_info? + +Possible debugging routines: (Should also be configured from Env Var) + H5ESdebug_signal(hid_t es_id, signal_t sig, uint64_t ); + H5ESdebug_err_trace_log(hid_t es_id, const char *filename); + H5ESdebug_err_trace_fh(hid_t es_id, FILE *fh); + H5ESdebug_err_signal(hid_t es_id, signal_t sig); +[Possibly option to allow operations to be inserted into event set with error?] + + Example usage: + es_id = H5EScreate(); + H5ESdebug...(es_id, ...); + ... + H5Dwrite_async(..., es_id); + +How to Trace Async Operations? + + +*/ + +/** + * Callback for H5ESregister_insert_func() + */ +typedef int (*H5ES_event_insert_func_t)(const H5ES_op_info_t *op_info, void *ctx); + +/** + * Callback for H5ESregister_complete_func() + */ +typedef int (*H5ES_event_complete_func_t)(const H5ES_op_info_t *op_info, H5ES_status_t status, + hid_t err_stack, void *ctx); + /********************/ /* Public Variables */ /********************/ @@ -48,6 +145,241 @@ typedef enum H5ES_status_t { extern "C" { #endif +/** + * \ingroup H5ES + * + * \brief Creates an event set + * + * \returns \hid_t{event set} + * + * \details H5EScreate() creates a new event set and returns a corresponding + * event set identifier. + * + * \since 1.14.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.14.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 Attempt to cancel operations in an event set + * + * \es_id + * \param[out] num_not_canceled The number of events not canceled + * \param[out] err_occurred Status indicating if error is present in the event set + * \returns \herr_t + * + * \details H5EScancel() attempts to cancel operations in an event set specified + * by \p es_id. H5ES_NONE is a valid value for \p es_id, but functions as a no-op. + * + * \since 1.14.0 + * + */ +H5_DLL herr_t H5EScancel(hid_t es_id, size_t *num_not_canceled, 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.14.0 + * + */ +H5_DLL herr_t H5ESget_count(hid_t es_id, size_t *count); + +/** + * \ingroup H5ES + * + * \brief Retrieves the accumulative operation counter for an event set + * + * \es_id + * \param[out] counter The accumulative counter value for an event set + * \returns \herr_t + * + * \details H5ESget_op_counter() retrieves the current accumulative count of + * event set operations since the event set creation of \p es_id. + * + * \note This is designed for wrapper libraries mainly, to use as a mechanism + * for matching operations inserted into the event set with possible + * errors that occur. + * + * \since 1.14.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.14.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.14.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.14.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 Convenience routine to free an array of H5ES_err_info_t structs + * + * \param[in] num_err_info The number of elements in \p err_info array + * \param[in] err_info Array of structures + * \returns \herr_t + * + * \since 1.14.0 + * + */ +H5_DLL herr_t H5ESfree_err_info(size_t num_err_info, H5ES_err_info_t err_info[]); + +/** + * \ingroup H5ES + * + * \brief Registers a callback to invoke when a new operation is inserted into + * an event set + * + * \es_id + * \param[in] func The insert function to register + * \param[in] ctx User-specified information (context) to pass to \p func + * \returns \herr_t + * + * \details Only one insert callback can be registered for each event set. + * Registering a new callback will replace the existing one. + * H5ES_NONE is a valid value for 'es_id', but functions as a no-op + * + * \since 1.14.0 + * + */ +H5_DLL herr_t H5ESregister_insert_func(hid_t es_id, H5ES_event_insert_func_t func, void *ctx); + +/** + * \ingroup H5ES + * + * \brief Registers a callback to invoke when an operation completes within an + * event set + * + * \es_id + * \param[in] func The completion function to register + * \param[in] ctx User-specified information (context) to pass to \p func + * \returns \herr_t + * + * \details Only one complete callback can be registered for each event set. + * Registering a new callback will replace the existing one. + * H5ES_NONE is a valid value for 'es_id', but functions as a no-op + * + * \since 1.14.0 + * + */ +H5_DLL herr_t H5ESregister_complete_func(hid_t es_id, H5ES_event_complete_func_t func, void *ctx); + +/** + * \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.14.0 + * + */ +H5_DLL herr_t H5ESclose(hid_t es_id); + #ifdef __cplusplus } #endif diff --git a/libs/windows/include/H5EnumType.h b/libs/windows/include/H5EnumType.h index 484405a..a98688e 100644 --- a/libs/windows/include/H5EnumType.h +++ b/libs/windows/include/H5EnumType.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -41,7 +40,7 @@ class H5_DLLCPP EnumType : public DataType { // Returns an EnumType object via DataType* by decoding the // binary object description of this type. - virtual DataType *decode() const; + virtual DataType *decode() const override; // Returns the number of members in this enumeration datatype. int getNmembers() const; @@ -68,7 +67,7 @@ class H5_DLLCPP EnumType : public DataType { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("EnumType"); } @@ -82,7 +81,7 @@ class H5_DLLCPP EnumType : public DataType { // Copy constructor: same as the original EnumType. EnumType(const EnumType &original); - virtual ~EnumType(); + virtual ~EnumType() override; }; // end of EnumType } // namespace H5 diff --git a/libs/windows/include/H5Epubgen.h b/libs/windows/include/H5Epubgen.h index 375e92d..5c19d43 100644 --- a/libs/windows/include/H5Epubgen.h +++ b/libs/windows/include/H5Epubgen.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -38,6 +37,8 @@ extern "C" { #define H5E_REFERENCE (H5OPEN H5E_REFERENCE_g) #define H5E_DATASPACE (H5OPEN H5E_DATASPACE_g) #define H5E_RESOURCE (H5OPEN H5E_RESOURCE_g) +#define H5E_EVENTSET (H5OPEN H5E_EVENTSET_g) +#define H5E_ID (H5OPEN H5E_ID_g) #define H5E_RS (H5OPEN H5E_RS_g) #define H5E_FARRAY (H5OPEN H5E_FARRAY_g) #define H5E_HEAP (H5OPEN H5E_HEAP_g) @@ -55,7 +56,6 @@ extern "C" { #define H5E_PLIST (H5OPEN H5E_PLIST_g) #define H5E_DATATYPE (H5OPEN H5E_DATATYPE_g) #define H5E_OHDR (H5OPEN H5E_OHDR_g) -#define H5E_ATOM (H5OPEN H5E_ATOM_g) #define H5E_NONE_MAJOR (H5OPEN H5E_NONE_MAJOR_g) #define H5E_SLIST (H5OPEN H5E_SLIST_g) #define H5E_ARGS (H5OPEN H5E_ARGS_g) @@ -76,6 +76,8 @@ H5_DLLVAR hid_t H5E_BTREE_g; /* B-Tree node */ H5_DLLVAR hid_t H5E_REFERENCE_g; /* References */ H5_DLLVAR hid_t H5E_DATASPACE_g; /* Dataspace */ H5_DLLVAR hid_t H5E_RESOURCE_g; /* Resource unavailable */ +H5_DLLVAR hid_t H5E_EVENTSET_g; /* Event Set */ +H5_DLLVAR hid_t H5E_ID_g; /* Object ID */ H5_DLLVAR hid_t H5E_RS_g; /* Reference Counted Strings */ H5_DLLVAR hid_t H5E_FARRAY_g; /* Fixed Array */ H5_DLLVAR hid_t H5E_HEAP_g; /* Heap */ @@ -93,7 +95,6 @@ H5_DLLVAR hid_t H5E_LINK_g; /* Links */ H5_DLLVAR hid_t H5E_PLIST_g; /* Property lists */ H5_DLLVAR hid_t H5E_DATATYPE_g; /* Datatype */ H5_DLLVAR hid_t H5E_OHDR_g; /* Object header */ -H5_DLLVAR hid_t H5E_ATOM_g; /* Object atom */ H5_DLLVAR hid_t H5E_NONE_MAJOR_g; /* No error */ H5_DLLVAR hid_t H5E_SLIST_g; /* Skip Lists */ H5_DLLVAR hid_t H5E_ARGS_g; /* Invalid arguments to routine */ @@ -107,6 +108,20 @@ H5_DLLVAR hid_t H5E_CACHE_g; /* Object cache */ /* Minor error codes */ /*********************/ +/* Object ID related errors */ +#define H5E_BADID (H5OPEN H5E_BADID_g) +#define H5E_BADGROUP (H5OPEN H5E_BADGROUP_g) +#define H5E_CANTREGISTER (H5OPEN H5E_CANTREGISTER_g) +#define H5E_CANTINC (H5OPEN H5E_CANTINC_g) +#define H5E_CANTDEC (H5OPEN H5E_CANTDEC_g) +#define H5E_NOIDS (H5OPEN H5E_NOIDS_g) +H5_DLLVAR hid_t H5E_BADID_g; /* Unable to find ID information (already closed?) */ +H5_DLLVAR hid_t H5E_BADGROUP_g; /* Unable to find ID group information */ +H5_DLLVAR hid_t H5E_CANTREGISTER_g; /* Unable to register new ID */ +H5_DLLVAR hid_t H5E_CANTINC_g; /* Unable to increment reference count */ +H5_DLLVAR hid_t H5E_CANTDEC_g; /* Unable to decrement reference count */ +H5_DLLVAR hid_t H5E_NOIDS_g; /* Out of IDs for group */ + /* Generic low-level file I/O errors */ #define H5E_SEEKERROR (H5OPEN H5E_SEEKERROR_g) #define H5E_READERROR (H5OPEN H5E_READERROR_g) @@ -157,6 +172,10 @@ H5_DLLVAR hid_t H5E_CANTATTACH_g; /* Can't attach object */ H5_DLLVAR hid_t H5E_CANTUPDATE_g; /* Can't update object */ H5_DLLVAR hid_t H5E_CANTOPERATE_g; /* Can't operate on object */ +/* Map related errors */ +#define H5E_CANTPUT (H5OPEN H5E_CANTPUT_g) +H5_DLLVAR hid_t H5E_CANTPUT_g; /* Can't put value */ + /* Function entry/exit interface errors */ #define H5E_CANTINIT (H5OPEN H5E_CANTINIT_g) #define H5E_ALREADYINIT (H5OPEN H5E_ALREADYINIT_g) @@ -175,6 +194,12 @@ H5_DLLVAR hid_t H5E_CANTSET_g; /* Can't set value */ H5_DLLVAR hid_t H5E_DUPCLASS_g; /* Duplicate class name in parent class */ H5_DLLVAR hid_t H5E_SETDISALLOWED_g; /* Disallowed operation */ +/* Asynchronous operation errors */ +#define H5E_CANTWAIT (H5OPEN H5E_CANTWAIT_g) +#define H5E_CANTCANCEL (H5OPEN H5E_CANTCANCEL_g) +H5_DLLVAR hid_t H5E_CANTWAIT_g; /* Can't wait on operation */ +H5_DLLVAR hid_t H5E_CANTCANCEL_g; /* Can't cancel operation */ + /* Free space errors */ #define H5E_CANTMERGE (H5OPEN H5E_CANTMERGE_g) #define H5E_CANTREVIVE (H5OPEN H5E_CANTREVIVE_g) @@ -249,6 +274,7 @@ H5_DLLVAR hid_t H5E_OPENERROR_g; /* Can't open directory or file */ #define H5E_BADFILE (H5OPEN H5E_BADFILE_g) #define H5E_TRUNCATED (H5OPEN H5E_TRUNCATED_g) #define H5E_MOUNT (H5OPEN H5E_MOUNT_g) +#define H5E_UNMOUNT (H5OPEN H5E_UNMOUNT_g) #define H5E_CANTDELETEFILE (H5OPEN H5E_CANTDELETEFILE_g) #define H5E_CANTLOCKFILE (H5OPEN H5E_CANTLOCKFILE_g) #define H5E_CANTUNLOCKFILE (H5OPEN H5E_CANTUNLOCKFILE_g) @@ -261,24 +287,11 @@ H5_DLLVAR hid_t H5E_NOTHDF5_g; /* Not an HDF5 file */ H5_DLLVAR hid_t H5E_BADFILE_g; /* Bad file ID accessed */ H5_DLLVAR hid_t H5E_TRUNCATED_g; /* File has been truncated */ H5_DLLVAR hid_t H5E_MOUNT_g; /* File mount error */ +H5_DLLVAR hid_t H5E_UNMOUNT_g; /* File unmount error */ H5_DLLVAR hid_t H5E_CANTDELETEFILE_g; /* Unable to delete file */ H5_DLLVAR hid_t H5E_CANTLOCKFILE_g; /* Unable to lock file */ H5_DLLVAR hid_t H5E_CANTUNLOCKFILE_g; /* Unable to unlock file */ -/* Object atom related errors */ -#define H5E_BADATOM (H5OPEN H5E_BADATOM_g) -#define H5E_BADGROUP (H5OPEN H5E_BADGROUP_g) -#define H5E_CANTREGISTER (H5OPEN H5E_CANTREGISTER_g) -#define H5E_CANTINC (H5OPEN H5E_CANTINC_g) -#define H5E_CANTDEC (H5OPEN H5E_CANTDEC_g) -#define H5E_NOIDS (H5OPEN H5E_NOIDS_g) -H5_DLLVAR hid_t H5E_BADATOM_g; /* Unable to find atom information (already closed?) */ -H5_DLLVAR hid_t H5E_BADGROUP_g; /* Unable to find ID group information */ -H5_DLLVAR hid_t H5E_CANTREGISTER_g; /* Unable to register new atom */ -H5_DLLVAR hid_t H5E_CANTINC_g; /* Unable to increment reference count */ -H5_DLLVAR hid_t H5E_CANTDEC_g; /* Unable to decrement reference count */ -H5_DLLVAR hid_t H5E_NOIDS_g; /* Out of IDs for group */ - /* Cache related errors */ #define H5E_CANTFLUSH (H5OPEN H5E_CANTFLUSH_g) #define H5E_CANTUNSERIALIZE (H5OPEN H5E_CANTUNSERIALIZE_g) @@ -401,6 +414,7 @@ H5_DLLVAR hid_t H5E_BADVALUE_g; /* Bad value */ #define H5E_CANTLIST (H5OPEN H5E_CANTLIST_g) #define H5E_CANTMODIFY (H5OPEN H5E_CANTMODIFY_g) #define H5E_CANTREMOVE (H5OPEN H5E_CANTREMOVE_g) +#define H5E_CANTFIND (H5OPEN H5E_CANTFIND_g) H5_DLLVAR hid_t H5E_NOTFOUND_g; /* Object not found */ H5_DLLVAR hid_t H5E_EXISTS_g; /* Object already exists */ H5_DLLVAR hid_t H5E_CANTENCODE_g; /* Unable to encode value */ @@ -412,6 +426,7 @@ H5_DLLVAR hid_t H5E_CANTINSERT_g; /* Unable to insert object */ H5_DLLVAR hid_t H5E_CANTLIST_g; /* Unable to list node */ H5_DLLVAR hid_t H5E_CANTMODIFY_g; /* Unable to modify record */ H5_DLLVAR hid_t H5E_CANTREMOVE_g; /* Unable to remove object */ +H5_DLLVAR hid_t H5E_CANTFIND_g; /* Unable to check for record */ /* Datatype conversion errors */ #define H5E_CANTCONVERT (H5OPEN H5E_CANTCONVERT_g) diff --git a/libs/windows/include/H5Epublic.h b/libs/windows/include/H5Epublic.h index 2f529b3..b6cc1cb 100644 --- a/libs/windows/include/H5Epublic.h +++ b/libs/windows/include/H5Epublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -17,14 +16,13 @@ #ifndef H5Epublic_H #define H5Epublic_H -#include /*FILE arg of H5Eprint() */ +#include /* FILE arg of H5Eprint() */ -/* Public headers needed by this file */ -#include "H5public.h" -#include "H5Ipublic.h" +#include "H5public.h" /* Generic Functions */ +#include "H5Ipublic.h" /* Identifiers */ /* Value for the default error stack */ -#define H5E_DEFAULT (hid_t)0 +#define H5E_DEFAULT 0 /* (hid_t) */ /** * Different kinds of error information @@ -38,9 +36,9 @@ typedef struct H5E_error2_t { hid_t cls_id; /**< Class ID */ hid_t maj_num; - /**< Major error ID */ + /**< Major error ID */ hid_t min_num; - /**< Minor error number */ + /**< Minor error number */ unsigned line; /**< Line in file where error occurs */ const char *func_name; @@ -60,8 +58,15 @@ typedef struct H5E_error2_t { #endif /* H5private_H */ /* HDF5 error class */ +/* Extern "C" block needed to compile C++ filter plugins with some compilers */ +#ifdef __cplusplus +extern "C" { +#endif #define H5E_ERR_CLS (H5OPEN H5E_ERR_CLS_g) H5_DLLVAR hid_t H5E_ERR_CLS_g; +#ifdef __cplusplus +} +#endif /* Include the automatically generated public header information */ /* (This includes the list of major and minor error codes for the library) */ @@ -74,7 +79,7 @@ H5_DLLVAR hid_t H5E_ERR_CLS_g; * easier just to use this macro like: * H5E_BEGIN_TRY { * ...stuff here that's likely to fail... - * } H5E_END_TRY; + * } H5E_END_TRY * * Warning: don't break, return, or longjmp() from the body of the loop or * the error reporting won't be properly restored! @@ -112,7 +117,7 @@ H5_DLLVAR hid_t H5E_ERR_CLS_g; #define H5E_BEGIN_TRY \ { \ H5E_auto2_t saved_efunc; \ - void * H5E_saved_edata; \ + void *H5E_saved_edata; \ \ (void)H5Eget_auto2(H5E_DEFAULT, &saved_efunc, &H5E_saved_edata); \ (void)H5Eset_auto2(H5E_DEFAULT, NULL, NULL); @@ -144,10 +149,10 @@ H5_DLLVAR hid_t H5E_ERR_CLS_g; * And goto a label after pushing error onto stack. */ #define H5Epush_goto(func, cls, maj, min, str, label) \ - { \ + do { \ H5Epush2(H5E_DEFAULT, __FILE__, func, __LINE__, cls, maj, min, str); \ goto label; \ - } + } while (0) /** * Error stack traversal direction @@ -197,7 +202,7 @@ typedef herr_t (*H5E_auto2_t)(hid_t estack, void *client_data); * \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. + error class belongs. It 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 @@ -271,7 +276,7 @@ H5_DLL hid_t H5Ecreate_msg(hid_t cls, H5E_type_t msg_type, const char *msg); * \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 + * new stack's identifier. Use H5Eclose_stack() to close the error stack * identifier returned by this function. * * \since 1.8.0 @@ -291,6 +296,26 @@ H5_DLL hid_t H5Ecreate_stack(void); * \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.14.0 + */ +H5_DLL herr_t H5Eappend_stack(hid_t dst_stack_id, hid_t src_stack_id, hbool_t close_source_stack); /** * -------------------------------------------------------------------------- * \ingroup H5E @@ -315,12 +340,12 @@ H5_DLL herr_t H5Eclose_stack(hid_t stack_id); * * \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. + * \param[in] size The maximum number of characters of 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 + * by the class identifier. If a 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 @@ -505,7 +530,7 @@ H5_DLL herr_t H5Ewalk2(hid_t err_stack, H5E_direction_t direction, H5E_walk2_t f * 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 + * 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. * @@ -696,12 +721,13 @@ typedef herr_t (*H5E_auto1_t)(void *client_data); * * \return \herr_t * + * \deprecated 1.8.0 Function H5Eclear() renamed to H5Eclear1() and deprecated + * in this release. + * * \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); /** @@ -717,6 +743,9 @@ H5_DLL herr_t H5Eclear1(void); * function * \return \herr_t * + * \deprecated 1.8.0 Function H5Eget_auto() renamed to H5Eget_auto1() and + * deprecated in this release. + * * \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 @@ -739,12 +768,10 @@ H5_DLL herr_t H5Eclear1(void); * 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 + * 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); /** @@ -761,6 +788,9 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); * \param[in] str Error description string * \return \herr_t * + * \deprecated 1.8.0 Function H5Epush() renamed to H5Epush1() and + * deprecated in this release. + * * \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 @@ -771,8 +801,6 @@ H5_DLL herr_t H5Eget_auto1(H5E_auto1_t *func, void **client_data); * 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); @@ -785,7 +813,10 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma * \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 + * \deprecated 1.8.0 Function H5Eprint() renamed to H5Eprint1() and + * deprecated in this release. + * + * \details H5Eprint1() 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} @@ -795,8 +826,6 @@ H5_DLL herr_t H5Epush1(const char *file, const char *func, unsigned line, H5E_ma * 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); /** @@ -809,6 +838,9 @@ H5_DLL herr_t H5Eprint1(FILE *stream); * \param[in] client_data Data passed to the error function * \return \herr_t * + * \deprecated 1.8.0 Function H5Eset_auto() renamed to H5Eset_auto1() and + * deprecated in this release. + * * \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 @@ -825,8 +857,6 @@ H5_DLL herr_t H5Eprint1(FILE *stream); * 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); /** @@ -840,6 +870,9 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); * \param[in] client_data Data to be passed to \p func * \return \herr_t * + * \deprecated 1.8.0 Function H5Ewalk() renamed to H5Ewalk1() and + * deprecated in this release. + * * \details H5Ewalk1() walks the error stack for the current thread and calls * the function specified in \p func for each error along the way. * @@ -857,8 +890,6 @@ H5_DLL herr_t H5Eset_auto1(H5E_auto1_t func, void *client_data); * 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); /** @@ -871,14 +902,15 @@ H5_DLL herr_t H5Ewalk1(H5E_direction_t direction, H5E_walk1_t func, void *client * \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. + * \deprecated 1.8.0 Function deprecated in this release. + * + * \details H5Eget_major() returns a constant + * character string that describes the error, given a major error number. * * \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); /** @@ -891,8 +923,10 @@ H5_DLL char *H5Eget_major(H5E_major_t maj); * \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. + * \deprecated 1.8.0 Function deprecated and return type changed in this release. + * + * \details H5Eget_minor() returns a constant + * character string that describes the error, given a minor error number. * * \attention In the Release 1.8.x series, H5Eget_minor() returns a string of * dynamic allocated \c char array. An application calling this @@ -900,7 +934,6 @@ H5_DLL char *H5Eget_major(H5E_major_t maj); * 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 */ diff --git a/libs/windows/include/H5Exception.h b/libs/windows/include/H5Exception.h index 9970d22..d4533e5 100644 --- a/libs/windows/include/H5Exception.h +++ b/libs/windows/include/H5Exception.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -41,9 +40,9 @@ class H5_DLLCPP Exception { // Returns the detailed message set at the time the exception is thrown H5std_string getDetailMsg() const; - const char * getCDetailMsg() const; // C string of detailed message + const char *getCDetailMsg() const; // C string of detailed message H5std_string getFuncName() const; // function name as a string object - const char * getCFuncName() const; // function name as a char string + const char *getCFuncName() const; // function name as a char string // Turns on the automatic error printing. static void setAutoPrint(H5E_auto2_t &func, void *client_data); @@ -90,84 +89,84 @@ class H5_DLLCPP FileIException : public Exception { public: FileIException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); FileIException(); - virtual ~FileIException() throw() H5_OVERRIDE; + virtual ~FileIException() throw() override; }; class H5_DLLCPP GroupIException : public Exception { public: GroupIException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); GroupIException(); - virtual ~GroupIException() throw() H5_OVERRIDE; + virtual ~GroupIException() throw() override; }; class H5_DLLCPP DataSpaceIException : public Exception { public: DataSpaceIException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); DataSpaceIException(); - virtual ~DataSpaceIException() throw() H5_OVERRIDE; + virtual ~DataSpaceIException() throw() override; }; class H5_DLLCPP DataTypeIException : public Exception { public: DataTypeIException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); DataTypeIException(); - virtual ~DataTypeIException() throw() H5_OVERRIDE; + virtual ~DataTypeIException() throw() override; }; class H5_DLLCPP ObjHeaderIException : public Exception { public: ObjHeaderIException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); ObjHeaderIException(); - virtual ~ObjHeaderIException() throw() H5_OVERRIDE; + virtual ~ObjHeaderIException() throw() override; }; class H5_DLLCPP PropListIException : public Exception { public: PropListIException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); PropListIException(); - virtual ~PropListIException() throw() H5_OVERRIDE; + virtual ~PropListIException() throw() override; }; class H5_DLLCPP DataSetIException : public Exception { public: DataSetIException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); DataSetIException(); - virtual ~DataSetIException() throw() H5_OVERRIDE; + virtual ~DataSetIException() throw() override; }; class H5_DLLCPP AttributeIException : public Exception { public: AttributeIException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); AttributeIException(); - virtual ~AttributeIException() throw() H5_OVERRIDE; + virtual ~AttributeIException() throw() override; }; class H5_DLLCPP ReferenceException : public Exception { public: ReferenceException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); ReferenceException(); - virtual ~ReferenceException() throw() H5_OVERRIDE; + virtual ~ReferenceException() throw() override; }; class H5_DLLCPP LibraryIException : public Exception { public: LibraryIException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); LibraryIException(); - virtual ~LibraryIException() throw() H5_OVERRIDE; + virtual ~LibraryIException() throw() override; }; class H5_DLLCPP LocationException : public Exception { public: LocationException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); LocationException(); - virtual ~LocationException() throw() H5_OVERRIDE; + virtual ~LocationException() throw() override; }; class H5_DLLCPP IdComponentException : public Exception { public: IdComponentException(const H5std_string &func_name, const H5std_string &message = DEFAULT_MSG); IdComponentException(); - virtual ~IdComponentException() throw() H5_OVERRIDE; + virtual ~IdComponentException() throw() override; }; // end of IdComponentException } // namespace H5 diff --git a/libs/windows/include/H5FDcore.h b/libs/windows/include/H5FDcore.h index d456c3e..235d6fc 100644 --- a/libs/windows/include/H5FDcore.h +++ b/libs/windows/include/H5FDcore.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -12,15 +11,13 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Robb Matzke - * Monday, August 2, 1999 - * * Purpose: The public header file for the core driver. */ #ifndef H5FDcore_H #define H5FDcore_H -#define H5FD_CORE (H5FD_core_init()) +#define H5FD_CORE (H5FDperform_init(H5FD_core_init)) +#define H5FD_CORE_VALUE H5_VFD_CORE #ifdef __cplusplus extern "C" { @@ -51,15 +48,15 @@ H5_DLL hid_t H5FD_core_init(void); * 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 + * 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 + * 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 + * 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 diff --git a/libs/windows/include/H5FDdevelop.h b/libs/windows/include/H5FDdevelop.h new file mode 100644 index 0000000..75e63b1 --- /dev/null +++ b/libs/windows/include/H5FDdevelop.h @@ -0,0 +1,307 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * This file contains public declarations for the H5FD (file drivers) developer + * support routines. + */ + +#ifndef H5FDdevelop_H +#define H5FDdevelop_H + +/* Include package's public header */ +#include "H5FDpublic.h" + +/*****************/ +/* Public Macros */ +/*****************/ + +/* H5FD_class_t struct version */ +#define H5FD_CLASS_VERSION 0x01 /* File driver struct version */ + +/* Map "fractal heap" header blocks to 'ohdr' type file memory, since its + * a fair amount of work to add a new kind of file memory and they are similar + * enough to object headers and probably too minor to deserve their own type. + * + * Map "fractal heap" indirect blocks to 'ohdr' type file memory, since they + * are similar to fractal heap header blocks. + * + * Map "fractal heap" direct blocks to 'lheap' type file memory, since they + * will be replacing local heaps. + * + * Map "fractal heap" 'huge' objects to 'draw' type file memory, since they + * represent large objects that are directly stored in the file. + * + * -QAK + */ +#define H5FD_MEM_FHEAP_HDR H5FD_MEM_OHDR +#define H5FD_MEM_FHEAP_IBLOCK H5FD_MEM_OHDR +#define H5FD_MEM_FHEAP_DBLOCK H5FD_MEM_LHEAP +#define H5FD_MEM_FHEAP_HUGE_OBJ H5FD_MEM_DRAW + +/* Map "free space" header blocks to 'ohdr' type file memory, since its + * a fair amount of work to add a new kind of file memory and they are similar + * enough to object headers and probably too minor to deserve their own type. + * + * Map "free space" serialized sections to 'lheap' type file memory, since they + * are similar enough to local heap info. + * + * -QAK + */ +#define H5FD_MEM_FSPACE_HDR H5FD_MEM_OHDR +#define H5FD_MEM_FSPACE_SINFO H5FD_MEM_LHEAP + +/* Map "shared object header message" master table to 'ohdr' type file memory, + * since its a fair amount of work to add a new kind of file memory and they are + * similar enough to object headers and probably too minor to deserve their own + * type. + * + * Map "shared object header message" indices to 'btree' type file memory, + * since they are similar enough to B-tree nodes. + * + * -QAK + */ +#define H5FD_MEM_SOHM_TABLE H5FD_MEM_OHDR +#define H5FD_MEM_SOHM_INDEX H5FD_MEM_BTREE + +/* Map "extensible array" header blocks to 'ohdr' type file memory, since its + * a fair amount of work to add a new kind of file memory and they are similar + * enough to object headers and probably too minor to deserve their own type. + * + * Map "extensible array" index blocks to 'ohdr' type file memory, since they + * are similar to extensible array header blocks. + * + * Map "extensible array" super blocks to 'btree' type file memory, since they + * are similar enough to B-tree nodes. + * + * Map "extensible array" data blocks & pages to 'lheap' type file memory, since + * they are similar enough to local heap info. + * + * -QAK + */ +#define H5FD_MEM_EARRAY_HDR H5FD_MEM_OHDR +#define H5FD_MEM_EARRAY_IBLOCK H5FD_MEM_OHDR +#define H5FD_MEM_EARRAY_SBLOCK H5FD_MEM_BTREE +#define H5FD_MEM_EARRAY_DBLOCK H5FD_MEM_LHEAP +#define H5FD_MEM_EARRAY_DBLK_PAGE H5FD_MEM_LHEAP + +/* Map "fixed array" header blocks to 'ohdr' type file memory, since its + * a fair amount of work to add a new kind of file memory and they are similar + * enough to object headers and probably too minor to deserve their own type. + * + * Map "fixed array" data blocks & pages to 'lheap' type file memory, since + * they are similar enough to local heap info. + * + */ +#define H5FD_MEM_FARRAY_HDR H5FD_MEM_OHDR +#define H5FD_MEM_FARRAY_DBLOCK H5FD_MEM_LHEAP +#define H5FD_MEM_FARRAY_DBLK_PAGE H5FD_MEM_LHEAP + +/* + * A free-list map which maps all types of allocation requests to a single + * free list. This is useful for drivers that don't really care about + * keeping different requests segregated in the underlying file and which + * want to make most efficient reuse of freed memory. The use of the + * H5FD_MEM_SUPER free list is arbitrary. + */ +#define H5FD_FLMAP_SINGLE \ + { \ + H5FD_MEM_SUPER, /*default*/ \ + H5FD_MEM_SUPER, /*super*/ \ + H5FD_MEM_SUPER, /*btree*/ \ + H5FD_MEM_SUPER, /*draw*/ \ + H5FD_MEM_SUPER, /*gheap*/ \ + H5FD_MEM_SUPER, /*lheap*/ \ + H5FD_MEM_SUPER /*ohdr*/ \ + } + +/* + * A free-list map which segregates requests into `raw' or `meta' data + * pools. + */ +#define H5FD_FLMAP_DICHOTOMY \ + { \ + H5FD_MEM_SUPER, /*default*/ \ + H5FD_MEM_SUPER, /*super*/ \ + H5FD_MEM_SUPER, /*btree*/ \ + H5FD_MEM_DRAW, /*draw*/ \ + H5FD_MEM_DRAW, /*gheap*/ \ + H5FD_MEM_SUPER, /*lheap*/ \ + H5FD_MEM_SUPER /*ohdr*/ \ + } + +/* + * The default free list map which causes each request type to use it's own + * free-list. + */ +#define H5FD_FLMAP_DEFAULT \ + { \ + H5FD_MEM_DEFAULT, /*default*/ \ + H5FD_MEM_DEFAULT, /*super*/ \ + H5FD_MEM_DEFAULT, /*btree*/ \ + H5FD_MEM_DEFAULT, /*draw*/ \ + H5FD_MEM_DEFAULT, /*gheap*/ \ + H5FD_MEM_DEFAULT, /*lheap*/ \ + H5FD_MEM_DEFAULT /*ohdr*/ \ + } + +/*******************/ +/* Public Typedefs */ +/*******************/ + +/* Forward declaration */ +typedef struct H5FD_t H5FD_t; + +/* Class information for each file driver */ +typedef struct H5FD_class_t { + unsigned version; /**< File driver class struct version number */ + H5FD_class_value_t value; + const char *name; + haddr_t maxaddr; + H5F_close_degree_t fc_degree; + herr_t (*terminate)(void); + hsize_t (*sb_size)(H5FD_t *file); + herr_t (*sb_encode)(H5FD_t *file, char *name /*out*/, unsigned char *p /*out*/); + herr_t (*sb_decode)(H5FD_t *f, const char *name, const unsigned char *p); + size_t fapl_size; + void *(*fapl_get)(H5FD_t *file); + void *(*fapl_copy)(const void *fapl); + herr_t (*fapl_free)(void *fapl); + size_t dxpl_size; + void *(*dxpl_copy)(const void *dxpl); + herr_t (*dxpl_free)(void *dxpl); + H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl, haddr_t maxaddr); + herr_t (*close)(H5FD_t *file); + int (*cmp)(const H5FD_t *f1, const H5FD_t *f2); + herr_t (*query)(const H5FD_t *f1, unsigned long *flags); + herr_t (*get_type_map)(const H5FD_t *file, H5FD_mem_t *type_map); + haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size); + herr_t (*free)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, hsize_t size); + haddr_t (*get_eoa)(const H5FD_t *file, H5FD_mem_t type); + herr_t (*set_eoa)(H5FD_t *file, H5FD_mem_t type, haddr_t addr); + haddr_t (*get_eof)(const H5FD_t *file, H5FD_mem_t type); + herr_t (*get_handle)(H5FD_t *file, hid_t fapl, void **file_handle); + herr_t (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, void *buffer); + herr_t (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, const void *buffer); + herr_t (*read_vector)(H5FD_t *file, hid_t dxpl, uint32_t count, H5FD_mem_t types[], haddr_t addrs[], + size_t sizes[], void *bufs[]); + herr_t (*write_vector)(H5FD_t *file, hid_t dxpl, uint32_t count, H5FD_mem_t types[], haddr_t addrs[], + size_t sizes[], const void *bufs[]); + herr_t (*read_selection)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, size_t count, hid_t mem_spaces[], + hid_t file_spaces[], haddr_t offsets[], size_t element_sizes[], + void *bufs[] /*out*/); + herr_t (*write_selection)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, size_t count, hid_t mem_spaces[], + hid_t file_spaces[], haddr_t offsets[], size_t element_sizes[], + const void *bufs[] /*in*/); + herr_t (*flush)(H5FD_t *file, hid_t dxpl_id, hbool_t closing); + herr_t (*truncate)(H5FD_t *file, hid_t dxpl_id, hbool_t closing); + herr_t (*lock)(H5FD_t *file, hbool_t rw); + herr_t (*unlock)(H5FD_t *file); + herr_t (*del)(const char *name, hid_t fapl); + herr_t (*ctl)(H5FD_t *file, uint64_t op_code, uint64_t flags, const void *input, void **output); + H5FD_mem_t fl_map[H5FD_MEM_NTYPES]; +} H5FD_class_t; + +/* A free list is a singly-linked list of address/size pairs. */ +typedef struct H5FD_free_t { + haddr_t addr; + hsize_t size; + struct H5FD_free_t *next; +} H5FD_free_t; + +/* + * The main datatype for each driver. Public fields common to all drivers + * are declared here and the driver appends private fields in memory. + */ +struct H5FD_t { + hid_t driver_id; /*driver ID for this file */ + const H5FD_class_t *cls; /*constant class info */ + unsigned long fileno; /* File 'serial' number */ + unsigned access_flags; /* File access flags (from create or open) */ + unsigned long feature_flags; /* VFL Driver feature Flags */ + haddr_t maxaddr; /* For this file, overrides class */ + haddr_t base_addr; /* Base address for HDF5 data w/in file */ + + /* Space allocation management fields */ + hsize_t threshold; /* Threshold for alignment */ + hsize_t alignment; /* Allocation alignment */ + hbool_t paged_aggr; /* Paged aggregation for file space is enabled or not */ +}; + +/* VFD initialization function */ +typedef hid_t (*H5FD_init_t)(void); + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ + +#ifdef __cplusplus +extern "C" { +#endif + +H5_DLL hid_t H5FDperform_init(H5FD_init_t op); +H5_DLL hid_t H5FDregister(const H5FD_class_t *cls); +H5_DLL htri_t H5FDis_driver_registered_by_name(const char *driver_name); +H5_DLL htri_t H5FDis_driver_registered_by_value(H5FD_class_value_t driver_value); +H5_DLL herr_t H5FDunregister(hid_t driver_id); +H5_DLL H5FD_t *H5FDopen(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr); +H5_DLL herr_t H5FDclose(H5FD_t *file); +H5_DLL int H5FDcmp(const H5FD_t *f1, const H5FD_t *f2); +H5_DLL int H5FDquery(const H5FD_t *f, unsigned long *flags); +H5_DLL haddr_t H5FDalloc(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size); +H5_DLL herr_t H5FDfree(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, hsize_t size); +H5_DLL haddr_t H5FDget_eoa(H5FD_t *file, H5FD_mem_t type); +H5_DLL herr_t H5FDset_eoa(H5FD_t *file, H5FD_mem_t type, haddr_t eoa); +H5_DLL haddr_t H5FDget_eof(H5FD_t *file, H5FD_mem_t type); +H5_DLL herr_t H5FDget_vfd_handle(H5FD_t *file, hid_t fapl, void **file_handle); +H5_DLL herr_t H5FDread(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size, + void *buf /*out*/); +H5_DLL herr_t H5FDwrite(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size, + const void *buf); +H5_DLL herr_t H5FDread_vector(H5FD_t *file, hid_t dxpl_id, uint32_t count, H5FD_mem_t types[], + haddr_t addrs[], size_t sizes[], void *bufs[] /* out */); +H5_DLL herr_t H5FDwrite_vector(H5FD_t *file, hid_t dxpl_id, uint32_t count, H5FD_mem_t types[], + haddr_t addrs[], size_t sizes[], const void *bufs[] /* in */); +H5_DLL herr_t H5FDread_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count, + hid_t mem_spaces[], hid_t file_spaces[], haddr_t offsets[], + size_t element_sizes[], void *bufs[] /* out */); +H5_DLL herr_t H5FDwrite_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count, + hid_t mem_spaces[], hid_t file_spaces[], haddr_t offsets[], + size_t element_sizes[], const void *bufs[]); +H5_DLL herr_t H5FDread_vector_from_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count, + hid_t mem_spaces[], hid_t file_spaces[], haddr_t offsets[], + size_t element_sizes[], void *bufs[] /* out */); +H5_DLL herr_t H5FDwrite_vector_from_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count, + hid_t mem_spaces[], hid_t file_spaces[], haddr_t offsets[], + size_t element_sizes[], const void *bufs[] /* in */); +H5_DLL herr_t H5FDread_from_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count, + hid_t mem_space_ids[], hid_t file_space_ids[], haddr_t offsets[], + size_t element_sizes[], void *bufs[] /* out */); +H5_DLL herr_t H5FDwrite_from_selection(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, uint32_t count, + hid_t mem_space_ids[], hid_t file_space_ids[], haddr_t offsets[], + size_t element_sizes[], const void *bufs[] /* in */); +H5_DLL herr_t H5FDflush(H5FD_t *file, hid_t dxpl_id, hbool_t closing); +H5_DLL herr_t H5FDtruncate(H5FD_t *file, hid_t dxpl_id, hbool_t closing); +H5_DLL herr_t H5FDlock(H5FD_t *file, hbool_t rw); +H5_DLL herr_t H5FDunlock(H5FD_t *file); +H5_DLL herr_t H5FDdelete(const char *name, hid_t fapl_id); +H5_DLL herr_t H5FDctl(H5FD_t *file, uint64_t op_code, uint64_t flags, const void *input, void **output); + +#ifdef __cplusplus +} +#endif + +#endif /* H5FDdevelop_H */ diff --git a/libs/windows/include/H5FDdirect.h b/libs/windows/include/H5FDdirect.h index f06de7f..e47ac37 100644 --- a/libs/windows/include/H5FDdirect.h +++ b/libs/windows/include/H5FDdirect.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -12,18 +11,17 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Raymond Lu - * Wednesday, 20 September 2006 - * * Purpose: The public header file for the direct driver. */ #ifndef H5FDdirect_H #define H5FDdirect_H #ifdef H5_HAVE_DIRECT -#define H5FD_DIRECT (H5FD_direct_init()) +#define H5FD_DIRECT (H5FDperform_init(H5FD_direct_init)) +#define H5FD_DIRECT_VALUE H5_VFD_DIRECT #else -#define H5FD_DIRECT (H5I_INVALID_HID) +#define H5FD_DIRECT (H5I_INVALID_HID) +#define H5FD_DIRECT_VALUE H5_VFD_INVALID #endif /* H5_HAVE_DIRECT */ #ifdef H5_HAVE_DIRECT @@ -56,7 +54,7 @@ H5_DLL hid_t H5FD_direct_init(void); * 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 + * 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 @@ -69,7 +67,7 @@ H5_DLL hid_t H5FD_direct_init(void); * \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. + * (zero) means to use HDF5 library's default value of 4KB. * * \p cbuf_size specifies the copy buffer size. * diff --git a/libs/windows/include/H5FDfamily.h b/libs/windows/include/H5FDfamily.h index 20ef532..76020f0 100644 --- a/libs/windows/include/H5FDfamily.h +++ b/libs/windows/include/H5FDfamily.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -12,15 +11,13 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Robb Matzke - * Monday, August 4, 1999 - * * Purpose: The public header file for the family driver. */ #ifndef H5FDfamily_H #define H5FDfamily_H -#define H5FD_FAMILY (H5FD_family_init()) +#define H5FD_FAMILY (H5FDperform_init(H5FD_family_init)) +#define H5FD_FAMILY_VALUE H5_VFD_FAMILY #ifdef __cplusplus extern "C" { diff --git a/libs/windows/include/H5FDhdfs.h b/libs/windows/include/H5FDhdfs.h index 219d0ac..c8c2c37 100644 --- a/libs/windows/include/H5FDhdfs.h +++ b/libs/windows/include/H5FDhdfs.h @@ -1,21 +1,16 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * - * Read-Only HDFS Virtual File Driver (VFD) * - * Copyright (c) 2018, The HDF Group. * - * * + * Copyright by The HDF Group. * * All rights reserved. * * * - * NOTICE: * - * All information contained herein is, and remains, the property of The HDF * - * Group. The intellectual and technical concepts contained herein are * - * proprietary to The HDF Group. Dissemination of this information or * - * reproduction of this material is strictly forbidden unless prior written * - * permission is obtained from The HDF Group. * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Jacob Smith - * 2018-04-23 - * * Purpose: The public header file for the hdfs driver. */ @@ -23,11 +18,18 @@ #define H5FDhdfs_H #ifdef H5_HAVE_LIBHDFS -#define H5FD_HDFS (H5FD_hdfs_init()) +#define H5FD_HDFS (H5FDperform_init(H5FD_hdfs_init)) +#define H5FD_HDFS_VALUE H5_VFD_HDFS #else /* H5_HAVE_LIBHDFS */ -#define H5FD_HDFS (H5I_INVALID_HID) +#define H5FD_HDFS (H5I_INVALID_HID) +#define H5FD_HDFS_VALUE H5_VFD_INVALID #endif /* H5_HAVE_LIBHDFS */ +#ifdef H5_HAVE_LIBHDFS +#ifdef __cplusplus +extern "C" { +#endif + /**************************************************************************** * * Structure: H5FD_hdfs_fapl_t @@ -85,11 +87,6 @@ * * TBD: If -1, relies on a default value. * - * - * - * Programmer: Jacob Smith - * 2018-04-23 - * ****************************************************************************/ #define H5FD__CURR_HDFS_FAPL_T_VERSION 1 @@ -107,10 +104,6 @@ typedef struct H5FD_hdfs_fapl_t { int32_t stream_buffer_size; } H5FD_hdfs_fapl_t; -#ifdef __cplusplus -extern "C" { -#endif - H5_DLL hid_t H5FD_hdfs_init(void); /** @@ -130,5 +123,6 @@ H5_DLL herr_t H5Pset_fapl_hdfs(hid_t fapl_id, H5FD_hdfs_fapl_t *fa); #ifdef __cplusplus } #endif +#endif /* H5_HAVE_LIBHDFS */ #endif /* ifndef H5FDhdfs_H */ diff --git a/libs/windows/include/H5FDioc.h b/libs/windows/include/H5FDioc.h new file mode 100644 index 0000000..bcacd52 --- /dev/null +++ b/libs/windows/include/H5FDioc.h @@ -0,0 +1,196 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * Purpose: The public header file for the "I/O concentrator" driver. + * This provides a similar functionality to that of the subfiling driver + * but introduces the necessary file access functionality via a multi- + * threading MPI service + */ + +#ifndef H5FDioc_H +#define H5FDioc_H + +#include "H5FDsubfiling.h" + +#ifdef H5_HAVE_IOC_VFD +/** + * \def H5FD_IOC + * Macro that returns the identifier for the #H5FD_IOC driver. \hid_t{file driver} + */ +#define H5FD_IOC (H5FDperform_init(H5FD_ioc_init)) +#else +#define H5FD_IOC (H5I_INVALID_HID) +#endif + +/** + * \def H5FD_IOC_NAME + * The canonical name for the #H5FD_IOC driver + */ +#define H5FD_IOC_NAME "ioc" + +#ifdef H5_HAVE_IOC_VFD + +#ifndef H5FD_IOC_FAPL_MAGIC +/** + * \def H5FD_IOC_CURR_FAPL_VERSION + * The version number of the H5FD_ioc_config_t configuration + * structure for the #H5FD_IOC driver + */ +#define H5FD_IOC_CURR_FAPL_VERSION 1 +/** + * \def H5FD_IOC_FAPL_MAGIC + * Unique number used to distinguish the #H5FD_IOC driver from other HDF5 file drivers + */ +#define H5FD_IOC_FAPL_MAGIC 0xFED21331 +#endif + +/** + * \def H5FD_IOC_DEFAULT_THREAD_POOL_SIZE + * The default number of I/O concentrator worker threads + */ +#define H5FD_IOC_DEFAULT_THREAD_POOL_SIZE 4 + +/* + * Environment variables interpreted by the IOC VFD + */ + +/** + * \def H5FD_IOC_THREAD_POOL_SIZE + * Macro for name of the environment variable that controls/overrides + * the number of I/O concentrator worker threads + * + * The value set for this environment variable is interpreted as an + * int value and must be > 0. + */ +#define H5FD_IOC_THREAD_POOL_SIZE "H5FD_IOC_THREAD_POOL_SIZE" + +//! +/** + * \struct H5FD_ioc_config_t + * \brief Configuration structure for H5Pset_fapl_ioc() / H5Pget_fapl_ioc() + * + * \details H5FD_ioc_config_t is a public structure that is used to pass + * configuration data to the #H5FD_IOC driver via a File Access + * Property List. A pointer to an instance of this structure is + * a parameter to H5Pset_fapl_ioc() and H5Pget_fapl_ioc(). + * + * \var uint32_t H5FD_ioc_config_t::magic + * A somewhat unique number which distinguishes the #H5FD_IOC driver + * from other drivers. Used in combination with a version number, it + * can help to validate a user-generated File Access Property List. + * This field should be set to #H5FD_IOC_FAPL_MAGIC. + * + * \var uint32_t H5FD_ioc_config_t::version + * Version number of the H5FD_ioc_config_t structure. Any instance passed + * to H5Pset_fapl_ioc() / H5Pget_fapl_ioc() must have a recognized version + * number or an error will be raised. Currently, this field should be set + * to #H5FD_IOC_CURR_FAPL_VERSION. + * + * \var int32_t H5FD_ioc_config_t::thread_pool_size + * The number of I/O concentrator worker threads to use. + * + * This value can also be set or adjusted with the #H5FD_IOC_THREAD_POOL_SIZE + * environment variable. + * + */ +typedef struct H5FD_ioc_config_t { + uint32_t magic; /* Must be set to H5FD_IOC_FAPL_MAGIC */ + uint32_t version; /* Must be set to H5FD_IOC_CURR_FAPL_VERSION */ + int32_t thread_pool_size; /* Number of I/O concentrator worker threads to use */ +} H5FD_ioc_config_t; +//! + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \brief Internal routine to initialize #H5FD_IOC driver. Not meant to be + * called directly by an HDF5 application + */ +H5_DLL hid_t H5FD_ioc_init(void); +/** + * \ingroup FAPL + * + * \brief Modifies the specified File Access Property List to use the #H5FD_IOC driver + * + * \fapl_id + * \param[in] vfd_config Pointer to #H5FD_IOC driver configuration structure. May be NULL. + * \returns \herr_t + * + * \details H5Pset_fapl_ioc() modifies the File Access Property List to use the + * #H5FD_IOC driver. + * + * The #H5FD_IOC driver is a reference implementation of an "I/O concentrator" + * file driver that works in conjunction with the #H5FD_SUBFILING driver and + * provides the I/O backend for servicing I/O requests to subfiles. + * + * Typically, an HDF5 application won't need to call this routine directly. + * The #H5FD_IOC driver is usually set up as a side effect of an HDF5 application + * using the #H5FD_SUBFILING driver, but this routine is provided in case the + * application wishes to manually configure the #H5FD_IOC driver. + * + * \note The \p vfd_config parameter may be NULL. In this case, the driver will + * be setup with default settings. Note that in this case, it is assumed + * the parent #H5FD_SUBFILING driver was also setup with default settings. + * If the two drivers differ in configuration settings, application behavior + * may not be as expected. + * + * \since 1.14.0 + * + */ +H5_DLL herr_t H5Pset_fapl_ioc(hid_t fapl_id, H5FD_ioc_config_t *vfd_config); +/** + * \ingroup FAPL + * + * \brief Queries a File Access Property List for #H5FD_IOC file driver properties + * + * \fapl_id + * \param[out] config_out Pointer to H5FD_ioc_config_t structure through which the + * #H5FD_IOC file driver properties will be returned. + * + * \returns \herr_t + * + * \details H5Pget_fapl_ioc() queries the specified File Access Property List for + * #H5FD_IOC driver properties as set by H5Pset_fapl_ioc(). If the #H5FD_IOC + * driver has not been set on the File Access Property List, a default + * configuration is returned. An HDF5 application may use this functionality + * to manually configure the #H5FD_IOC driver by calling H5Pget_fapl_ioc() + * on a newly-created File Access Property List, adjusting the default + * values and then calling H5Pset_fapl_ioc() with the configured + * H5FD_ioc_config_t structure. + * + * \since 1.14.0 + * + */ +H5_DLL herr_t H5Pget_fapl_ioc(hid_t fapl_id, H5FD_ioc_config_t *config_out); +/** + * \brief Internal routine for managing exclusive access to critical sections + * by the #H5FD_IOC driver's worker threads. Not meant to be called + * directly by an HDF5 application + */ +H5_DLL void H5FD_ioc_begin_thread_exclusive(void); +/** + * \brief Internal routine for managing exclusive access to critical sections + * by the #H5FD_IOC driver's worker threads. Not meant to be called + * directly by an HDF5 application + */ +H5_DLL void H5FD_ioc_end_thread_exclusive(void); + +#ifdef __cplusplus +} +#endif + +#endif /* H5_HAVE_IOC_VFD */ + +#endif diff --git a/libs/windows/include/H5FDlog.h b/libs/windows/include/H5FDlog.h index 969c091..ae4e2d0 100644 --- a/libs/windows/include/H5FDlog.h +++ b/libs/windows/include/H5FDlog.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -12,15 +11,13 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Quincey Koziol - * Monday, April 17, 2000 - * * Purpose: The public header file for the log driver. */ #ifndef H5FDlog_H #define H5FDlog_H -#define H5FD_LOG (H5FD_log_init()) +#define H5FD_LOG (H5FDperform_init(H5FD_log_init)) +#define H5FD_LOG_VALUE H5_VFD_LOG /* Flags for H5Pset_fapl_log() */ /* Flags for tracking 'meta' operations (truncate) */ diff --git a/libs/windows/include/H5FDmirror.h b/libs/windows/include/H5FDmirror.h index 49e24c1..b196b2b 100644 --- a/libs/windows/include/H5FDmirror.h +++ b/libs/windows/include/H5FDmirror.h @@ -19,7 +19,8 @@ #ifdef H5_HAVE_MIRROR_VFD -#define H5FD_MIRROR (H5FD_mirror_init()) +#define H5FD_MIRROR (H5FDperform_init(H5FD_mirror_init)) +#define H5FD_MIRROR_VALUE H5_VFD_MIRROR #ifdef __cplusplus extern "C" { @@ -33,7 +34,7 @@ extern "C" { /* --------------------------------------------------------------------------- * Structure: H5FD_mirror_fapl_t * - * Used to pass configuraiton information to the Mirror VFD. + * Used to pass configuration information to the Mirror VFD. * Populate components as appropriate and pass structure pointer to * `H5Pset_fapl_mirror()`. * diff --git a/libs/windows/include/H5FDmpi.h b/libs/windows/include/H5FDmpi.h index cf49301..9cee0e6 100644 --- a/libs/windows/include/H5FDmpi.h +++ b/libs/windows/include/H5FDmpi.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -12,9 +11,6 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Quincey Koziol - * Friday, January 30, 2004 - * * Purpose: The public header file for common items for all MPI VFL drivers */ #ifndef H5FDmpi_H diff --git a/libs/windows/include/H5FDmpio.h b/libs/windows/include/H5FDmpio.h index 8caf11c..96a9366 100644 --- a/libs/windows/include/H5FDmpio.h +++ b/libs/windows/include/H5FDmpio.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -12,9 +11,6 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Robb Matzke - * Monday, August 2, 1999 - * * Purpose: The public header file for the mpio driver. */ #ifndef H5FDmpio_H @@ -23,7 +19,7 @@ /* Macros */ #ifdef H5_HAVE_PARALLEL -#define H5FD_MPIO (H5FD_mpio_init()) +#define H5FD_MPIO (H5FDperform_init(H5FD_mpio_init)) #else #define H5FD_MPIO (H5I_INVALID_HID) #endif /* H5_HAVE_PARALLEL */ @@ -168,18 +164,24 @@ 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 + * \brief Sets low-level 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. + * \details H5Pset_dxpl_mpio_collective_opt() sets the data transfer property + * list \p dxpl_id to use transfer mode \p opt_mode when performing + * I/O. This allows the application to specify collective I/O at the + * HDF5 interface level (with the H5Pset_dxpl_mpio() API routine), + * while controlling whether the actual I/O is performed collectively + * (e.g., via MPI_File_write_at_all) or independently (e.g., via + * MPI_File_write_at). If the collectivity setting at the HDF5 + * interface level (set via H5Pset_dxpl_mpio()) is not set to + * H5FD_MPIO_COLLECTIVE, this setting will be ignored. * - * Valid transfer modes are #H5FD_MPIO_INDEPENDENT (default) and - * #H5FD_MPIO_COLLECTIVE. + * Valid transfer modes are #H5FD_MPIO_COLLECTIVE_IO (default) and + * #H5FD_MPIO_INDIVIDUAL_IO. * * \since 1.4.0 * @@ -223,7 +225,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_collective_opt(hid_t dxpl_id, H5FD_mpio_collectiv * * Use of this function is optional. * - * \todo Add missing version information + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t opt_mode); @@ -247,7 +249,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt(hid_t dxpl_id, H5FD_mpio_chunk_opt_t op * otherwise, a separate I/O process will be invoked for each chunk * (multi-chunk I/O). * - * \todo Add missing version information + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_per_proc); @@ -272,7 +274,7 @@ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_num(hid_t dxpl_id, unsigned num_chunk_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 + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_dxpl_mpio_chunk_opt_ratio(hid_t dxpl_id, unsigned percent_num_proc_per_chunk); diff --git a/libs/windows/include/H5FDmulti.h b/libs/windows/include/H5FDmulti.h index 62cc9c8..a85f2df 100644 --- a/libs/windows/include/H5FDmulti.h +++ b/libs/windows/include/H5FDmulti.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -12,15 +11,12 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Robb Matzke - * Monday, August 2, 1999 - * * Purpose: The public header file for the "multi" driver. */ #ifndef H5FDmulti_H #define H5FDmulti_H -#define H5FD_MULTI (H5FD_multi_init()) +#define H5FD_MULTI (H5FDperform_init(H5FD_multi_init)) #ifdef __cplusplus extern "C" { @@ -38,7 +34,7 @@ H5_DLL hid_t H5FD_multi_init(void); * \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 + * \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 @@ -73,7 +69,7 @@ H5_DLL hid_t H5FD_multi_init(void); * 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 + * 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. @@ -149,7 +145,7 @@ H5_DLL hid_t H5FD_multi_init(void); * * hid_t fapl = H5Pcreate(H5P_FILE_ACCESS); * H5Pset_fapl_multi(fapl, memb_map, memb_fapl, - * memb_name, memb_addr, TRUE); + * memb_name, memb_addr, true); * \endcode * * \version 1.6.3 \p memb_name parameter type changed to \Code{const char* const*}. @@ -169,7 +165,7 @@ H5_DLL herr_t H5Pset_fapl_multi(hid_t fapl_id, const H5FD_mem_t *memb_map, const * \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 + * \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 @@ -227,17 +223,17 @@ H5_DLL herr_t H5Pget_fapl_multi(hid_t fapl_id, H5FD_mem_t *memb_map /*out*/, hid * * \par Example: * \code - * // Example 1: Both metadata and rawdata files are in the same + * // Example 1: Both metadata and raw data files are in the same * // directory. Use Station1-m.h5 and Station1-r.h5 as - * // the metadata and rawdata files. + * // the metadata and raw data 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 + * // Example 2: metadata and raw data files are in different * // directories. Use PointA-m.h5 and /pfs/PointA-r.h5 as - * // the metadata and rawdata files. + * // the metadata and raw data files. * hid_t fapl, fid; * fapl = H5Pcreate(H5P_FILE_ACCESS); * H5Pset_fapl_split(fapl, "-m.h5", H5P_DEFAULT, "/pfs/%s-r.h5", H5P_DEFAULT); diff --git a/libs/windows/include/H5FDonion.h b/libs/windows/include/H5FDonion.h new file mode 100644 index 0000000..09b290e --- /dev/null +++ b/libs/windows/include/H5FDonion.h @@ -0,0 +1,182 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * Onion Virtual File Driver (VFD) + * + * Purpose: The public header file for the Onion VFD. + */ +#ifndef H5FDonion_H +#define H5FDonion_H + +#define H5FD_ONION (H5FDperform_init(H5FD_onion_init)) +#define H5FD_ONION_VALUE H5_VFD_ONION + +/** + * Current version of the onion VFD fapl info struct. + */ +#define H5FD_ONION_FAPL_INFO_VERSION_CURR 1 + +#define H5FD_ONION_FAPL_INFO_CREATE_FLAG_ENABLE_PAGE_ALIGNMENT \ + (0x0001u) /**< \ + * Onion history metadata will align to page_size. \ + * Partial pages of unused space will occur in the file, \ + * but may improve read performance from the backing store \ + * on some systems. \ + * If disabled (0), padding will not be inserted to align \ + * to page boundaries. \ + */ + +/** + * Max length of a comment. + * The buffer is defined to be this size + 1 to handle the NUL. + */ +#define H5FD_ONION_FAPL_INFO_COMMENT_MAX_LEN 255 + +/** + * Indicates that you want the latest revision. + */ +#define H5FD_ONION_FAPL_INFO_REVISION_ID_LATEST UINT64_MAX + +/** + * Indicates how the new onion data will be stored. + */ +typedef enum H5FD_onion_target_file_constant_t { + H5FD_ONION_STORE_TARGET_ONION, /**< + * Onion history is stored in a single, separate "onion + * file". Shares filename and path as hdf5 file (if any), + * with only a different filename extension. + */ +} H5FD_onion_target_file_constant_t; + +/** + * Stores fapl information for creating onion VFD files. + */ +typedef struct H5FD_onion_fapl_info_t { + uint8_t version; /**< + * Future-proofing identifier. Informs struct membership. + * Must equal H5FD_ONION_FAPL_VERSION_CURR to be considered valid. + */ + hid_t backing_fapl_id; /**< + * Backing or 'child' FAPL ID to handle I/O with the + * underlying backing store. It must use the same backing driver as the + * original file. + */ + uint32_t page_size; /**< + * page_size: Size of the amended data pages. If opening an existing file, + * must equal the existing page size or zero. If creating a new + * file or an initial revision of an existing file, must be a + * power of 2. + * + */ + H5FD_onion_target_file_constant_t store_target; /**< + * Identifies where the history data is stored. + */ + uint64_t revision_num; /**< + * Which revision to open. Valid values are 0 (the original file) or the + * revision number of an existing revision. + * H5FD_ONION_FAPL_INFO_REVISION_ID_LATEST refers to the most + * recently-created revision in the history. + */ + uint8_t force_write_open; /**< + * Flag to ignore the write-lock flag in the onion data + * and attempt to open the file write-only anyway. + * This may be relevant if, for example, the library crashed + * while the file was open in write mode and the write-lock + * flag was not cleared. + * Must equal H5FD_ONION_FAPL_FLAG_FORCE_OPEN to enable. + * + */ + uint8_t creation_flags; /**< + * Flag used only when instantiating an onion file. + * If the relevant bit is set to a nonzero value, its feature + * will be enabled. + */ + char comment[H5FD_ONION_FAPL_INFO_COMMENT_MAX_LEN + + 1]; /**< + * User-supplied NULL-terminated comment for a revision to be + * written. + * Cannot be longer than H5FD_ONION_FAPL_COMMENT_MAX_LEN. + * Ignored if part of a FAPL used to open in read mode. + */ +} H5FD_onion_fapl_info_t; + +#ifdef __cplusplus +extern "C" { +#endif + +H5_DLL hid_t H5FD_onion_init(void); + +/** + * -------------------------------------------------------------------------- + * \ingroup FAPL + * + * \brief get the onion info from the file access property list + * + * \fapl_id + * \param[out] fa_out The pointer to the structure H5FD_onion_fapl_info_t + * + * \return \herr_t + * + * \details H5Pget_fapl_onion() retrieves the structure H5FD_onion_fapl_info_t + * from the file access property list that is set for the onion VFD + * driver. + * + * \since 1.14.0 + */ +H5_DLL herr_t H5Pget_fapl_onion(hid_t fapl_id, H5FD_onion_fapl_info_t *fa_out); + +/** + * -------------------------------------------------------------------------- + * \ingroup FAPL + * + * \brief set the onion info for the file access property list + * + * \fapl_id + * \param[in] fa The pointer to the structure H5FD_onion_fapl_info_t + * + * \return \herr_t + * + * \details H5Pset_fapl_onion() sets the structure H5FD_onion_fapl_info_t + * for the file access property list that is set for the onion VFD + * driver. + * + * \since 1.14.0 + */ +H5_DLL herr_t H5Pset_fapl_onion(hid_t fapl_id, const H5FD_onion_fapl_info_t *fa); + +/** + * -------------------------------------------------------------------------- + * \ingroup H5FD + * + * \brief get the number of revisions + * + * \param[in] filename The name of the onion file + * \param[in] fapl_id The ID of the file access property list + * \param[out] revision_count The number of revisions + * + * \return \herr_t + * + * \details H5FDonion_get_revision_count() returns the number of revisions + * for an onion file. It takes the file name and file access property + * list that is set for the onion VFD driver. + * + * + * \since 1.14.0 + */ +H5_DLL herr_t H5FDonion_get_revision_count(const char *filename, hid_t fapl_id, uint64_t *revision_count); + +#ifdef __cplusplus +} +#endif + +#endif /* H5FDonion_H */ diff --git a/libs/windows/include/H5FDpublic.h b/libs/windows/include/H5FDpublic.h index 36f37f0..5f40bff 100644 --- a/libs/windows/include/H5FDpublic.h +++ b/libs/windows/include/H5FDpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -11,147 +10,44 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* - * Programmer: Robb Matzke - * Monday, July 26, 1999 - */ #ifndef H5FDpublic_H #define H5FDpublic_H -#include "H5public.h" -#include "H5Fpublic.h" /*for H5F_close_degree_t */ - -#define H5_HAVE_VFL 1 /*define a convenient app feature test*/ -#define H5FD_VFD_DEFAULT 0 /* Default VFL driver value */ - -/* Types of allocation requests: see H5Fpublic.h */ -typedef enum H5F_mem_t H5FD_mem_t; - -/* Map "fractal heap" header blocks to 'ohdr' type file memory, since its - * a fair amount of work to add a new kind of file memory and they are similar - * enough to object headers and probably too minor to deserve their own type. - * - * Map "fractal heap" indirect blocks to 'ohdr' type file memory, since they - * are similar to fractal heap header blocks. - * - * Map "fractal heap" direct blocks to 'lheap' type file memory, since they - * will be replacing local heaps. - * - * Map "fractal heap" 'huge' objects to 'draw' type file memory, since they - * represent large objects that are directly stored in the file. - * - * -QAK - */ -#define H5FD_MEM_FHEAP_HDR H5FD_MEM_OHDR -#define H5FD_MEM_FHEAP_IBLOCK H5FD_MEM_OHDR -#define H5FD_MEM_FHEAP_DBLOCK H5FD_MEM_LHEAP -#define H5FD_MEM_FHEAP_HUGE_OBJ H5FD_MEM_DRAW - -/* Map "free space" header blocks to 'ohdr' type file memory, since its - * a fair amount of work to add a new kind of file memory and they are similar - * enough to object headers and probably too minor to deserve their own type. - * - * Map "free space" serialized sections to 'lheap' type file memory, since they - * are similar enough to local heap info. - * - * -QAK - */ -#define H5FD_MEM_FSPACE_HDR H5FD_MEM_OHDR -#define H5FD_MEM_FSPACE_SINFO H5FD_MEM_LHEAP - -/* Map "shared object header message" master table to 'ohdr' type file memory, - * since its a fair amount of work to add a new kind of file memory and they are - * similar enough to object headers and probably too minor to deserve their own - * type. - * - * Map "shared object header message" indices to 'btree' type file memory, - * since they are similar enough to B-tree nodes. - * - * -QAK - */ -#define H5FD_MEM_SOHM_TABLE H5FD_MEM_OHDR -#define H5FD_MEM_SOHM_INDEX H5FD_MEM_BTREE +#include "H5public.h" /* Generic Functions */ +#include "H5Fpublic.h" /* Files */ +#include "H5Ipublic.h" /* Identifiers */ -/* Map "extensible array" header blocks to 'ohdr' type file memory, since its - * a fair amount of work to add a new kind of file memory and they are similar - * enough to object headers and probably too minor to deserve their own type. - * - * Map "extensible array" index blocks to 'ohdr' type file memory, since they - * are similar to extensible array header blocks. - * - * Map "extensible array" super blocks to 'btree' type file memory, since they - * are similar enough to B-tree nodes. - * - * Map "extensible array" data blocks & pages to 'lheap' type file memory, since - * they are similar enough to local heap info. - * - * -QAK - */ -#define H5FD_MEM_EARRAY_HDR H5FD_MEM_OHDR -#define H5FD_MEM_EARRAY_IBLOCK H5FD_MEM_OHDR -#define H5FD_MEM_EARRAY_SBLOCK H5FD_MEM_BTREE -#define H5FD_MEM_EARRAY_DBLOCK H5FD_MEM_LHEAP -#define H5FD_MEM_EARRAY_DBLK_PAGE H5FD_MEM_LHEAP +/*****************/ +/* Public Macros */ +/*****************/ -/* Map "fixed array" header blocks to 'ohdr' type file memory, since its - * a fair amount of work to add a new kind of file memory and they are similar - * enough to object headers and probably too minor to deserve their own type. - * - * Map "fixed array" data blocks & pages to 'lheap' type file memory, since - * they are similar enough to local heap info. - * - */ -#define H5FD_MEM_FARRAY_HDR H5FD_MEM_OHDR -#define H5FD_MEM_FARRAY_DBLOCK H5FD_MEM_LHEAP -#define H5FD_MEM_FARRAY_DBLK_PAGE H5FD_MEM_LHEAP +#define H5FD_VFD_DEFAULT 0 /* Default VFL driver value */ -/* - * A free-list map which maps all types of allocation requests to a single - * free list. This is useful for drivers that don't really care about - * keeping different requests segregated in the underlying file and which - * want to make most efficient reuse of freed memory. The use of the - * H5FD_MEM_SUPER free list is arbitrary. +/* VFD identifier values + * These are H5FD_class_value_t values, NOT hid_t values! */ -#define H5FD_FLMAP_SINGLE \ - { \ - H5FD_MEM_SUPER, /*default*/ \ - H5FD_MEM_SUPER, /*super*/ \ - H5FD_MEM_SUPER, /*btree*/ \ - H5FD_MEM_SUPER, /*draw*/ \ - H5FD_MEM_SUPER, /*gheap*/ \ - H5FD_MEM_SUPER, /*lheap*/ \ - H5FD_MEM_SUPER /*ohdr*/ \ - } +#define H5_VFD_INVALID ((H5FD_class_value_t)(-1)) +#define H5_VFD_SEC2 ((H5FD_class_value_t)(0)) +#define H5_VFD_CORE ((H5FD_class_value_t)(1)) +#define H5_VFD_LOG ((H5FD_class_value_t)(2)) +#define H5_VFD_FAMILY ((H5FD_class_value_t)(3)) +#define H5_VFD_MULTI ((H5FD_class_value_t)(4)) +#define H5_VFD_STDIO ((H5FD_class_value_t)(5)) +#define H5_VFD_SPLITTER ((H5FD_class_value_t)(6)) +#define H5_VFD_MPIO ((H5FD_class_value_t)(7)) +#define H5_VFD_DIRECT ((H5FD_class_value_t)(8)) +#define H5_VFD_MIRROR ((H5FD_class_value_t)(9)) +#define H5_VFD_HDFS ((H5FD_class_value_t)(10)) +#define H5_VFD_ROS3 ((H5FD_class_value_t)(11)) +#define H5_VFD_SUBFILING ((H5FD_class_value_t)(12)) +#define H5_VFD_IOC ((H5FD_class_value_t)(13)) +#define H5_VFD_ONION ((H5FD_class_value_t)(14)) -/* - * A free-list map which segregates requests into `raw' or `meta' data - * pools. - */ -#define H5FD_FLMAP_DICHOTOMY \ - { \ - H5FD_MEM_SUPER, /*default*/ \ - H5FD_MEM_SUPER, /*super*/ \ - H5FD_MEM_SUPER, /*btree*/ \ - H5FD_MEM_DRAW, /*draw*/ \ - H5FD_MEM_DRAW, /*gheap*/ \ - H5FD_MEM_SUPER, /*lheap*/ \ - H5FD_MEM_SUPER /*ohdr*/ \ - } +/* VFD IDs below this value are reserved for library use. */ +#define H5_VFD_RESERVED 256 -/* - * The default free list map which causes each request type to use it's own - * free-list. - */ -#define H5FD_FLMAP_DEFAULT \ - { \ - H5FD_MEM_DEFAULT, /*default*/ \ - H5FD_MEM_DEFAULT, /*super*/ \ - H5FD_MEM_DEFAULT, /*btree*/ \ - H5FD_MEM_DEFAULT, /*draw*/ \ - H5FD_MEM_DEFAULT, /*gheap*/ \ - H5FD_MEM_DEFAULT, /*lheap*/ \ - H5FD_MEM_DEFAULT /*ohdr*/ \ - } +/* Maximum VFD ID */ +#define H5_VFD_MAX 65535 /* Define VFL driver features that can be enabled on a per-driver basis */ /* These are returned with the 'query' function pointer in H5FD_class_t */ @@ -180,7 +76,7 @@ typedef enum H5F_mem_t H5FD_mem_t; /* * Defining H5FD_FEAT_DATA_SIEVE for a VFL driver means that * the library will attempt to cache raw data as it is read from/written to - * a file in a "data seive" buffer. See Rajeev Thakur's papers: + * a file in a "data sieve" buffer. See Rajeev Thakur's papers: * http://www.mcs.anl.gov/~thakur/papers/romio-coll.ps.gz * http://www.mcs.anl.gov/~thakur/papers/mpio-high-perf.ps.gz */ @@ -262,71 +158,106 @@ typedef enum H5F_mem_t H5FD_mem_t; * enabled may be used as the Write-Only (W/O) channel driver. */ #define H5FD_FEAT_DEFAULT_VFD_COMPATIBLE 0x00008000 +/* + * Defining H5FD_FEAT_MEMMANAGE for a VFL driver means that + * the driver uses special memory management routines or wishes + * to do memory management in a specific manner. Therefore, HDF5 + * should request that the driver handle any memory management + * operations when appropriate. + */ +#define H5FD_FEAT_MEMMANAGE 0x00010000 + +/* ctl function definitions: */ +#define H5FD_CTL_OPC_RESERVED 512 /* Opcodes below this value are reserved for library use */ +#define H5FD_CTL_OPC_EXPER_MIN \ + H5FD_CTL_OPC_RESERVED /* Minimum opcode value available for experimental use \ + */ +#define H5FD_CTL_OPC_EXPER_MAX \ + (H5FD_CTL_OPC_RESERVED + 511) /* Maximum opcode value available for experimental use */ -/* Forward declaration */ -typedef struct H5FD_t H5FD_t; +/* ctl function op codes: */ +#define H5FD_CTL_INVALID_OPCODE 0 +#define H5FD_CTL_TEST_OPCODE 1 +#define H5FD_CTL_GET_MPI_COMMUNICATOR_OPCODE 2 +#define H5FD_CTL_GET_MPI_RANK_OPCODE 3 +#define H5FD_CTL_GET_MPI_SIZE_OPCODE 4 +#define H5FD_CTL_MEM_ALLOC 5 +#define H5FD_CTL_MEM_FREE 6 +#define H5FD_CTL_MEM_COPY 7 +#define H5FD_CTL_GET_MPI_FILE_SYNC_OPCODE 8 -/* Class information for each file driver */ -typedef struct H5FD_class_t { - const char * name; - haddr_t maxaddr; - H5F_close_degree_t fc_degree; - herr_t (*terminate)(void); - hsize_t (*sb_size)(H5FD_t *file); - herr_t (*sb_encode)(H5FD_t *file, char *name /*out*/, unsigned char *p /*out*/); - herr_t (*sb_decode)(H5FD_t *f, const char *name, const unsigned char *p); - size_t fapl_size; - void *(*fapl_get)(H5FD_t *file); - void *(*fapl_copy)(const void *fapl); - herr_t (*fapl_free)(void *fapl); - size_t dxpl_size; - void *(*dxpl_copy)(const void *dxpl); - herr_t (*dxpl_free)(void *dxpl); - H5FD_t *(*open)(const char *name, unsigned flags, hid_t fapl, haddr_t maxaddr); - herr_t (*close)(H5FD_t *file); - int (*cmp)(const H5FD_t *f1, const H5FD_t *f2); - herr_t (*query)(const H5FD_t *f1, unsigned long *flags); - herr_t (*get_type_map)(const H5FD_t *file, H5FD_mem_t *type_map); - haddr_t (*alloc)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size); - herr_t (*free)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, hsize_t size); - haddr_t (*get_eoa)(const H5FD_t *file, H5FD_mem_t type); - herr_t (*set_eoa)(H5FD_t *file, H5FD_mem_t type, haddr_t addr); - haddr_t (*get_eof)(const H5FD_t *file, H5FD_mem_t type); - herr_t (*get_handle)(H5FD_t *file, hid_t fapl, void **file_handle); - herr_t (*read)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, void *buffer); - herr_t (*write)(H5FD_t *file, H5FD_mem_t type, hid_t dxpl, haddr_t addr, size_t size, const void *buffer); - herr_t (*flush)(H5FD_t *file, hid_t dxpl_id, hbool_t closing); - herr_t (*truncate)(H5FD_t *file, hid_t dxpl_id, hbool_t closing); - herr_t (*lock)(H5FD_t *file, hbool_t rw); - herr_t (*unlock)(H5FD_t *file); - H5FD_mem_t fl_map[H5FD_MEM_NTYPES]; -} H5FD_class_t; +/* ctl function flags: */ -/* A free list is a singly-linked list of address/size pairs. */ -typedef struct H5FD_free_t { - haddr_t addr; - hsize_t size; - struct H5FD_free_t *next; -} H5FD_free_t; +/* Definitions: + * + * WARNING: While the following definitions of Terminal + * and Passthrough VFDs should be workable for now, they + * have to be adjusted as our use cases for VFDs expand. + * + * JRM -- 8/4/21 + * + * + * Terminal VFD: Lowest VFD in the VFD stack through + * which all VFD calls pass. Note that this definition + * is situational. For example, the sec2 VFD is typically + * terminal. However, in the context of the family file + * driver, it is not -- the family file driver is the + * bottom VFD through which all VFD calls pass, and thus + * it is terminal. + * + * Similarly, on the splitter VFD, a sec2 VFD on the + * R/W channel is terminal, but a sec2 VFD on the W/O + * channel is not. + * + * + * Pass through VFD: Any VFD that relays all VFD calls + * (with the possible exception of some non-I/O related + * calls) to underlying VFD(s). + */ + +/* Unknown op codes should be ignored silently unless the + * H5FD_CTL_FAIL_IF_UNKNOWN_FLAG is set. + * + * On terminal VFDs, unknown op codes should generate an + * error unconditionally if this flag is set. + * + * On pass through VFDs, unknown op codes should be routed + * to the underlying VFD(s) as indicated by any routing + * flags. In the absence of such flags, the VFD should + * generate an error. + */ +#define H5FD_CTL_FAIL_IF_UNKNOWN_FLAG 0x0001 + +/* The H5FD_CTL_ROUTE_TO_TERMINAL_VFD_FLAG is used only + * by non-ternminal VFDs, and only applies to unknown + * opcodes. (known op codes should be handled as + * appropriate.) + * + * If this flag is set for an unknown op code, that + * op code should be passed to the next VFD down + * the VFD stack en-route to the terminal VFD. + * If that VFD does not support the ctl call, the + * pass through VFD should fail or succeed as directed + * by the H5FD_CTL_FAIL_IF_UNKNOWN_FLAG. + */ +#define H5FD_CTL_ROUTE_TO_TERMINAL_VFD_FLAG 0x0002 + +/*******************/ +/* Public Typedefs */ +/*******************/ /* - * The main datatype for each driver. Public fields common to all drivers - * are declared here and the driver appends private fields in memory. + * File driver identifiers. + * + * Values 0 through 255 are for drivers defined by the HDF5 library. + * Values 256 through 511 are available for testing new drivers. + * Subsequent values should be obtained from the HDF5 development + * team at mailto:help@hdfgroup.org. */ -struct H5FD_t { - hid_t driver_id; /*driver ID for this file */ - const H5FD_class_t *cls; /*constant class info */ - unsigned long fileno; /* File 'serial' number */ - unsigned access_flags; /* File access flags (from create or open) */ - unsigned long feature_flags; /* VFL Driver feature Flags */ - haddr_t maxaddr; /* For this file, overrides class */ - haddr_t base_addr; /* Base address for HDF5 data w/in file */ +typedef int H5FD_class_value_t; - /* Space allocation management fields */ - hsize_t threshold; /* Threshold for alignment */ - hsize_t alignment; /* Allocation alignment */ - hbool_t paged_aggr; /* Paged aggregation for file space is enabled or not */ -}; +/* Types of allocation requests: see H5Fpublic.h */ +typedef enum H5F_mem_t H5FD_mem_t; /** * Define enum for the source of file image callbacks @@ -383,6 +314,7 @@ typedef struct { /** * \param[in] dest Address of the destination buffer * \param[in] src Address of the source buffer + * \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 @@ -395,6 +327,7 @@ typedef struct { //! /** * \param[in] ptr Pointer to the buffer being reallocated + * \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 @@ -405,6 +338,10 @@ typedef struct { void *(*image_realloc)(void *ptr, size_t size, H5FD_file_image_op_t file_image_op, void *udata); //! /** + * \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 */ @@ -436,33 +373,53 @@ typedef struct { } H5FD_file_image_callbacks_t; //! +/** + * Define structure to hold "ctl memory copy" parameters + */ +//! +typedef struct H5FD_ctl_memcpy_args_t { + void *dstbuf; /**< Destination buffer */ + hsize_t dst_off; /**< Offset within destination buffer */ + const void *srcbuf; /**< Source buffer */ + hsize_t src_off; /**< Offset within source buffer */ + size_t len; /**< Length of data to copy from source buffer */ +} H5FD_ctl_memcpy_args_t; +//! + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ + #ifdef __cplusplus extern "C" { #endif /* Function prototypes */ -H5_DLL hid_t H5FDregister(const H5FD_class_t *cls); -H5_DLL herr_t H5FDunregister(hid_t driver_id); -H5_DLL H5FD_t *H5FDopen(const char *name, unsigned flags, hid_t fapl_id, haddr_t maxaddr); -H5_DLL herr_t H5FDclose(H5FD_t *file); -H5_DLL int H5FDcmp(const H5FD_t *f1, const H5FD_t *f2); -H5_DLL int H5FDquery(const H5FD_t *f, unsigned long *flags); -H5_DLL haddr_t H5FDalloc(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, hsize_t size); -H5_DLL herr_t H5FDfree(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, hsize_t size); -H5_DLL haddr_t H5FDget_eoa(H5FD_t *file, H5FD_mem_t type); -H5_DLL herr_t H5FDset_eoa(H5FD_t *file, H5FD_mem_t type, haddr_t eoa); -H5_DLL haddr_t H5FDget_eof(H5FD_t *file, H5FD_mem_t type); -H5_DLL herr_t H5FDget_vfd_handle(H5FD_t *file, hid_t fapl, void **file_handle); -H5_DLL herr_t H5FDread(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size, - void *buf /*out*/); -H5_DLL herr_t H5FDwrite(H5FD_t *file, H5FD_mem_t type, hid_t dxpl_id, haddr_t addr, size_t size, - const void *buf); -H5_DLL herr_t H5FDflush(H5FD_t *file, hid_t dxpl_id, hbool_t closing); -H5_DLL herr_t H5FDtruncate(H5FD_t *file, hid_t dxpl_id, hbool_t closing); -H5_DLL herr_t H5FDlock(H5FD_t *file, hbool_t rw); -H5_DLL herr_t H5FDunlock(H5FD_t *file); -/* Allows querying a VFD ID for features before the file is opened */ +/** + * \ingroup H5FD + * + * \brief Allows querying a VFD ID for features before the file is opened + * + * \param[in] driver_id Virtual File Driver (VFD) ID + * \param[out] flags VFD flags supported + * + * \return \herr_t + * + * \details Queries a virtual file driver (VFD) for feature flags. Takes a + * VFD hid_t so it can be used before the file is opened. For example, + * this could be used to check if a VFD supports SWMR. + * + * \note The flags obtained here are just those of the base driver and + * do not take any configuration options (e.g., set via a fapl + * call) into consideration. + * + * \since 1.10.2 + */ H5_DLL herr_t H5FDdriver_query(hid_t driver_id, unsigned long *flags /*out*/); #ifdef __cplusplus diff --git a/libs/windows/include/H5FDros3.h b/libs/windows/include/H5FDros3.h index 8e42ca2..ecd2678 100644 --- a/libs/windows/include/H5FDros3.h +++ b/libs/windows/include/H5FDros3.h @@ -13,18 +13,17 @@ /* * Read-Only S3 Virtual File Driver (VFD) * - * Programmer: John Mainzer - * 2017-10-10 - * * Purpose: The public header file for the ros3 driver. */ #ifndef H5FDros3_H #define H5FDros3_H #ifdef H5_HAVE_ROS3_VFD -#define H5FD_ROS3 (H5FD_ros3_init()) +#define H5FD_ROS3 (H5FDperform_init(H5FD_ros3_init)) +#define H5FD_ROS3_VALUE H5_VFD_ROS3 #else -#define H5FD_ROS3 (H5I_INVALID_HID) +#define H5FD_ROS3 (H5I_INVALID_HID) +#define H5FD_ROS3_VALUE H5_VFD_INVALID #endif /* H5_HAVE_ROS3_VFD */ #ifdef H5_HAVE_ROS3_VFD @@ -52,10 +51,10 @@ * * `authenticate` (hbool_t) * - * Flag TRUE or FALSE whether or not requests are to be authenticated + * Flag true or false whether or not requests are to be authenticated * with the AWS4 algorithm. - * If TRUE, `aws_region`, `secret_id`, and `secret_key` must be populated. - * If FALSE, those three components are unused. + * If true, `aws_region`, `secret_id`, and `secret_key` must be populated. + * If false, those three components are unused. * * `aws_region` (char[]) * @@ -71,12 +70,63 @@ * ****************************************************************************/ +/** + * \def H5FD_CURR_ROS3_FAPL_T_VERSION + * The version number of the H5FD_ros3_fapl_t configuration + * structure for the $H5FD_ROS3 driver. + */ #define H5FD_CURR_ROS3_FAPL_T_VERSION 1 -#define H5FD_ROS3_MAX_REGION_LEN 32 -#define H5FD_ROS3_MAX_SECRET_ID_LEN 128 +/** + * \def H5FD_ROS3_MAX_REGION_LEN + * Maximum string length for specifying the region of the S3 bucket. + */ +#define H5FD_ROS3_MAX_REGION_LEN 32 +/** + * \def H5FD_ROS3_MAX_SECRET_ID_LEN + * Maximum string length for specifying the security ID. + */ +#define H5FD_ROS3_MAX_SECRET_ID_LEN 128 +/** + * \def H5FD_ROS3_MAX_SECRET_KEY_LEN + * Maximum string length for specifying the security key. + */ #define H5FD_ROS3_MAX_SECRET_KEY_LEN 128 +/** + * \def H5FD_ROS3_MAX_SECRET_TOK_LEN + * Maximum string length for specifying the session/security token. + */ +#define H5FD_ROS3_MAX_SECRET_TOK_LEN 1024 +/** + *\struct H5FD_ros3_fapl_t + * \brief Configuration structure for H5Pset_fapl_ros3() / H5Pget_fapl_ros3(). + * + * \details H5FD_ros_fapl_t is a public structure that is used to pass + * configuration data to the #H5FD_ROS3 driver via a File Access + * Property List. A pointer to an instance of this structure is + * a parameter to H5Pset_fapl_ros3() and H5Pget_fapl_ros3(). + * + * \var int32_t H5FD_ros3_fapl_t::version + * Version number of the H5FD_ros3_fapl_t structure. Any instance passed + * to H5Pset_fapl_ros3() / H5Pget_fapl_ros3() must have a recognized version + * number or an error will be raised. Currently, this field should be set + * to #H5FD_CURR_ROS3_FAPL_T_VERSION. + * + * \var hbool_t H5FD_ros3_fapl_t::authenticate + * A Boolean which specifies if security credentials should be used for + * accessing a S3 bucket. + * + * \var char H5FD_ros3_fapl_t::aws_region[H5FD_ROS3_MAX_REGION_LEN + 1] + * A string which specifies the AWS region of the S3 bucket. + * + * \var char H5FD_ros3_fapl_t::secret_id[H5FD_ROS3_MAX_SECRET_ID_LEN + 1] + * A string which specifies the security ID. + * + * \var char H5FD_ros3_fapl_t::secret_key[H5FD_ROS3_MAX_SECRET_KEY_LEN + 1] + * A string which specifies the security key. + * + */ typedef struct H5FD_ros3_fapl_t { int32_t version; hbool_t authenticate; @@ -89,21 +139,71 @@ typedef struct H5FD_ros3_fapl_t { extern "C" { #endif +/** + * \brief Internal routine to initialize #H5FD_ROS3 driver. Not meant to be + * called directly by an HDF5 application. + */ H5_DLL hid_t H5FD_ros3_init(void); /** * \ingroup FAPL * - * \todo Add missing documentation + * \brief Queries a File Access Property List for #H5FD_ROS3 file driver properties. + * + * \fapl_id + * \param[out] fa_out Pointer to #H5FD_ROS3 driver configuration structure. + * \returns \herr_t */ H5_DLL herr_t H5Pget_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa_out); /** * \ingroup FAPL * - * \todo Add missing documentation + * \brief Modifies the specified File Access Property List to use the #H5FD_ROS3 driver. + * + * \fapl_id + * \param[in] fa Pointer to #H5FD_ROS3 driver configuration structure. + * \returns \herr_t + */ +H5_DLL herr_t H5Pset_fapl_ros3(hid_t fapl_id, const H5FD_ros3_fapl_t *fa); + +/** + * \ingroup FAPL + * + * \brief Queries a File Access Property List for #H5FD_ROS3 file driver session/security + * token. + * + * \fapl_id + * \param[in] size Size of the provided char array for storing the session/security token. + * \param[out] token Session/security token. + * \returns \herr_t + * + * \since 1.14.2 + */ +H5_DLL herr_t H5Pget_fapl_ros3_token(hid_t fapl_id, size_t size, char *token); + +/** + * \ingroup FAPL + * + * \brief Modifies the specified File Access Property List to use the #H5FD_ROS3 driver + * by adding the specified session/security token. + * + * \fapl_id + * \param[in] token Session/security token. + * \returns \herr_t + * + * \details H5Pset_fapl_ros3_token() modifies an existing File Access Property List which + * is used by #H5FD_ROS3 driver by adding or updating the session/security token + * of the property list. Be aware, to set the token first you need to create + * a proper File Access Property List using H5Pset_fapl_ros() and use this list + * as input argument of the function H5Pset_fapl_ros3_token(). + * + * Note, the session token is only needed when you want to access a S3 bucket + * using temporary security credentials. + * + * \since 1.14.2 */ -H5_DLL herr_t H5Pset_fapl_ros3(hid_t fapl_id, H5FD_ros3_fapl_t *fa); +H5_DLL herr_t H5Pset_fapl_ros3_token(hid_t fapl_id, const char *token); #ifdef __cplusplus } diff --git a/libs/windows/include/H5FDs3comms.h b/libs/windows/include/H5FDs3comms.h index da6a62d..120a71a 100644 --- a/libs/windows/include/H5FDs3comms.h +++ b/libs/windows/include/H5FDs3comms.h @@ -45,11 +45,6 @@ * ``` * ...in destination buffer. * - * TODO: put documentation in a consistent place and point to it from here. - * - * Programmer: Jacob Smith - * 2017-11-30 - * *****************************************************************************/ #include "H5private.h" /* Generic Functions */ @@ -135,7 +130,7 @@ * * Format "S3 Credential" string from inputs, for AWS4. * - * Wrapper for HDsnprintf(). + * Wrapper for snprintf(). * * _HAS NO ERROR-CHECKING FACILITIES_ * It is left to programmer to ensure that return value confers success. @@ -158,8 +153,8 @@ *--------------------------------------------------------------------------- */ #define S3COMMS_FORMAT_CREDENTIAL(dest, access, iso8601_date, region, service) \ - HDsnprintf((dest), S3COMMS_MAX_CREDENTIAL_SIZE, "%s/%s/%s/%s/aws4_request", (access), (iso8601_date), \ - (region), (service)) + snprintf((dest), S3COMMS_MAX_CREDENTIAL_SIZE, "%s/%s/%s/%s/aws4_request", (access), (iso8601_date), \ + (region), (service)) /********************* * PUBLIC STRUCTURES * @@ -179,7 +174,7 @@ * HTTP header fields, of particular use when composing an * "S3 Canonical Request" for authentication. * - * - The creation of a Canoncial Request involves: + * - The creation of a Canonical Request involves: * - convert field names to lower case * - sort by this lower-case name * - convert ": " name-value separator in HTTP string to ":" @@ -216,7 +211,7 @@ * * `magic` (unsigned long) * - * "unique" idenfier number for the structure type + * "unique" identifier number for the structure type * * `name` (char *) * @@ -249,10 +244,10 @@ */ typedef struct hrb_node_t { unsigned long magic; - char * name; - char * value; - char * cat; - char * lowername; + char *name; + char *value; + char *cat; + char *lowername; struct hrb_node_t *next; } hrb_node_t; #define S3COMMS_HRB_NODE_MAGIC 0x7F5757UL @@ -325,12 +320,12 @@ typedef struct hrb_node_t { */ typedef struct { unsigned long magic; - char * body; + char *body; size_t body_len; - hrb_node_t * first_header; - char * resource; - char * verb; - char * version; + hrb_node_t *first_header; + char *resource; + char *verb; + char *version; } hrb_t; #define S3COMMS_HRB_MAGIC 0x6DCC84UL @@ -388,11 +383,11 @@ typedef struct { */ typedef struct { unsigned long magic; - char * scheme; /* required */ - char * host; /* required */ - char * port; - char * path; - char * query; + char *scheme; /* required */ + char *host; /* required */ + char *port; + char *path; + char *query; } parsed_url_t; #define S3COMMS_PARSED_URL_MAGIC 0x21D0DFUL @@ -459,30 +454,31 @@ typedef struct { * * Pointer to NULL-terminated string for "secret" access id to S3 resource. * - * Requred to authenticate. + * Required to authenticate. * * `signing_key` (unsigned char *) * - * Pointer to `SHA256_DIGEST_LENGTH`-long string for "re-usable" signing + * Pointer to `SHA256_DIGEST_LENGTH`-long string for "reusable" signing * key, generated via * `HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("AWS4", * ""), ""), "aws4_request")` * which may be re-used for several (up to seven (7)) days from creation? * Computed once upon file open. * - * Requred to authenticate. + * Required to authenticate. * *---------------------------------------------------------------------------- */ typedef struct { unsigned long magic; - CURL * curlhandle; + CURL *curlhandle; size_t filesize; - char * httpverb; - parsed_url_t * purl; - char * region; - char * secret_id; + char *httpverb; + parsed_url_t *purl; + char *region; + char *secret_id; unsigned char *signing_key; + char *token; } s3r_t; #define S3COMMS_S3R_MAGIC 0x44d8d79 @@ -514,7 +510,7 @@ H5_DLL herr_t H5FD_s3comms_s3r_close(s3r_t *handle); H5_DLL size_t H5FD_s3comms_s3r_get_filesize(s3r_t *handle); H5_DLL s3r_t *H5FD_s3comms_s3r_open(const char url[], const char region[], const char id[], - const unsigned char signing_key[]); + const unsigned char signing_key[], const char token[]); H5_DLL herr_t H5FD_s3comms_s3r_read(s3r_t *handle, haddr_t offset, size_t len, void *dest); @@ -527,8 +523,7 @@ H5_DLL struct tm *gmnow(void); H5_DLL herr_t H5FD_s3comms_aws_canonical_request(char *canonical_request_dest, int cr_size, char *signed_headers_dest, int sh_size, hrb_t *http_request); -H5_DLL herr_t H5FD_s3comms_bytes_to_hex(char *dest, const unsigned char *msg, size_t msg_len, - hbool_t lowercase); +H5_DLL herr_t H5FD_s3comms_bytes_to_hex(char *dest, const unsigned char *msg, size_t msg_len, bool lowercase); H5_DLL herr_t H5FD_s3comms_free_purl(parsed_url_t *purl); @@ -552,7 +547,7 @@ H5_DLL herr_t H5FD_s3comms_tostringtosign(char *dest, const char *req_str, const H5_DLL herr_t H5FD_s3comms_trim(char *dest, char *s, size_t s_len, size_t *n_written); -H5_DLL herr_t H5FD_s3comms_uriencode(char *dest, const char *s, size_t s_len, hbool_t encode_slash, +H5_DLL herr_t H5FD_s3comms_uriencode(char *dest, const char *s, size_t s_len, bool encode_slash, size_t *n_written); #ifdef __cplusplus diff --git a/libs/windows/include/H5FDsec2.h b/libs/windows/include/H5FDsec2.h index 541ac71..a2590ae 100644 --- a/libs/windows/include/H5FDsec2.h +++ b/libs/windows/include/H5FDsec2.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -12,21 +11,35 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Robb Matzke - * Monday, August 2, 1999 - * - * Purpose: The public header file for the sec2 driver. + * Purpose: The public header file for the sec2 driver */ #ifndef H5FDsec2_H #define H5FDsec2_H -#define H5FD_SEC2 (H5FD_sec2_init()) +#define H5FD_SEC2 (H5FDperform_init(H5FD_sec2_init)) +#define H5FD_SEC2_VALUE H5_VFD_SEC2 #ifdef __cplusplus extern "C" { #endif -H5_DLL hid_t H5FD_sec2_init(void); +H5_DLL hid_t H5FD_sec2_init(void); + +/** + * \ingroup FAPL + * + * \brief Modifies the file access property list to use the #H5FD_SEC2 driver + * + * \fapl_id + * + * \returns \herr_t + * + * \details H5Pset_fapl_sec2() modifies the file access property list to use the + * #H5FD_SEC2 driver. + * + * \since 1.4.0 + * + */ H5_DLL herr_t H5Pset_fapl_sec2(hid_t fapl_id); #ifdef __cplusplus diff --git a/libs/windows/include/H5FDsplitter.h b/libs/windows/include/H5FDsplitter.h index ee6e7c5..c8751c8 100644 --- a/libs/windows/include/H5FDsplitter.h +++ b/libs/windows/include/H5FDsplitter.h @@ -17,7 +17,8 @@ #ifndef H5FDsplitter_H #define H5FDsplitter_H -#define H5FD_SPLITTER (H5FD_splitter_init()) +#define H5FD_SPLITTER (H5FDperform_init(H5FD_splitter_init)) +#define H5FD_SPLITTER_VALUE H5_VFD_SPLITTER /* The version of the H5FD_splitter_vfd_config_t structure used */ #define H5FD_CURR_SPLITTER_VFD_CONFIG_VERSION 1 @@ -34,7 +35,7 @@ * Structure: H5FD_spliiter_vfd_config_t * * One-stop shopping for configuring a Splitter VFD (rather than many - * paramaters passed into H5Pset/get functions). + * parameters passed into H5Pset/get functions). * * magic (int32_t) * Semi-unique number, used to sanity-check that a given pointer is diff --git a/libs/windows/include/H5FDstdio.h b/libs/windows/include/H5FDstdio.h index 9db92ed..e2e05a7 100644 --- a/libs/windows/include/H5FDstdio.h +++ b/libs/windows/include/H5FDstdio.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -12,17 +11,14 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Robb Matzke - * Monday, August 2, 1999 - * - * Purpose: The public header file for the sec2 driver. + * Purpose: The public header file for the C stdio driver */ #ifndef H5FDstdio_H #define H5FDstdio_H #include "H5Ipublic.h" -#define H5FD_STDIO (H5FD_stdio_init()) +#define H5FD_STDIO (H5FDperform_init(H5FD_stdio_init)) #ifdef __cplusplus extern "C" { diff --git a/libs/windows/include/H5FDsubfiling.h b/libs/windows/include/H5FDsubfiling.h new file mode 100644 index 0000000..d6d2ffd --- /dev/null +++ b/libs/windows/include/H5FDsubfiling.h @@ -0,0 +1,415 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* Purpose: The public header file for the subfiling driver. */ +#ifndef H5FDsubfiling_H +#define H5FDsubfiling_H + +#ifdef H5_HAVE_SUBFILING_VFD +/** + * \def H5FD_SUBFILING + * Macro that returns the identifier for the #H5FD_SUBFILING driver. \hid_t{file driver} + */ +#define H5FD_SUBFILING (H5FDperform_init(H5FD_subfiling_init)) +#else +#define H5FD_SUBFILING (H5I_INVALID_HID) +#endif + +/** + * \def H5FD_SUBFILING_NAME + * The canonical name for the #H5FD_SUBFILING driver + */ +#define H5FD_SUBFILING_NAME "subfiling" + +#ifdef H5_HAVE_SUBFILING_VFD + +#ifndef H5FD_SUBFILING_FAPL_MAGIC +/** + * \def H5FD_SUBFILING_CURR_FAPL_VERSION + * The version number of the H5FD_subfiling_config_t configuration + * structure for the #H5FD_SUBFILING driver + */ +#define H5FD_SUBFILING_CURR_FAPL_VERSION 1 +/** + * \def H5FD_SUBFILING_FAPL_MAGIC + * Unique number used to distinguish the #H5FD_SUBFILING driver from other HDF5 file drivers + */ +#define H5FD_SUBFILING_FAPL_MAGIC 0xFED01331 +#endif + +/** + * \def H5FD_SUBFILING_DEFAULT_STRIPE_SIZE + * The default stripe size (in bytes) for data stripes in subfiles + */ +#define H5FD_SUBFILING_DEFAULT_STRIPE_SIZE (32 * 1024 * 1024) + +/** + * \def H5FD_SUBFILING_DEFAULT_STRIPE_COUNT + * Macro for the default Subfiling stripe count value. The default + * is currently to use one subfile per node. + */ +#define H5FD_SUBFILING_DEFAULT_STRIPE_COUNT -1 + +/** + * \def H5FD_SUBFILING_FILENAME_TEMPLATE + * The basic printf-style template for a #H5FD_SUBFILING driver + * subfile filename. The format specifiers correspond to: + * + * \par \%s + * base filename, e.g. "file.h5" + * + * \par \%PRIu64 + * file inode, e.g. 11273556 + * + * \par \%0*d + * number (starting at 1) signifying the Nth (out of + * total number of subfiles) subfile. Zero-padded + * according to the number of digits in the number of + * subfiles (calculated by log10(num_subfiles) + 1) + * + * \par \%d + * number of subfiles + * + * yielding filenames such as: + * + * file.h5.subfile_11273556_01_of_10 \n + * file.h5.subfile_11273556_02_of_10 \n + * file.h5.subfile_11273556_10_of_10 \n + */ +#define H5FD_SUBFILING_FILENAME_TEMPLATE "%s.subfile_%" PRIu64 "_%0*d_of_%d" + +/** + * \def H5FD_SUBFILING_CONFIG_FILENAME_TEMPLATE + * The basic printf-style template for a #H5FD_SUBFILING driver + * configuration filename. The format specifiers correspond to: + * + * \par \%s + * base filename, e.g. "file.h5" + * + * \par \%PRIu64 + * file inode, e.g. 11273556 + * + * yielding a filename such as: + * + * file.h5.subfile_11273556.config + */ +#define H5FD_SUBFILING_CONFIG_FILENAME_TEMPLATE "%s.subfile_%" PRIu64 ".config" + +/* + * Environment variables interpreted by the HDF5 Subfiling feature + */ + +/** + * \def H5FD_SUBFILING_STRIPE_SIZE + * Macro for name of the environment variable that specifies the size + * (in bytes) for data stripes in subfiles + * + * The value set for this environment variable is interpreted as a + * long long value and must be > 0. + */ +#define H5FD_SUBFILING_STRIPE_SIZE "H5FD_SUBFILING_STRIPE_SIZE" +/** + * \def H5FD_SUBFILING_IOC_PER_NODE + * Macro for name of the environment variable that specifies the number + * of MPI ranks per node to use as I/O concentrators + * + * The value set for this environment variable is interpreted as a + * long value and must be > 0. + */ +#define H5FD_SUBFILING_IOC_PER_NODE "H5FD_SUBFILING_IOC_PER_NODE" +/** + * \def H5FD_SUBFILING_IOC_SELECTION_CRITERIA + * Macro for name of the environment variable that provides information + * for selection MPI ranks as I/O concentrators + * + * The value set for this environment variable is interpreted differently, + * depending on the IOC selection method chosen. + * + * For #SELECT_IOC_ONE_PER_NODE, this value is ignored. + * + * For #SELECT_IOC_EVERY_NTH_RANK, this value is interpreted as a + * long value and must be > 0. The value will correspond to the + * `N` value when selecting every `N`-th MPI rank as an I/O + * concentrator. + * + * For #SELECT_IOC_WITH_CONFIG, this value is ignored as that particular + * IOC selection method is not currently supported. + * + * For #SELECT_IOC_TOTAL, this value is interpreted as a long value + * and must be > 0. The value will correspond to the total number + * of I/O concentrators to be used. + */ +#define H5FD_SUBFILING_IOC_SELECTION_CRITERIA "H5FD_SUBFILING_IOC_SELECTION_CRITERIA" +/** + * \def H5FD_SUBFILING_SUBFILE_PREFIX + * Macro for name of the environment variable that specifies a prefix + * to apply to the filenames generated for subfiles + * + * The value set for this environment variable is interpreted as a + * pathname. + */ +#define H5FD_SUBFILING_SUBFILE_PREFIX "H5FD_SUBFILING_SUBFILE_PREFIX" +/** + * \def H5FD_SUBFILING_CONFIG_FILE_PREFIX + * Macro for name of the environment variable that specifies a prefix + * to apply to the subfiling configuration filename. Useful for cases + * where the application wants to place the configuration file in a + * different directory than the default of putting it alongside the + * generated subfiles. For example, when writing to node-local storage + * one may wish to place the configuration file on a scratch file + * system readable by all nodes, while the subfiles are initially + * written to the node-local storage. + * + * The value set for this environment variable is interpreted as a + * pathname that must already exist. + * + * NOTE: As this prefix string will be encoded in the driver info + * message that gets written to the file, there is an upper + * limit of about ~900 single-byte characters for this string, + * though possibly less due to other information the driver + * may encode. Avoid long prefix names where possible. + */ +#define H5FD_SUBFILING_CONFIG_FILE_PREFIX "H5FD_SUBFILING_CONFIG_FILE_PREFIX" + +/** + * \enum H5FD_subfiling_ioc_select_t + * This enum defines the various constants to allow different + * allocations of MPI ranks as I/O concentrators. + * + * \var SELECT_IOC_ONE_PER_NODE + * Default selection method. One MPI rank per node is used as an + * I/O concentrator. If this selection method is used, the number + * of I/O concentrators per node can be adjusted with the + * #H5FD_SUBFILING_IOC_PER_NODE environment variable. + * + * \var SELECT_IOC_EVERY_NTH_RANK + * Starting with MPI rank 0, a stride of 'N' is applied to the MPI + * rank values to determine the next I/O concentrator. The + * #H5FD_SUBFILING_IOC_SELECTION_CRITERIA environment variable must + * be set to the value desired for 'N'. + * + * \var SELECT_IOC_WITH_CONFIG + * Currently unsupported. Use a configuration file to determine + * the mapping from MPI ranks to I/O concentrators. The + * #H5FD_SUBFILING_IOC_SELECTION_CRITERIA environment variable must + * be set to the path to the configuration file. + * + * \var SELECT_IOC_TOTAL + * Specifies that a total of 'N' I/O concentrators should be used. + * Starting with MPI rank 0, a stride of 'MPI comm size' / 'N' is + * applied to the MPI rank values to determine the next I/O + * concentrator. The #H5FD_SUBFILING_IOC_SELECTION_CRITERIA + * environment variable must be set to the value desired for 'N'. + * + * \var ioc_selection_options + * Unused. Sentinel value + */ +typedef enum { + SELECT_IOC_ONE_PER_NODE = 0, /* Default */ + SELECT_IOC_EVERY_NTH_RANK, /* Starting at rank 0, select-next += N */ + SELECT_IOC_WITH_CONFIG, /* NOT IMPLEMENTED: Read-from-file */ + SELECT_IOC_TOTAL, /* Starting at rank 0, mpi_size / total */ + ioc_selection_options /* Sentinel value */ + /* NOTE: Add to the Fortran constants (H5f90global.F90) when adding new entries */ +} H5FD_subfiling_ioc_select_t; + +/** + * \struct H5FD_subfiling_params_t + * \brief Subfiling parameter structure that is shared between the #H5FD_SUBFILING + * and #H5FD_IOC drivers + * + * \var H5FD_subfiling_ioc_select_t H5FD_subfiling_params_t::ioc_selection + * The method to use for selecting MPI ranks to be I/O concentrators. The + * current default is to select one MPI rank per node to be an I/O concentrator. + * Refer to #H5FD_subfiling_ioc_select_t for a description of the algorithms + * available for use. + * + * \var int64_t H5FD_subfiling_params_t::stripe_size + * The stripe size defines the size (in bytes) of the data stripes in the + * subfiles for the logical HDF5 file. Data is striped across the subfiles + * in a round-robin wrap-around fashion in segments equal to the stripe size. + * + * For example, in an HDF5 file consisting of four subfiles with a 1MiB stripe + * size, the first and fifth 1MiB of data would reside in the first subfile, + * the second and sixth 1MiB of data would reside in the second subfile and so + * on. + * + * This value can also be set or adjusted with the #H5FD_SUBFILING_STRIPE_SIZE + * environment variable. + * + * \var int32_t H5FD_subfiling_params_t::stripe_count + * The target number of subfiles to use for the logical HDF5 file. The current + * default is to use one subfile per node, but it can be useful to set a + * different target number of subfiles, especially if the HDF5 application will + * pre-create the HDF5 file on a single MPI rank. In that particular case, the + * single rank will need to know how many subfiles the logical HDF5 file will + * consist of in order to properly pre-create the file. + * + * This value is used in conjunction with the IOC selection method to determine + * which MPI ranks will be assigned as I/O concentrators. Alternatively, the + * mapping between MPI ranks and I/O concentrators can be set or adjusted with a + * combination of the #ioc_selection field and the #H5FD_SUBFILING_IOC_PER_NODE + * and #H5FD_SUBFILING_IOC_SELECTION_CRITERIA environment variables. + */ +typedef struct H5FD_subfiling_params_t { + H5FD_subfiling_ioc_select_t ioc_selection; /* Method to select I/O concentrators */ + int64_t stripe_size; /* Size (in bytes) of data stripes in subfiles */ + int32_t stripe_count; /* Target number of subfiles to use */ +} H5FD_subfiling_params_t; + +//! +/** + * \struct H5FD_subfiling_config_t + * \brief Configuration structure for H5Pset_fapl_subfiling() / H5Pget_fapl_subfiling() + * + * \details H5FD_subfiling_config_t is a public structure that is used to pass + * subfiling configuration data to the #H5FD_SUBFILING driver via + * a File Access Property List. A pointer to an instance of this structure + * is a parameter to H5Pset_fapl_subfiling() and H5Pget_fapl_subfiling(). + * + * \var uint32_t H5FD_subfiling_config_t::magic + * A somewhat unique number which distinguishes the #H5FD_SUBFILING driver + * from other drivers. Used in combination with a version number, it can + * help to validate a user-generated File Access Property List. This field + * should be set to #H5FD_SUBFILING_FAPL_MAGIC. + * + * \var uint32_t H5FD_subfiling_config_t::version + * Version number of the H5FD_subfiling_config_t structure. Any instance + * passed to H5Pset_fapl_subfiling() / H5Pget_fapl_subfiling() must have + * a recognized version number or an error will be raised. Currently, this + * field should be set to #H5FD_SUBFILING_CURR_FAPL_VERSION. + * + * \var hid_t H5FD_subfiling_config_t::ioc_fapl_id + * The File Access Property List which is setup with the file driver that + * the #H5FD_SUBFILING driver will use for servicing I/O requests to the + * subfiles. Currently, the File Access Property List must be setup with + * the #H5FD_IOC driver by calling H5Pset_fapl_ioc(), but future development + * may allow other file drivers to be used. + * + * \var bool H5FD_subfiling_config_t::require_ioc + * A boolean flag which indicates whether the #H5FD_SUBFILING driver should + * use the #H5FD_IOC driver for its I/O operations. This field should currently + * always be set to true. + * + * \var H5FD_subfiling_params_t H5FD_subfiling_config_t::shared_cfg + * A structure which contains the subfiling parameters that are shared between + * the #H5FD_SUBFILING and #H5FD_IOC drivers. This includes the subfile stripe + * size, stripe count, IOC selection method, etc. + * + */ +typedef struct H5FD_subfiling_config_t { + uint32_t magic; /* Must be set to H5FD_SUBFILING_FAPL_MAGIC */ + uint32_t version; /* Must be set to H5FD_SUBFILING_CURR_FAPL_VERSION */ + hid_t ioc_fapl_id; /* The FAPL setup with the stacked VFD to use for I/O concentrators */ + bool require_ioc; /* Whether to use the IOC VFD (currently must always be true) */ + H5FD_subfiling_params_t shared_cfg; /* Subfiling/IOC parameters (stripe size, stripe count, etc.) */ +} H5FD_subfiling_config_t; +//! + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \brief Internal routine to initialize #H5FD_SUBFILING driver. Not meant to be + * called directly by an HDF5 application + */ +H5_DLL hid_t H5FD_subfiling_init(void); +/** + * \ingroup FAPL + * + * \brief Modifies the specified File Access Property List to use the #H5FD_SUBFILING driver + * + * \fapl_id + * \param[in] vfd_config Pointer to #H5FD_SUBFILING driver configuration structure. May be NULL. + * \returns \herr_t + * + * \details H5Pset_fapl_subfiling() modifies the File Access Property List to use the + * #H5FD_SUBFILING driver. + * + * The #H5FD_SUBFILING driver is an MPI-based file driver that allows an + * HDF5 application to distribute a logical HDF5 file across a collection + * of "subfiles" in equal-sized data segment "stripes". I/O to the logical + * HDF5 file is then directed to the appropriate "subfile" according to the + * #H5FD_SUBFILING configuration and a system of I/O concentrators, which + * are MPI ranks operating worker threads. + * + * By allowing a configurable stripe size, number of I/O concentrators and + * method for selecting MPI ranks as I/O concentrators, the #H5FD_SUBFILING + * driver aims to enable an HDF5 application to find a middle ground between + * the single shared file and file-per-process approaches to parallel file I/O + * for the particular machine the application is running on. In general, the + * goal is to avoid some of the complexity of the file-per-process approach + * while also minimizing the locking issues of the single shared file approach + * on a parallel file system. + * + * \note Since the #H5FD_SUBFILING driver is an MPI-based file driver, the HDF5 + * application should ensure that H5Pset_mpi_params() is called before this + * routine so that the appropriate MPI communicator and info objects will be + * setup for use by the #H5FD_SUBFILING and #H5FD_IOC drivers. + * + * \note The current architecture of the #H5FD_SUBFILING driver requires that the + * HDF5 application must have been initialized with MPI_Init_thread() using + * a value of MPI_THREAD_MULTIPLE for the thread support level. + * + * \note The \p vfd_config parameter may be NULL. In this case, the reference + * implementation I/O concentrator VFD will be used with the default settings + * of one I/O concentrator per node and a stripe size of 32MiB. Refer to the + * H5FD_subfiling_config_t documentation for information about configuration + * for the #H5FD_SUBFILING driver. + * + * \since 1.14.0 + * + */ +H5_DLL herr_t H5Pset_fapl_subfiling(hid_t fapl_id, const H5FD_subfiling_config_t *vfd_config); +/** + * \ingroup FAPL + * + * \brief Queries a File Access Property List for #H5FD_SUBFILING file driver properties + * + * \fapl_id + * \param[out] config_out Pointer to H5FD_subfiling_config_t structure through which the + * #H5FD_SUBFILING file driver properties will be returned. + * + * \returns \herr_t + * + * \details H5Pget_fapl_subfiling() queries the specified File Access Property List for + * #H5FD_SUBFILING driver properties as set by H5Pset_fapl_subfiling(). If the + * #H5FD_SUBFILING driver has not been set on the File Access Property List, a + * default configuration is returned. An HDF5 application may use this + * functionality to manually configure the #H5FD_SUBFILING driver by calling + * H5Pget_fapl_subfiling() on a newly-created File Access Property List, adjusting + * the default values and then calling H5Pset_fapl_subfiling() with the configured + * H5FD_subfiling_config_t structure. + * + * \note H5Pget_fapl_subfiling() returns the #H5FD_SUBFILING driver properties as they + * were initially set for the File Access Property List using H5Pset_fapl_subfiling(). + * Alternatively, the driver properties can be modified at runtime according to values + * set for the #H5FD_SUBFILING_STRIPE_SIZE, #H5FD_SUBFILING_IOC_PER_NODE and + * #H5FD_SUBFILING_IOC_SELECTION_CRITERIA environment variables. However, driver + * properties set through environment variables will not be reflected in what is + * returned by H5Pget_fapl_subfiling(), so an application may need to check those + * environment variables to get accurate values for the #H5FD_SUBFILING driver + * properties. + * + * \since 1.14.0 + * + */ +H5_DLL herr_t H5Pget_fapl_subfiling(hid_t fapl_id, H5FD_subfiling_config_t *config_out); + +#ifdef __cplusplus +} +#endif + +#endif /* H5_HAVE_SUBFILING_VFD */ + +#endif /* H5FDsubfiling_H */ diff --git a/libs/windows/include/H5FDwindows.h b/libs/windows/include/H5FDwindows.h index 79e73b6..14f6985 100644 --- a/libs/windows/include/H5FDwindows.h +++ b/libs/windows/include/H5FDwindows.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -12,11 +11,7 @@ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* - * Programmer: Scott Wegner - * Based on code by Robb Matzke - * Thursday, May 24 2007 - * - * Purpose: The public header file for the windows driver. + * Purpose: The public header file for the Windows driver */ #ifndef H5FDwindows_H #define H5FDwindows_H @@ -49,7 +44,7 @@ extern "C" { * comes. * * Only the Windows driver is tested on Windows systems; other drivers - * are used at the application’s and the user’s risk. + * 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. diff --git a/libs/windows/include/H5FaccProp.h b/libs/windows/include/H5FaccProp.h index 998f870..27028a2 100644 --- a/libs/windows/include/H5FaccProp.h +++ b/libs/windows/include/H5FaccProp.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -137,7 +136,7 @@ class H5_DLLCPP FileAccPropList : public PropList { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("FileAccPropList"); } @@ -150,7 +149,7 @@ class H5_DLLCPP FileAccPropList : public PropList { FileAccPropList(const hid_t plist_id); // Noop destructor - virtual ~FileAccPropList(); + virtual ~FileAccPropList() override; #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/libs/windows/include/H5FcreatProp.h b/libs/windows/include/H5FcreatProp.h index 00ae0b1..399db71 100644 --- a/libs/windows/include/H5FcreatProp.h +++ b/libs/windows/include/H5FcreatProp.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -78,7 +77,7 @@ class H5_DLLCPP FileCreatPropList : public PropList { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("FileCreatPropList"); } @@ -91,7 +90,7 @@ class H5_DLLCPP FileCreatPropList : public PropList { FileCreatPropList(const hid_t plist_id); // Noop destructor - virtual ~FileCreatPropList(); + virtual ~FileCreatPropList() override; #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/libs/windows/include/H5File.h b/libs/windows/include/H5File.h index 6126eec..617adaa 100644 --- a/libs/windows/include/H5File.h +++ b/libs/windows/include/H5File.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -27,10 +26,12 @@ class H5_DLLCPP H5File : public Group { // Creates or opens an HDF5 file. H5File(const char *name, unsigned int flags, const FileCreatPropList &create_plist = FileCreatPropList::DEFAULT, - const FileAccPropList & access_plist = FileAccPropList::DEFAULT); + const FileAccPropList &access_plist = FileAccPropList::DEFAULT); H5File(const H5std_string &name, unsigned int flags, const FileCreatPropList &create_plist = FileCreatPropList::DEFAULT, - const FileAccPropList & access_plist = FileAccPropList::DEFAULT); + const FileAccPropList &access_plist = FileAccPropList::DEFAULT); + H5File(const char *name, unsigned int flags, const FileAccPropList &access_plist); + H5File(const H5std_string &name, unsigned int flags, const FileAccPropList &access_plist); // Open the file void openFile(const H5std_string &name, unsigned int flags, @@ -39,7 +40,7 @@ class H5_DLLCPP H5File : public Group { const FileAccPropList &access_plist = FileAccPropList::DEFAULT); // Close this file. - virtual void close() H5_OVERRIDE; + virtual void close() override; // Gets a copy of the access property list of this file. FileAccPropList getAccessPlist() const; @@ -77,9 +78,9 @@ class H5_DLLCPP H5File : public Group { static bool isHdf5(const H5std_string &name); // Determines if a file, specified by its name, can be accessed as HDF5 - static bool isAccessible(const char * name, + static bool isAccessible(const char *name, const FileAccPropList &access_plist = FileAccPropList::DEFAULT); - static bool isAccessible(const H5std_string & name, + static bool isAccessible(const H5std_string &name, const FileAccPropList &access_plist = FileAccPropList::DEFAULT); // Reopens this file. @@ -96,16 +97,16 @@ class H5_DLLCPP H5File : public Group { ///\brief Returns this class name. virtual H5std_string - fromClass() const H5_OVERRIDE + fromClass() const override { return ("H5File"); } // Throw file exception. - virtual void throwException(const H5std_string &func_name, const H5std_string &msg) const H5_OVERRIDE; + virtual void throwException(const H5std_string &func_name, const H5std_string &msg) const override; // For CommonFG to get the file id. - virtual hid_t getLocId() const H5_OVERRIDE; + virtual hid_t getLocId() const override; // Default constructor H5File(); @@ -114,15 +115,15 @@ class H5_DLLCPP H5File : public Group { H5File(const H5File &original); // Gets the HDF5 file id. - virtual hid_t getId() const H5_OVERRIDE; + virtual hid_t getId() const override; // H5File destructor. - virtual ~H5File(); + virtual ~H5File() override; protected: #ifndef DOXYGEN_SHOULD_SKIP_THIS // Sets the HDF5 file id. - virtual void p_setId(const hid_t new_id) H5_OVERRIDE; + virtual void p_setId(const hid_t new_id) override; #endif // DOXYGEN_SHOULD_SKIP_THIS private: diff --git a/libs/windows/include/H5FloatType.h b/libs/windows/include/H5FloatType.h index c76be95..42437ec 100644 --- a/libs/windows/include/H5FloatType.h +++ b/libs/windows/include/H5FloatType.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -36,7 +35,7 @@ class H5_DLLCPP FloatType : public AtomType { // Returns an FloatType object via DataType* by decoding the // binary object description of this type. - virtual DataType *decode() const; + virtual DataType *decode() const override; // Retrieves the exponent bias of a floating-point type. size_t getEbias() const; @@ -64,7 +63,7 @@ class H5_DLLCPP FloatType : public AtomType { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("FloatType"); } @@ -79,7 +78,7 @@ class H5_DLLCPP FloatType : public AtomType { FloatType(const FloatType &original); // Noop destructor. - virtual ~FloatType(); + virtual ~FloatType() override; }; // end of FloatType } // namespace H5 diff --git a/libs/windows/include/H5Fpublic.h b/libs/windows/include/H5Fpublic.h index 89238b6..cc0bf2f 100644 --- a/libs/windows/include/H5Fpublic.h +++ b/libs/windows/include/H5Fpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -17,10 +16,9 @@ #ifndef H5Fpublic_H #define H5Fpublic_H -/* Public header files needed by this file */ -#include "H5public.h" -#include "H5ACpublic.h" -#include "H5Ipublic.h" +#include "H5public.h" /* Generic Functions */ +#include "H5ACpublic.h" /* Metadata Cache */ +#include "H5Ipublic.h" /* Identifiers */ /* When this header is included from a private header, don't make calls to H5check() */ #undef H5CHECK @@ -84,7 +82,7 @@ (0x0020u) /**< Restrict search to objects opened through current file ID \ (as opposed to objects opened through any file ID accessing this file) */ -#define H5F_FAMILY_DEFAULT (hsize_t)0 +#define H5F_FAMILY_DEFAULT 0 /* (hsize_t) */ #ifdef H5_HAVE_PARALLEL /** @@ -108,7 +106,7 @@ typedef enum H5F_scope_t { /** * Unlimited file size for H5Pset_external() */ -#define H5F_UNLIMITED ((hsize_t)(-1L)) +#define H5F_UNLIMITED HSIZE_UNDEF /** * How does file close behave? @@ -126,17 +124,17 @@ typedef enum H5F_close_degree_t { //! typedef struct H5F_info2_t { struct { - unsigned version; /**< Superblock version # */ + unsigned version; /**< Superblock version number */ hsize_t super_size; /**< Superblock size */ hsize_t super_ext_size; /**< Superblock extension size */ } super; struct { - unsigned version; /**< Version # of file free space management */ + unsigned version; /**< Version number of file free space management */ hsize_t meta_size; /**< Free space manager metadata size */ hsize_t tot_space; /**< Amount of free space in the file */ } free; struct { - unsigned version; /**< Version # of shared object header info */ + unsigned version; /**< Version number of shared object header info */ hsize_t hdr_size; /**< Shared object header message header size */ H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */ } sohm; @@ -189,10 +187,11 @@ typedef enum H5F_libver_t { H5F_LIBVER_V18 = 1, /**< Use the latest v18 format for storing objects */ 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_NBOUNDS + H5F_LIBVER_V114 = 4, /**< Use the latest v114 format for storing objects */ + H5F_LIBVER_NBOUNDS /**< Sentinel */ } H5F_libver_t; -#define H5F_LIBVER_LATEST H5F_LIBVER_V112 +#define H5F_LIBVER_LATEST H5F_LIBVER_V114 /** * File space handling strategy @@ -351,6 +350,17 @@ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Fcreate_async(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t es_id); +#endif /** * \ingroup H5F * @@ -386,7 +396,7 @@ H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_ * opened. * * The \p fapl_id parameter specifies the file access property list. - * Use of #H5P_DEFAULT specifies that default I/O access properties + * The use of #H5P_DEFAULT specifies that default I/O access properties * are to be used. * * The \p flags parameter specifies whether the file will be opened in @@ -444,6 +454,17 @@ H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_ * */ H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Fopen} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Fopen_async(const char *filename, unsigned flags, hid_t access_plist, hid_t es_id); +#endif /** * \ingroup H5F * @@ -470,6 +491,17 @@ H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id); * */ H5_DLL hid_t H5Freopen(hid_t file_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Freopen} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Freopen_async(hid_t file_id, hid_t es_id); +#endif /** * \ingroup H5F * @@ -496,13 +528,24 @@ H5_DLL hid_t H5Freopen(hid_t file_id); * \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 + * flushes the internal HDF5 buffers and then asks the operating system * (the OS) to flush the system buffers for the open files. After * that, the OS is responsible for ensuring that the data is * actually flushed to disk. * */ H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Fflush} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Fflush_async(hid_t object_id, H5F_scope_t scope, hid_t es_id); +#endif /** * \ingroup H5F * @@ -523,7 +566,7 @@ H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope); * \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 + * above-described behavior. If H5Fclose() is called for a file, but one * or more objects within the file remain open, those objects will remain * accessible until they are individually closed. Thus, if the dataset * \c data_sample is open when H5Fclose() is called for the file @@ -532,7 +575,7 @@ H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope); * automatically closed once all objects in the file have been closed.\n * Be warned, however, that there are circumstances where it is not * possible to delay closing a file. For example, an MPI-IO file close is - * a collective call; all of the processes that opened the file must + * a collective call; all of the processes that open the file must * close it collectively. The file cannot be closed at some time in the * future by each process in an independent fashion. Another example is * that an application using an AFS token-based file access privilege may @@ -547,6 +590,17 @@ H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope); * */ H5_DLL herr_t H5Fclose(hid_t file_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Fclose} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Fclose_async(hid_t file_id, hid_t es_id); +#endif /** * \ingroup H5F * @@ -902,7 +956,7 @@ H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment); * \file_id * \param[out] buf_ptr Pointer to the buffer into which the image of the * HDF5 file is to be copied. If \p buf_ptr is NULL, - * no data will be copied but the function’s return value + * no data will be copied but the function's return value * will still indicate the buffer size required (or a * negative value on error). * \param[out] buf_len Size of the supplied buffer @@ -919,7 +973,7 @@ H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment); * file image. So if the file size is unknown, it can be safely * determined with an initial H5Fget_file_image() call with buf_ptr * set to NULL. The file image can then be retrieved with a second - * H5Fget_file_image() call with \p buf_len set to the initial call’s + * H5Fget_file_image() call with \p buf_len set to the initial call's * return value. * * While the current file size can also be retrieved with @@ -990,7 +1044,7 @@ H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); * \since 1.8.0 * */ -H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr); +H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, const H5AC_cache_config_t *config_ptr); /** * \ingroup MDC * @@ -1117,7 +1171,7 @@ H5_DLL ssize_t H5Fget_name(hid_t obj_id, char *name, size_t size); /** * \ingroup H5F * - * \brief Retrieves name of file to which object belongs + * \brief Retrieves global file information * * \fgdta_obj_id * \param[out] file_info Buffer for global file information @@ -1265,7 +1319,7 @@ H5_DLL herr_t H5Fget_metadata_read_retry_info(hid_t file_id, H5F_retry_info_t *i * on a system that is not atomic. * \li Turn off usage of the library's accumulator to avoid possible * ordering problem on a system that is not atomic. - * \li Perform a flush of the file’s data buffers and metadata to set + * \li Perform a flush of the file's data buffers and metadata to set * a consistent state for starting SWMR write operations. * * Library objects are groups, datasets, and committed datatypes. For @@ -1304,7 +1358,7 @@ H5_DLL herr_t H5Fstart_swmr_write(hid_t file_id); * \snippet this H5F_sect_info_t_snip * * This routine retrieves free-space section information for \p nsects - * sections or at most the maximum number of sections in the specified + * sections or, at most, the maximum number of sections in the specified * free-space manager. If the number of sections is not known, a * preliminary H5Fget_free_sections() call can be made by setting \p * sect_info to NULL and the total number of free-space sections for @@ -1335,7 +1389,7 @@ H5_DLL ssize_t H5Fget_free_sections(hid_t file_id, H5F_mem_t type, size_t nsects * \return \herr_t * * \details H5Fclear_elink_file_cache() evicts all the cached child files in - * the specified file’s external file cache, causing them to be closed + * the specified file's external file cache, causing them to be closed * if there is nothing else holding them open. * * H5Fclear_elink_file_cache() does not close the cache itself; @@ -1513,12 +1567,6 @@ H5_DLL herr_t H5Fstop_mdc_logging(hid_t file_id); * \since 1.10.0 */ H5_DLL herr_t H5Fget_mdc_logging_status(hid_t file_id, hbool_t *is_enabled, hbool_t *is_currently_logging); -/** - * \ingroup SWMR - * - * \todo UFO? - */ -H5_DLL herr_t H5Fformat_convert(hid_t fid); /** * \ingroup H5F * @@ -1570,7 +1618,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 \c HADDR_UNDEF if it does not + * \param[out] image_addr Offset of the cache image if it exists, or #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 * @@ -1610,9 +1658,9 @@ H5_DLL herr_t H5Fget_mdc_image_info(hid_t file_id, haddr_t *image_addr, hsize_t * \details H5Fget_dset_no_attrs_hint() retrieves the no dataset attributes * hint setting for the file specified by the file identifier \p * file_id. This setting is used to inform the library to create - * minimized dataset object headers when \c TRUE. + * minimized dataset object headers when \c true. * - * The setting's value is returned in the boolean pointer minimize. + * The setting's value is returned in the boolean pointer minimized. * * \since 1.10.5 * @@ -1631,18 +1679,18 @@ H5_DLL herr_t H5Fget_dset_no_attrs_hint(hid_t file_id, hbool_t *minimize); * * \details H5Fset_dset_no_attrs_hint() sets the no dataset attributes hint * setting for the file specified by the file identifier \p file_id. - * If the boolean flag \p minimize is set to \c TRUE, then the library + * If the boolean flag \p minimize is set to \c true, then the library * will create minimized dataset object headers in the file. * \Bold{All} files that refer to the same file-on-disk will be * affected by the most recent setting, regardless of the file * identifier/handle (e.g., as returned by H5Fopen()). By setting the - * \p minimize flag to \c TRUE, the library expects that no attributes + * \p minimize flag to \c true, the library expects that no attributes * will be added to the dataset - attributes can be added, but they * are appended with a continuation message, which can reduce * performance. * * \attention This setting interacts with H5Pset_dset_no_attrs_hint(): if - * either is set to \c TRUE, then the created dataset's object header + * either is set to \c true, then the created dataset's object header * will be minimized. * * \since 1.10.5 @@ -1681,7 +1729,7 @@ H5_DLL herr_t H5Fset_dset_no_attrs_hint(hid_t file_id, hbool_t minimize); * pass the same values for \p file_id and \p flag. * * This function is available only when the HDF5 library is configured with parallel support - * (\Code{--enable-parallel}). It is useful only when used with the #H5FD_MPIO driver + * (\Code{--enable-parallel | HDF5_ENABLE_PARALLEL}). It is useful only when used with the #H5FD_MPIO driver * (see H5Pset_fapl_mpio()). * \endparblock * @@ -1741,6 +1789,33 @@ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag); H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag); #endif /* H5_HAVE_PARALLEL */ +/// \cond DEV +/* Internal API routines */ +H5_DLL herr_t H5Fformat_convert(hid_t fid); +/// \endcond + +/// \cond DEV +/* API Wrappers for async routines */ +/* (Must be defined _after_ the function prototype) */ +/* (And must only defined when included in application code, not the library) */ +#ifndef H5F_MODULE +#define H5Fcreate_async(...) H5Fcreate_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Fopen_async(...) H5Fopen_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Freopen_async(...) H5Freopen_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Fflush_async(...) H5Fflush_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Fclose_async(...) H5Fclose_async(__FILE__, __func__, __LINE__, __VA_ARGS__) + +/* Define "wrapper" versions of function calls, to allow compile-time values to + * be passed in by language wrapper or library layer on top of HDF5. + */ +#define H5Fcreate_async_wrap H5_NO_EXPAND(H5Fcreate_async) +#define H5Fopen_async_wrap H5_NO_EXPAND(H5Fopen_async) +#define H5Freopen_async_wrap H5_NO_EXPAND(H5Freopen_async) +#define H5Fflush_async_wrap H5_NO_EXPAND(H5Fflush_async) +#define H5Fclose_async_wrap H5_NO_EXPAND(H5Fclose_async) +#endif /* H5F_MODULE */ +/// \endcond + /* Symbols defined for compatibility with previous versions of the HDF5 API. * * Use of these symbols is deprecated. @@ -1769,7 +1844,7 @@ typedef struct H5F_info1_t { /** * \ingroup H5F * - * \brief Retrieves name of file to which object belongs + * \brief Retrieves global file information * * \fgdta_obj_id * \param[out] file_info Buffer for global file information @@ -1811,7 +1886,7 @@ H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *file_info); /** * \ingroup H5F * - * \brief Sets thelatest version of the library to be used for writing objects + * \brief Sets the latest version of the library to be used for writing objects * * \file_id * \param[in] latest_format Latest format flag @@ -1820,6 +1895,7 @@ H5_DLL herr_t H5Fget_info1(hid_t obj_id, H5F_info1_t *file_info); * * \deprecated When? * + * \todo In which version was this function introduced? * \todo In which version was this function deprecated? * */ @@ -1838,6 +1914,7 @@ H5_DLL herr_t H5Fset_latest_format(hid_t file_id, hbool_t latest_format); * \details H5Fis_hdf5() determines whether a file is in the HDF5 format. * * \todo In which version was this function deprecated? + * \todo In which version was this function introduced? * */ H5_DLL htri_t H5Fis_hdf5(const char *file_name); diff --git a/libs/windows/include/H5Gpublic.h b/libs/windows/include/H5Gpublic.h index 7f1faf8..cc04680 100644 --- a/libs/windows/include/H5Gpublic.h +++ b/libs/windows/include/H5Gpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -14,8 +13,6 @@ /*------------------------------------------------------------------------- * * Created: H5Gpublic.h - * Jul 11 1997 - * Robb Matzke * * Purpose: Public declarations for the H5G package * @@ -24,14 +21,10 @@ #ifndef H5Gpublic_H #define H5Gpublic_H -/* System headers needed by this file */ -#include - -/* Public headers needed by this file */ -#include "H5public.h" /* Generic Functions */ -#include "H5Lpublic.h" /* Links */ -#include "H5Opublic.h" /* Object headers */ -#include "H5Tpublic.h" /* Datatypes */ +#include "H5public.h" /* Generic Functions */ +#include "H5Ipublic.h" /* Identifiers */ +#include "H5Lpublic.h" /* Links */ +#include "H5Opublic.h" /* Object Headers */ /*****************/ /* Public Macros */ @@ -120,11 +113,24 @@ extern "C" { * * \since 1.8.0 * - * \see H5Gopen2(), H5Gclose() + * \see H5Gopen2() * */ H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Gcreate} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Gcreate_async(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, + hid_t es_id); +#endif + /** *------------------------------------------------------------------------- * \ingroup H5G @@ -142,7 +148,7 @@ H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcp * provides similar functionality to that provided by * H5Gcreate1(), with the differences described in the list below. * - * The new group’s creation and access properties are specified + * The new group's creation and access properties are specified * in \p gcpl_id and \p gapl_id, respectively. * * H5Gcreate_anon() returns a new group identifier. This identifier @@ -154,12 +160,12 @@ H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcp * * \li H5Gcreate1() does not provide for the use of custom property * lists; H5Gcreate1() always uses default properties. - * \li H5Gcreate_anon() neither provides the new group’s name + * \li H5Gcreate_anon() neither provides the new group's name * nor links it into the HDF5 file structure; those actions * must be performed separately through a call to H5Olink(), * which offers greater control over linking. * \li H5Gcreate_anon() does not directly provide a hint mechanism - * for the group’s heap size. Comparable information can be + * for the group's heap size. Comparable information can be * included in the group creation property list \p gcpl_id through * a H5Pset_local_heap_size_hint() call. * @@ -167,7 +173,7 @@ H5_DLL hid_t H5Gcreate2(hid_t loc_id, const char *name, hid_t lcpl_id, hid_t gcp * H5Gclose() when the group is no longer needed so that resource * leaks will not develop. * - * \see H5Olink(), H5Dcreate(), Using Identifiers + * \see H5Olink(), H5Gcreate() * * \since 1.8.0 * @@ -199,11 +205,23 @@ H5_DLL hid_t H5Gcreate_anon(hid_t loc_id, hid_t gcpl_id, hid_t gapl_id); * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() + * \see H5Gcreate2() * */ H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Gopen} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Gopen_async(hid_t loc_id, const char *name, hid_t gapl_id, hid_t es_id); +#endif + /** *------------------------------------------------------------------------- * \ingroup H5G @@ -218,12 +236,10 @@ H5_DLL hid_t H5Gopen2(hid_t loc_id, const char *name, hid_t gapl_id); * property list associated with the group specified by \p group_id. * * The creation property list identifier should be released with - * H5Gclose() to prevent resource leaks. + * H5Pclose() to prevent resource leaks. * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL hid_t H5Gget_create_plist(hid_t group_id); @@ -250,11 +266,21 @@ H5_DLL hid_t H5Gget_create_plist(hid_t group_id); * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Gget_info} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Gget_info_async(hid_t loc_id, H5G_info_t *ginfo /*out*/, hid_t es_id); +#endif + /** *------------------------------------------------------------------------- * \ingroup H5G @@ -284,16 +310,28 @@ H5_DLL herr_t H5Gget_info(hid_t loc_id, H5G_info_t *ginfo); * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *ginfo, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Gget_info_by_name} + */ +#ifndef H5_DOXYGEN +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*/, + hid_t lapl_id, hid_t es_id); +#else +H5_DLL herr_t H5Gget_info_by_name_async(hid_t loc_id, const char *name, H5G_info_t *ginfo /*out*/, + hid_t lapl_id, hid_t es_id); +#endif + /** *------------------------------------------------------------------------- * \ingroup H5G * - * \brief Retrieves information about a group, according to the group’s + * \brief Retrieves information about a group, according to the group's * position within an index * * \fgdta_loc_id @@ -331,12 +369,26 @@ H5_DLL herr_t H5Gget_info_by_name(hid_t loc_id, const char *name, H5G_info_t *gi * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx_type, H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Gget_info_by_idx} + */ +#ifndef H5_DOXYGEN +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, + H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo /*out*/, + hid_t lapl_id, hid_t es_id); +#else +H5_DLL herr_t H5Gget_info_by_idx_async(hid_t loc_id, const char *group_name, H5_index_t idx_type, + H5_iter_order_t order, hsize_t n, H5G_info_t *ginfo /*out*/, + hid_t lapl_id, hid_t es_id); +#endif + /** *------------------------------------------------------------------------- * \ingroup H5G @@ -348,7 +400,7 @@ H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_ * \return \herr_t * * \details H5Gflush() causes all buffers associated with a group to be - * immediately flushed to disk without removing the data from + * immediately flushed to the disk without removing the data from * the cache. * * \attention @@ -356,12 +408,10 @@ H5_DLL herr_t H5Gget_info_by_idx(hid_t loc_id, const char *group_name, H5_index_ * flushes the internal HDF5 buffers and then asks the operating * system (the OS) to flush the system buffers for the open * files. After that, the OS is responsible for ensuring that - * the data is actually flushed to disk. + * the data is actually flushed to the disk. * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL herr_t H5Gflush(hid_t group_id); @@ -379,14 +429,12 @@ H5_DLL herr_t H5Gflush(hid_t group_id); * cleared and immediately re-loaded with updated contents from disk. * * This function essentially closes the group, evicts all - * metadata associated with it from the cache, and then re-opens + * metadata associated with it from the cache, and then reopens * the group. The reopened group is automatically re-registered * with the same identifier. * * \since 1.8.0 * - * \see H5Gcreate2(), H5Gclose() - * */ H5_DLL herr_t H5Grefresh(hid_t group_id); @@ -400,7 +448,7 @@ H5_DLL herr_t H5Grefresh(hid_t group_id); * * \return \herr_t * - * \details H5Gclose() releases resources used by a group which was + * \details H5Gclose() releases resources used by a group that was * opened by H5Gcreate() or H5Gopen(). After closing a group, * \p group_id cannot be used again until another H5Gcreate() * or H5Gopen() is called on it. @@ -416,6 +464,42 @@ H5_DLL herr_t H5Grefresh(hid_t group_id); */ H5_DLL herr_t H5Gclose(hid_t group_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Gclose} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Gclose_async(hid_t group_id, hid_t es_id); +#endif + +/// \cond DEV +/* API Wrappers for async routines */ +/* (Must be defined _after_ the function prototype) */ +/* (And must only defined when included in application code, not the library) */ +#ifndef H5G_MODULE +#define H5Gcreate_async(...) H5Gcreate_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Gopen_async(...) H5Gopen_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Gget_info_async(...) H5Gget_info_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Gget_info_by_name_async(...) H5Gget_info_by_name_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Gget_info_by_idx_async(...) H5Gget_info_by_idx_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Gclose_async(...) H5Gclose_async(__FILE__, __func__, __LINE__, __VA_ARGS__) + +/* Define "wrapper" versions of function calls, to allow compile-time values to + * be passed in by language wrapper or library layer on top of HDF5. + */ +#define H5Gcreate_async_wrap H5_NO_EXPAND(H5Gcreate_async) +#define H5Gopen_async_wrap H5_NO_EXPAND(H5Gopen_async) +#define H5Gget_info_async_wrap H5_NO_EXPAND(H5Gget_info_async) +#define H5Gget_info_by_name_async_wrap H5_NO_EXPAND(H5Gget_info_by_name_async) +#define H5Gget_info_by_idx_async_wrap H5_NO_EXPAND(H5Gget_info_by_idx_async) +#define H5Gclose_async_wrap H5_NO_EXPAND(H5Gclose_async) +#endif /* H5G_MODULE */ +/// \endcond + /* Symbols defined for compatibility with previous versions of the HDF5 API. * * Use of these symbols is deprecated. @@ -660,7 +744,7 @@ H5_DLL herr_t H5Glink2(hid_t cur_loc_id, const char *cur_name, H5G_link_t type, * * \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. + * \ref UG. * * \version 1.8.0 Function deprecated in this release. * @@ -691,7 +775,7 @@ H5_DLL herr_t H5Gmove(hid_t src_loc_id, const char *src_name, const char *dst_na * * \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. + * \ref UG. * * \version 1.8.0 Function deprecated in this release. * @@ -725,14 +809,14 @@ H5_DLL herr_t H5Gmove2(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, * 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 + * Note that space identified as freespace is available for reuse 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. + * the \ref UG 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. + * \ref UG. * * \version 1.8.0 Function deprecated in this release. * @@ -800,7 +884,7 @@ H5_DLL herr_t H5Gget_linkval(hid_t loc_id, const char *name, size_t size, char * * \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 + * \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 * @@ -836,14 +920,14 @@ H5_DLL herr_t H5Gset_comment(hid_t loc_id, const char *name, const char *comment * \deprecated This function is deprecated in favor of the function * H5Oget_comment(). * - * \details H5Gget_comment() retrieves the comment for the the object specified + * \details H5Gget_comment() retrieves the comment for 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 + * \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 * @@ -897,7 +981,7 @@ H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char * * 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. + * passed into H5Giterate(), \p op_data. * * The return values from an operator are: * \li Zero causes the iterator to continue, returning zero when all @@ -918,7 +1002,10 @@ H5_DLL int H5Gget_comment(hid_t loc_id, const char *name, size_t bufsize, char * * examine the members of \c subgroup_a. When recursive iteration is * required, the application must handle the recursion, explicitly * calling H5Giterate() on discovered subgroups. - + * + * \warning Adding or removing members to the group during iteration + * will lead to undefined behavior. + * * \version 1.8.0 Function deprecated in this release. * */ @@ -1006,7 +1093,7 @@ H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link *------------------------------------------------------------------------- * \ingroup H5G * - * \brief Returns a name of an object specified by an index + * \brief Returns the name of an object specified by an index * * \fg_loc_id * \param[in] idx Transient index identifying object @@ -1019,7 +1106,7 @@ H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link * * \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 + * \details H5Gget_objname_by_idx() returns the 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 @@ -1038,7 +1125,7 @@ H5_DLL herr_t H5Gget_objinfo(hid_t loc_id, const char *name, hbool_t follow_link * 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 + * Note that if the size of the object's name is unknown, 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 diff --git a/libs/windows/include/H5Group.h b/libs/windows/include/H5Group.h index b5f7e51..cb9b092 100644 --- a/libs/windows/include/H5Group.h +++ b/libs/windows/include/H5Group.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -24,20 +23,20 @@ namespace H5 { class H5_DLLCPP Group : public H5Object, public CommonFG { public: // Close this group. - virtual void close() H5_OVERRIDE; + virtual void close() override; ///\brief Returns this class name. virtual H5std_string - fromClass() const H5_OVERRIDE + fromClass() const override { return ("Group"); } // Throw group exception. - virtual void throwException(const H5std_string &func_name, const H5std_string &msg) const H5_OVERRIDE; + virtual void throwException(const H5std_string &func_name, const H5std_string &msg) const override; // for CommonFG to get the file id. - virtual hid_t getLocId() const H5_OVERRIDE; + virtual hid_t getLocId() const override; // Creates a group by way of dereference. Group(const H5Location &loc, const void *ref, H5R_type_t ref_type = H5R_OBJECT, @@ -63,10 +62,10 @@ class H5_DLLCPP Group : public H5Object, public CommonFG { Group(const Group &original); // Gets the group id. - virtual hid_t getId() const H5_OVERRIDE; + virtual hid_t getId() const override; // Destructor - virtual ~Group() H5_OVERRIDE; + virtual ~Group() override; // Creates a copy of an existing group using its id. Group(const hid_t group_id); @@ -74,7 +73,7 @@ class H5_DLLCPP Group : public H5Object, public CommonFG { protected: #ifndef DOXYGEN_SHOULD_SKIP_THIS // Sets the group id. - virtual void p_setId(const hid_t new_id) H5_OVERRIDE; + virtual void p_setId(const hid_t new_id) override; #endif // DOXYGEN_SHOULD_SKIP_THIS private: diff --git a/libs/windows/include/H5IMpublic.h b/libs/windows/include/H5IMpublic.h index 2843942..0ba9d64 100644 --- a/libs/windows/include/H5IMpublic.h +++ b/libs/windows/include/H5IMpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -18,33 +17,329 @@ extern "C" { #endif +/** \page H5IM_UG The HDF5 High Level Images + * @todo Under Construction + */ + +/**\defgroup H5IM HDF5 Images API (H5IM) + * + * Creating and manipulating HDF5 datasets intended to be + * interpreted as images (H5IM) + * + * The specification for the Images API is presented in another + * document: \ref IMG + * This version of the API is primarily concerned with two dimensional raster + * data similar to HDF4 Raster Images. + * The HDF5 Images API uses the \ref H5LT. + * + * \note \Bold{Programming hints:} + * \note To use any of these functions or subroutines, + * you must first include the relevant include file (C) or + * module (Fortran) in your application. + * \note The following line includes the HDF5 Images package, H5IM, + * in C applications: + * \code #include "hdf5_hl.h" \endcode + * \note This line includes the H5IM module in Fortran applications: + * \code use h5im \endcode + * + * - \ref H5IMget_image_info + * \n Gets information about an image dataset (dimensions, + * interlace mode and number of associated palettes). + * - \ref H5IMget_npalettes + * \n Gets the number of palettes associated to an image. + * - \ref H5IMget_palette + * \n Gets the palette dataset. + * - \ref H5IMget_palette_info + * \n Gets information about a palette dataset (dimensions). + * - \ref H5IMis_image + * \n Inquires if a dataset is an image + * - \ref H5IMis_palette + * \n Inquires if a dataset is a palette. + * - \ref H5IMlink_palette + * \n Attaches a palette to an image. + * - \ref H5IMmake_image_8bit + * \n Creates and writes an image. + * - \ref H5IMmake_image_24bit + * \n Creates and writes a true color image. + * - \ref H5IMmake_palette + * \n Creates and writes a palette. + * - \ref H5IMread_image + * \n Reads image data from disk. + * - \ref H5IMunlink_palette + * \n Detaches a palette from an image. + * + */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Creates and writes an image. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[in] width The width of the image + * \param[in] height The height of the image + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5IMmake_image_8bit() creates and writes a dataset named + * \p dset_name attached to the file or group specified by the + * identifier \p loc_id. Attributes conforming to the HDF5 Image + * and Palette specification for an indexed image are attached to + * the dataset, thus identifying it as an image. The image data is + * of the type #H5T_NATIVE_UCHAR. An indexed image is an image in + * which each each pixel information storage is an index to a + * table palette. + * + */ H5_HLDLL herr_t H5IMmake_image_8bit(hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height, const unsigned char *buffer); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Creates and writes a true color image. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[in] width The width of the image + * \param[in] height The height of the image + * \param[in] interlace String defining the interlace mode + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5IMmake_image_24bit() creates and writes a dataset named + * \p dset_name attached to the file or group specified by the + * identifier \p loc_id. This function defines a true color image + * conforming to the HDF5 Image and Palette specification. + * The function assumes that the image data is of the type + * #H5T_NATIVE_UCHAR. + * + * A true color image is an image where the pixel storage contains + * several color planes. In a 24 bit RGB color model, these planes + * are red, green and blue. In a true color image the stream of bytes + * can be stored in several different ways, thus defining the + * interlace (or interleaving) mode. The 2 most used types of interlace mode + * are interlace by pixel and interlace by plane. In the 24 bit RGB color + * model example, interlace by plane means all the red components for the + * entire dataset are stored first, followed by all the green components, + * and then by all the blue components. Interlace by pixel in this example + * means that for each pixel the sequence red, green, blue is defined. + * In this function, the interlace mode is defined in the parameter + * \p interlace, a string that can have the values INTERLACE_PIXEL + * or INTERLACE_PLANE. + * + */ H5_HLDLL herr_t H5IMmake_image_24bit(hid_t loc_id, const char *dset_name, hsize_t width, hsize_t height, const char *interlace, const unsigned char *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Gets information about an image dataset + * (dimensions, interlace mode and number of associated palettes). + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset + * \param[out] width The width of the image + * \param[out] height The height of the image + * \param[out] planes The number of color planes of the image + * \param[out] interlace The interlace mode of the image + * \param[out] npals The number of palettes associated to the image + * + * \return \herr_t + * + * \details H5IMget_image_info() gets information about an image + * named \p dset_name attached to the file or group specified + * by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5IMget_image_info(hid_t loc_id, const char *dset_name, hsize_t *width, hsize_t *height, hsize_t *planes, char *interlace, hssize_t *npals); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Reads image data from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[out] buffer Buffer with data to store the image + * + * \return \herr_t + * + * \details H5IMread_image() reads a dataset named \p dset_name + * attached to the file or group specified by the + * identifier \p loc_id. + * + */ H5_HLDLL herr_t H5IMread_image(hid_t loc_id, const char *dset_name, unsigned char *buffer); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Creates and writes a palette. + * + * \fg_loc_id + * \param[in] pal_name The name of the palette + * \param[in] pal_dims An array of the size of the palette dimensions + * \param[in] pal_data Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5IMmake_palette() creates and writes a dataset + * named \p pal_name. Attributes conforming to the HDF5 Image and + * Palette specification are attached to the dataset, thus + * identifying it as a palette. The palette data is of the + * type #H5T_NATIVE_UCHAR. + * + */ H5_HLDLL herr_t H5IMmake_palette(hid_t loc_id, const char *pal_name, const hsize_t *pal_dims, const unsigned char *pal_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Attaches a palette to an image. + * + * \fg_loc_id + * \param[in] image_name The name of the dataset to attach the palette to + * \param[in] pal_name The name of the palette + * + * \return \herr_t + * + * \details H5IMlink_palette() attaches a palette named \p pal_name + * to an image specified by \p image_name. The image dataset + * may or not already have an attached palette. If it has, + * the array of palette references is extended to hold the reference + * to the new palette. + * + */ H5_HLDLL herr_t H5IMlink_palette(hid_t loc_id, const char *image_name, const char *pal_name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Detaches a palette from an image. + * + * \fg_loc_id + * \param[in] image_name The name of the image dataset + * \param[in] pal_name The name of the palette + * + * \return \herr_t + * + * \details H5IMunlink_palette() detaches a palette from an image + * specified by \p image_name. + * + */ H5_HLDLL herr_t H5IMunlink_palette(hid_t loc_id, const char *image_name, const char *pal_name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Gets the number of palettes associated to an image. + * + * \fg_loc_id + * \param[in] image_name The name of the image dataset + * \param[out] npals The number of palettes + * + * \return \herr_t + * + * \details H5IMget_npalettes() gets the number of palettes associated to + * an image specified by \p image_name. + * + */ H5_HLDLL herr_t H5IMget_npalettes(hid_t loc_id, const char *image_name, hssize_t *npals); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Gets information about a palette dataset (dimensions). + * + * \fg_loc_id + * \param[in] image_name The name of the image dataset + * \param[in] pal_number The zero based index that identifies + * the palette + * \param[out] pal_dims The dimensions of the palette dataset + * + * \return \herr_t + * + * \details H5IMget_palette_info() gets the dimensions of the palette + * dataset identified by \p pal_number (a zero based index) + * associated to an image specified by \p image_name. + * + */ H5_HLDLL herr_t H5IMget_palette_info(hid_t loc_id, const char *image_name, int pal_number, hsize_t *pal_dims); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Gets the palette dataset. + * + * \fg_loc_id + * \param[in] image_name The name of the image dataset + * \param[in] pal_number The zero based index that identifies + * the palette + * \param[out] pal_data The palette dataset + * + * \return \herr_t + * + * \details H5IMget_palette() gets the palette dataset identified + * by \p pal_number (a zero based index) associated to an + * image specified by \p image_name. + * + */ H5_HLDLL herr_t H5IMget_palette(hid_t loc_id, const char *image_name, int pal_number, unsigned char *pal_data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Inquires if a dataset is an image. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset + * + * \return \htri_t + * + * \details H5IMis_image() inquires if a dataset named \p dset_name, + * attached to the file or group specified by the identifier + * \p loc_id, is an image based on the HDF5 Image and Palette + * Specification. + * + */ H5_HLDLL herr_t H5IMis_image(hid_t loc_id, const char *dset_name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5IM + * + * \brief Inquires if a dataset is a palette + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset + * + * \return \htri_t + * + * \details H5IMis_palette() inquires if a dataset named \p dset_name, + * attached to the file or group specified by the + * identifier \p loc_id, is a palette based on the HDF5 + * Image and Palette Specification. + * + */ H5_HLDLL herr_t H5IMis_palette(hid_t loc_id, const char *dset_name); #ifdef __cplusplus diff --git a/libs/windows/include/H5IdComponent.h b/libs/windows/include/H5IdComponent.h index 383d42d..d64bdb5 100644 --- a/libs/windows/include/H5IdComponent.h +++ b/libs/windows/include/H5IdComponent.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * diff --git a/libs/windows/include/H5Idevelop.h b/libs/windows/include/H5Idevelop.h new file mode 100644 index 0000000..d0ff200 --- /dev/null +++ b/libs/windows/include/H5Idevelop.h @@ -0,0 +1,139 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * This file contains public declarations for the H5I (ID management) developer + * support routines. + */ + +#ifndef H5Idevelop_H +#define H5Idevelop_H + +/* Include package's public header */ +#include "H5Ipublic.h" /* ID management */ + +/*****************/ +/* Public Macros */ +/*****************/ + +/*******************/ +/* Public Typedefs */ +/*******************/ + +/** + * The type of the realize_cb callback for H5Iregister_future + */ +//! +typedef herr_t (*H5I_future_realize_func_t)(void *future_object, hid_t *actual_object_id); +//! + +/** + * The type of the discard_cb callback for H5Iregister_future + */ +//! +typedef herr_t (*H5I_future_discard_func_t)(void *future_object); +//! + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \ingroup H5I + * + * \brief Registers a "future" object under a type and returns an ID for it + * + * \param[in] type The identifier of the type of the new ID + * \param[in] object Pointer to "future" object for which a new ID is created + * \param[in] realize_cb Function pointer to realize a future object + * \param[in] discard_cb Function pointer to destroy a future object + * + * \return \hid_t{object} + * + * \details H5Iregister_future() creates and returns a new ID for a "future" object. + * Future objects are a special kind of object and represent a + * placeholder for an object that has not yet been created or opened. + * The \p realize_cb will be invoked by the HDF5 library to 'realize' + * the future object as an actual object. A call to H5Iobject_verify() + * will invoke the \p realize_cb callback and if it successfully + * returns, will return the actual object, not the future object. + * + * \details The \p type parameter is the identifier for the ID type to which + * this new future ID will belong. This identifier may have been created + * by a call to H5Iregister_type() or may be one of the HDF5 pre-defined + * ID classes (e.g. H5I_FILE, H5I_GROUP, H5I_DATASPACE, etc). + * + * \details The \p object parameter is a pointer to the memory which the new ID + * will be a reference to. This pointer will be stored by the library, + * but will not be returned to a call to H5Iobject_verify() until the + * \p realize_cb callback has returned the actual pointer for the object. + * + * A NULL value for \p object is allowed. + * + * \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 \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 + * from an HDF5 pre-defined ID type. For example, the \p realize_cb + * for a future dataspace object will be called during the process + * of returning information from H5Sget_simple_extent_dims(). + * + * Note that although the \p realize_cb routine returns + * an ID (as a parameter) for the actual object, the HDF5 library + * will swap the actual object in that ID for the future object in + * the future ID. This ensures that the ID value for the object + * doesn't change for the user when the object is realized. + * + * Note that the \p realize_cb callback could receive a NULL value + * for a future object pointer, if one was used when H5Iregister_future() + * was initially called. This is permitted as a means of allowing + * the \p realize_cb to act as a generator of new objects, without + * requiring creation of unnecessary future objects. + * + * It is an error to pass NULL for \p realize_cb. + * + * \details The \p discard_cb parameter is a function pointer that will be + * invoked by the HDF5 library to destroy a future object. This + * callback will always be invoked for _every_ future object, whether + * the \p realize_cb is invoked on it or not. It's possible that + * the \p discard_cb is invoked on a future object without the + * \p realize_cb being invoked, e.g. when a future ID is closed without + * requiring the future object to be realized into an actual one. + * + * Note that the \p discard_cb callback could receive a NULL value + * for a future object pointer, if one was used when H5Iregister_future() + * was initially called. + * + * It is an error to pass NULL for \p discard_cb. + * + * \note The H5Iregister_future() function is primarily targeted at VOL connector + * authors and is _not_ designed for general-purpose application use. + * + */ +H5_DLL hid_t H5Iregister_future(H5I_type_t type, const void *object, H5I_future_realize_func_t realize_cb, + H5I_future_discard_func_t discard_cb); + +#ifdef __cplusplus +} +#endif + +#endif /* H5Idevelop_H */ diff --git a/libs/windows/include/H5Include.h b/libs/windows/include/H5Include.h index 0dc930d..a55cbe4 100644 --- a/libs/windows/include/H5Include.h +++ b/libs/windows/include/H5Include.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -24,10 +23,3 @@ * magic number as prefix and checksum as suffix for all chunks. */ #define H5O_VERSION_2 2 - -// Define H5_OVERRIDE to override for C++11. -#if defined(__cplusplus) && (201103L <= __cplusplus) -#define H5_OVERRIDE override -#else -#define H5_OVERRIDE -#endif diff --git a/libs/windows/include/H5IntType.h b/libs/windows/include/H5IntType.h index 185c8f0..170ed37 100644 --- a/libs/windows/include/H5IntType.h +++ b/libs/windows/include/H5IntType.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -36,17 +35,17 @@ class H5_DLLCPP IntType : public AtomType { // Returns an IntType object via DataType* by decoding the // binary object description of this type. - virtual DataType *decode() const; + virtual DataType *decode() const override; // Retrieves the sign type for an integer type H5T_sign_t getSign() const; - // Sets the sign proprety for an integer type. + // Sets the sign property for an integer type. void setSign(H5T_sign_t sign) const; ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("IntType"); } @@ -61,7 +60,7 @@ class H5_DLLCPP IntType : public AtomType { IntType(const IntType &original); // Noop destructor. - virtual ~IntType(); + virtual ~IntType() override; }; // end of IntType } // namespace H5 diff --git a/libs/windows/include/H5Ipublic.h b/libs/windows/include/H5Ipublic.h index 6442a0d..ce78ae3 100644 --- a/libs/windows/include/H5Ipublic.h +++ b/libs/windows/include/H5Ipublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -18,8 +17,7 @@ #ifndef H5Ipublic_H #define H5Ipublic_H -/* Public headers needed by this file */ -#include "H5public.h" +#include "H5public.h" /* Generic Functions */ /** * Library type values. @@ -51,6 +49,7 @@ typedef enum H5I_type_t { H5I_ERROR_MSG, /**< type ID for error messages */ H5I_ERROR_STACK, /**< type ID for error stacks */ H5I_SPACE_SEL_ITER, /**< type ID for dataspace selection iterator */ + H5I_EVENTSET, /**< type ID for event sets */ H5I_NTYPES /**< number of library types, MUST BE LAST! */ } H5I_type_t; //! @@ -76,13 +75,15 @@ typedef int64_t hid_t; #define H5I_INVALID_HID (-1) /** - * A function for freeing objects. This function will be called with an object - * ID type number and a pointer to the object. The function should free the - * object and return non-negative to indicate that the object - * can be removed from the ID type. If the function returns negative - * (failure) then the object will remain in the ID type. + * A function for freeing objects. This function will be called with a pointer + * to the object and a pointer to a pointer to the asynchronous request object. + * The function should free the object and return non-negative to indicate that + * the object can be removed from the ID type. If the function returns negative + * (failure) then the object will remain in the ID type. For asynchronous + * operations and handling the request parameter, see the HDF5 user guide and + * VOL connector author guide. */ -typedef herr_t (*H5I_free_t)(void *); +typedef herr_t (*H5I_free_t)(void *obj, void **request); /** * The type of a function to compare objects & keys @@ -105,7 +106,7 @@ extern "C" { /* Public API functions */ /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Registers an object under a type and returns an ID for it * @@ -127,7 +128,7 @@ extern "C" { */ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Returns the object referenced by an ID * @@ -143,14 +144,14 @@ H5_DLL hid_t H5Iregister(H5I_type_t type, const void *object); * * \note H5Iobject_verify() does not change the ID it is called on in any way * (as opposed to H5Iremove_verify(), which removes the ID from its - * type’s hash table). + * type's hash table). * * \see H5Iregister() * */ H5_DLL void *H5Iobject_verify(hid_t id, H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Removes an ID from its type * @@ -189,12 +190,7 @@ H5_DLL void *H5Iremove_verify(hid_t id, H5I_type_t type); * \return Returns the object type if successful; otherwise #H5I_BADID. * * \details H5Iget_type() retrieves the type of the object identified by - * \p id. - * - * Valid types returned by the function are: - * \id_types - * - * If no valid type can be determined or the identifier submitted is + * \p id. If no valid type can be determined or the identifier submitted is * invalid, the function returns #H5I_BADID. * * This function is of particular use in determining the type of @@ -238,7 +234,7 @@ H5_DLL hid_t H5Iget_file_id(hid_t id); * \brief Retrieves a name of an object based on the object identifier * * \obj_id{id} - * \param[out] name A buffer for thename associated with the identifier + * \param[out] name A buffer for the name associated with the identifier * \param[in] size The size of the \p name buffer; usually the size of * the name in bytes plus 1 for a NULL terminator * @@ -339,27 +335,27 @@ H5_DLL int H5Iinc_ref(hid_t id); * * The reference count for a newly created object will be 1. Reference * counts for objects may be explicitly modified with this function or - * with H5Iinc_ref(). When an object identifier’s reference count + * with H5Iinc_ref(). When an object identifier's reference count * reaches zero, the object will be closed. Calling an object - * identifier’s \c close function decrements the reference count for - * the identifier which normally closes the object, but if the + * identifier's \c close function decrements the reference count for + * the identifier, which normally closes the object, but if the * reference count for the identifier has been incremented with * H5Iinc_ref(), the object will only be closed when the reference * count reaches zero with further calls to this function or the - * object identifier’s \c close function. + * object identifier's \c close function. * * If the object ID was created by a collective parallel call (such as * H5Dcreate(), H5Gopen(), etc.), the reference count should be * modified by all the processes which have copies of the ID. - * Generally this means that group, dataset, attribute, file and named + * Generally, this means that group, dataset, attribute, file and named * datatype IDs should be modified by all the processes and that all * other types of IDs are safe to modify by individual processes. * - * This function is of particular value when an application is - * maintaining multiple copies of an object ID. The object ID can be + * This function is of particular value when an application + * maintains multiple copies of an object ID. The object ID can be * incremented when a copy is made. Each copy of the ID can then be * safely closed or decremented and the HDF5 object will be closed - * when the reference count for that that object drops to zero. + * when the reference count for that object drops to zero. * * \since 1.6.2 * @@ -390,7 +386,7 @@ H5_DLL int H5Idec_ref(hid_t id); */ H5_DLL int H5Iget_ref(hid_t id); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Creates and returns a new ID type * @@ -422,7 +418,7 @@ H5_DLL int H5Iget_ref(hid_t id); */ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free_t free_func); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Deletes all identifiers of the given type * @@ -446,7 +442,7 @@ H5_DLL H5I_type_t H5Iregister_type(size_t hash_size, unsigned reserved, H5I_free */ H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Removes an identifier type and all identifiers within that type * @@ -458,9 +454,9 @@ H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); * identifiers of this type are destroyed and no new identifiers of * this type can be registered. * - * The type’s free function is called on all of the identifiers which + * The type's free function is called on all of the identifiers which * are deleted by this function, freeing their memory. In addition, - * all memory used by this type’s hash table is freed. + * all memory used by this type's hash table is freed. * * Since the H5I_type_t values of destroyed identifier types are * reused when new types are registered, it is a good idea to set the @@ -469,7 +465,7 @@ H5_DLL herr_t H5Iclear_type(H5I_type_t type, hbool_t force); */ H5_DLL herr_t H5Idestroy_type(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Increments the reference count on an ID type * @@ -488,7 +484,7 @@ H5_DLL herr_t H5Idestroy_type(H5I_type_t type); */ H5_DLL int H5Iinc_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Decrements the reference count on an identifier type * @@ -508,11 +504,11 @@ H5_DLL int H5Iinc_type_ref(H5I_type_t type); */ H5_DLL int H5Idec_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Retrieves the reference count on an ID type * - * \param[in] type The identifier of the type whose reference count is to be retieved + * \param[in] type The identifier of the type whose reference count is to be retrieved * * \return Returns the current reference count on success, negative on failure. * @@ -527,7 +523,7 @@ H5_DLL int H5Idec_type_ref(H5I_type_t type); */ H5_DLL int H5Iget_type_ref(H5I_type_t type); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Finds the memory referred to by an ID within the given ID type such * that some criterion is satisfied @@ -568,7 +564,7 @@ H5_DLL int H5Iget_type_ref(H5I_type_t type); */ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Calls a callback for each member of the identifier type specified * @@ -592,12 +588,15 @@ H5_DLL void *H5Isearch(H5I_type_t type, H5I_search_func_t func, void *key); * to continue, as long as there are other identifiers remaining in * type. * + * \warning Adding or removing members of the identifier type during iteration + * will lead to undefined behavior. + * * \since 1.12.0 * */ H5_DLL herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Returns the number of identifiers in a given identifier type * @@ -617,7 +616,7 @@ H5_DLL herr_t H5Iiterate(H5I_type_t type, H5I_iterate_func_t op, void *op_data); */ H5_DLL herr_t H5Inmembers(H5I_type_t type, hsize_t *num_members); /** - * \ingroup H5I + * \ingroup H5IUD * * \brief Determines whether an identifier type is registered * @@ -646,7 +645,7 @@ H5_DLL htri_t H5Itype_exists(H5I_type_t type); * \details Valid identifiers are those that have been obtained by an * application and can still be used to access the original target. * Examples of invalid identifiers include: - * \li Out of range values: negative, for example + * \li Out-of-range values: negative, for example * \li Previously-valid identifiers that have been released: * for example, a dataset identifier for which the dataset has * been closed @@ -654,7 +653,7 @@ H5_DLL htri_t H5Itype_exists(H5I_type_t type); * H5Iis_valid() can be used with any type of identifier: object * identifier, property list identifier, attribute identifier, error * message identifier, etc. When necessary, a call to H5Iget_type() - * can determine the type of the object that \p id identifies. + * can determine the type of object that the \p id identifies. * * \since 1.8.3 * diff --git a/libs/windows/include/H5LDpublic.h b/libs/windows/include/H5LDpublic.h index 011b208..1eee8b4 100644 --- a/libs/windows/include/H5LDpublic.h +++ b/libs/windows/include/H5LDpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -18,8 +17,146 @@ extern "C" { #endif +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Retrieves the current dimension sizes of a dataset. + * + * \param[in] did The dataset identifier + * \param[out] cur_dims The current dimension sizes of the dataset + * + * \return \herr_t + * + * \details H5LDget_dset_dims() retrieves the current dimension sizes + * for the dataset \p did through the parameter \p cur_dims. + * It will return failure if \p cur_dims is NULL. + * + * \note See Also: + * \note Dataset Watch functions (used with h5watch): + * - H5LDget_dset_dims() + * - H5LDget_dset_elmts() + * - H5LDget_dset_type_size() + * + * \par Example: + * See the example code in H5LDget_dset_elmts() for usage of this routine. + * + * \since 1.10.0 + * + */ H5_HLDLL herr_t H5LDget_dset_dims(hid_t did, hsize_t *cur_dims); + +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Returns the size in bytes of the dataset's datatype + * + * \param[in] did The dataset identifier + * \param[in] fields The pointer to a comma-separated list of fields for a compound datatype + * + * \return If successful, returns the size in bytes of the + * dataset's datatype. Otherwise, returns 0. + * + * \details H5LDget_dset_type_size() allows the user to find out the datatype + * size for the dataset associated with \p did. If the + * parameter \p fields is NULL, this routine just returns the size + * of the dataset's datatype. If the dataset has a compound datatype + * and \p fields is non-NULL, this routine returns the size of the + * datatype(s) for the selected fields specified in \p fields. + * Note that ’,’ is the separator for the fields of a compound + * datatype while ’.’ (dot) is the separator for a nested field. + * Use a backslash ( \ ) to escape characters in field names that + * conflict with these two separators. + * + * \note See Also: + * \note Dataset Watch functions (used with h5watch): + * - H5LDget_dset_dims() + * - H5LDget_dset_elmts() + * - H5LDget_dset_type_size() + * + * \par Example: + * See the example code in H5LDget_dset_elmts() for usage of this routine. + * + * \since 1.10.0 + * + */ H5_HLDLL size_t H5LDget_dset_type_size(hid_t did, const char *fields); + +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Retrieves selected data from the dataset + * + * \param[in] did The dataset identifier + * \param[in] prev_dims The previous dimension size of the dataset + * \param[in] cur_dims The current dimension sizes of the dataset + * \param[in] fields A string containing a comma-separated list + * of fields for a compound datatype + * \param[out] buf Buffer for storing data retrieved from the + * dataset + * + * \return \herr_t + * + * \details H5LDget_dset_dims() retrieves selected data of the dataset + * \p did and stores the data in the parameter \p buf. + * The difference between the parameters \p prev_dims and + * \p cur_dims indicates the dimension sizes of the data to be + * selected from the dataset. Note that \p cur_dims must have + * at least one dimension whose size is greater than the + * corresponding dimension in \p prev_dims. Users can + * determine the size of buf by multiplying the datatype + * size of the dataset by the number of selected elements. + * + * If the parameter \p fields is NULL, this routine returns + * data for the selected elements of the dataset. If \p fields + * is not NULL and the dataset has a compound datatype, \p fields + * is a string containing a comma-separated list of fields. + * Each name in \p fields specifies a field in the compound + * datatype, and this routine returns data of the selected fields + * for the dataset's selected elements. Note that ’,’ is the + * separator for the fields of a compound datatype while + * ’.’ is the separator for a nested field. Use backslash to + * escape characters in field names that conflict with these + * two separators. + * + * \note See Also: + * \note Dataset Watch functions (used with h5watch): + * - H5LDget_dset_dims() + * - H5LDget_dset_elmts() + * - H5LDget_dset_type_size() + * + * \par Examples: + * + * For the first example, \c DSET1 is a two-dimensional chunked dataset with atomic type defined below: + * \snippet H5LDget_dset_elmts.c first_declare + * + * The following coding sample illustrates the reading of + * data elements appended to the dataset \c DSET1: + * \snippet H5LDget_dset_elmts.c first_reading + * + * The output buffer will contain data elements selected from + * \c DSET1 as follows: + * \snippet H5LDget_dset_elmts.c first_output + * + * For the second example, DSET2 is a one-dimensional chunked dataset + * with compound type defined below: + * \snippet H5LDget_dset_elmts.c second_declare + * + * The following coding sample illustrates the reading of data elements + * appended to the dataset \c DSET2 with compound datatype. + * This example selects only 2 fields: the fourth field \c d and a + * subfield of the sixth field \c s2.c: + * \snippet H5LDget_dset_elmts.c second_reading + * + * The output buffer will contain data for \c d and \c s2.c + * selected from \c DSET2 as follows: + * \snippet H5LDget_dset_elmts.c second_output + * + * \since 1.10.0 + * + */ H5_HLDLL herr_t H5LDget_dset_elmts(hid_t did, const hsize_t *prev_dims, const hsize_t *cur_dims, const char *fields, void *buf); diff --git a/libs/windows/include/H5LTpublic.h b/libs/windows/include/H5LTpublic.h index 2af9b07..1ce5c81 100644 --- a/libs/windows/include/H5LTpublic.h +++ b/libs/windows/include/H5LTpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -19,7 +18,7 @@ #define H5LT_FILE_IMAGE_DONT_COPY 0x0002 /* The HDF5 lib won't copy */ /* user supplied image buffer. The same image is open with the core driver. */ #define H5LT_FILE_IMAGE_DONT_RELEASE 0x0004 /* The HDF5 lib won't */ -/* deallocate user supplied image buffer. The user application is reponsible */ +/* deallocate user supplied image buffer. The user application is responsible */ /* for doing so. */ #define H5LT_FILE_IMAGE_ALL 0x0007 @@ -35,6 +34,124 @@ typedef enum H5LT_lang_t { extern "C" { #endif +/** \page H5LT_UG The HDF5 High Level Lite + * @todo Under Construction + */ + +/**\defgroup H5LT HDF5 Lite APIs (H5LT,H5LD) + * Functions used to simplify creating and manipulating datasets, + * attributes and other features (H5LT, H5LD) + * + * The HDF5 Lite API consists of higher-level functions which do + * more operations per call than the basic HDF5 interface. + * The purpose is to wrap intuitive functions around certain sets + * of features in the existing APIs. + * It has the following sets of functions listed below. + * + * \note \Bold{Programming hints:} + * \note To use any of these functions or subroutines, + * you must first include the relevant include file (C) or + * module (Fortran) in your application. + * \note The following line includes the HDF5 Lite package, H5LT, + * in C applications: + * \code #include "hdf5_hl.h" \endcode + * \note This line includes the H5LT module in Fortran applications: + * \code use h5lt \endcode + * + * + * + *
+ * + * - Dataset Functions + * - Make dataset functions + * - \ref H5LTmake_dataset + * - \ref H5LTmake_dataset_char + * - \ref H5LTmake_dataset_short + * - \ref H5LTmake_dataset_int + * - \ref H5LTmake_dataset_long + * - \ref H5LTmake_dataset_float + * - \ref H5LTmake_dataset_double + * - \ref H5LTmake_dataset_string + * + * - Read dataset functions + * - \ref H5LTread_dataset + * - \ref H5LTread_dataset_char + * - \ref H5LTread_dataset_short + * - \ref H5LTread_dataset_int + * - \ref H5LTread_dataset_long + * - \ref H5LTread_dataset_float + * - \ref H5LTread_dataset_double + * - \ref H5LTread_dataset_string + * + * - Query dataset functions + * - \ref H5LTfind_dataset + * - \ref H5LTget_dataset_ndims + * - \ref H5LTget_dataset_info + * + * - Dataset watch functions + * - \ref H5LDget_dset_dims + * - \ref H5LDget_dset_elmts + * - \ref H5LDget_dset_type_size + * + * + * + * - Attribute Functions + * - Set attribute functions + * - \ref H5LTset_attribute_string + * - \ref H5LTset_attribute_char + * - \ref H5LTset_attribute_uchar + * - \ref H5LTset_attribute_short + * - \ref H5LTset_attribute_ushort + * - \ref H5LTset_attribute_int + * - \ref H5LTset_attribute_uint + * - \ref H5LTset_attribute_long + * - \ref H5LTset_attribute_long_long + * - \ref H5LTset_attribute_ulong + * - \ref H5LTset_attribute_ullong + * - \ref H5LTset_attribute_float + * - \ref H5LTset_attribute_double + * - H5LTset_attribute_f (fortran ONLY) + * + * - Get attribute functions + * - \ref H5LTget_attribute + * - \ref H5LTget_attribute_string + * - \ref H5LTget_attribute_char + * - \ref H5LTget_attribute_uchar + * - \ref H5LTget_attribute_short + * - \ref H5LTget_attribute_ushort + * - \ref H5LTget_attribute_int + * - \ref H5LTget_attribute_uint + * - \ref H5LTget_attribute_long + * - \ref H5LTget_attribute_long_long + * - \ref H5LTget_attribute_ulong + * - \ref H5LTget_attribute_ullong + * - \ref H5LTget_attribute_float + * - \ref H5LTget_attribute_double + * + * - Query attribute functions + * - \ref H5LTfind_attribute + * - \ref H5LTget_attribute_info + * - \ref H5LTget_attribute_ndims + * + * + * + * - Datatype Functions + * - Datatype translation functions + * - \ref H5LTtext_to_dtype + * - \ref H5LTdtype_to_text + * + * - File image function + * - Open file image function + * - \ref H5LTopen_file_image + * + * - Path and object function + * - Query path and object function + * - \ref H5LTpath_valid + * + *
+ * + */ + /*------------------------------------------------------------------------- * * Make dataset functions @@ -42,27 +159,214 @@ extern "C" { *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset of a type \p type_id. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] type_id Identifier of the datatype to use when creating the dataset + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset() creates and writes a dataset named + * \p dset_name attached to the object specified by the + * identifier \p loc_id. + * + * The parameter \p type_id can be any valid HDF5 Prdefined \ref PDTNAT; + * For example, setting \p type_id to #H5T_NATIVE_INT will result in a dataset + * of signed \e integer datatype. + * + * \version 1.10.0 Fortran 2003 subroutine added to accept a C address of the data buffer. + * \version 1.8.7 Fortran subroutine modified in this release to accommodate arrays + * with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTmake_dataset(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, hid_t type_id, const void *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_char() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset's datatype will be \e character, #H5T_NATIVE_CHAR. + * + */ H5_HLDLL herr_t H5LTmake_dataset_char(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const char *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_short() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset's datatype will be short signed integer, + * #H5T_NATIVE_SHORT. + * + */ H5_HLDLL herr_t H5LTmake_dataset_short(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const short *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_int() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset's datatype will be native signed integer, + * #H5T_NATIVE_INT. + * + * \version Fortran subroutine modified in this release to accommodate + * arrays with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTmake_dataset_int(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const int *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_long() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset's datatype will be long signed integer, + * #H5T_NATIVE_LONG. + * + */ H5_HLDLL herr_t H5LTmake_dataset_long(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const long *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_float() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset's datatype will be native floating point, + * #H5T_NATIVE_FLOAT. + * + * \version 1.8.7 Fortran subroutine modified in this release to accommodate + * arrays with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTmake_dataset_float(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const float *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset. + * + * \fg_loc_id + * \param[in] dset_name The Name of the dataset to create + * \param[in] rank Number of dimensions of dataspace + * \param[in] dims An array of the size of each dimension + * \param[in] buffer Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_double() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset's datatype will be + * native floating-point double, #H5T_NATIVE_DOUBLE. + * + * \version 1.8.7 Fortran subroutine modified in this release to accommodate + * arrays with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTmake_dataset_double(hid_t loc_id, const char *dset_name, int rank, const hsize_t *dims, const double *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a dataset with string datatype. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[in] buf Buffer with data to be written to the dataset + * + * \return \herr_t + * + * \details H5LTmake_dataset_string() creates and writes a dataset + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + * The dataset's datatype will be C string, #H5T_C_S1. + * + */ H5_HLDLL herr_t H5LTmake_dataset_string(hid_t loc_id, const char *dset_name, const char *buf); /*------------------------------------------------------------------------- @@ -72,20 +376,169 @@ H5_HLDLL herr_t H5LTmake_dataset_string(hid_t loc_id, const char *dset_name, con *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[in] type_id Identifier of the datatype to use when reading + * the dataset + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * + * \version 1.10.0 Fortran 2003 subroutine added to accept a C + * address of the data buffer. + * \version 1.8.7 Fortran subroutine modified in this release to + * accommodate arrays with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTread_dataset(hid_t loc_id, const char *dset_name, hid_t type_id, void *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_char() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_CHAR. + * + */ H5_HLDLL herr_t H5LTread_dataset_char(hid_t loc_id, const char *dset_name, char *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_short() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_SHORT. + * + */ H5_HLDLL herr_t H5LTread_dataset_short(hid_t loc_id, const char *dset_name, short *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_int() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_INT. + * + * \version 1.8.7 Fortran subroutine modified in this release to + * accommodate arrays with more than three dimensions. + * + */ H5_HLDLL herr_t H5LTread_dataset_int(hid_t loc_id, const char *dset_name, int *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_long() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_LONG. + * + */ H5_HLDLL herr_t H5LTread_dataset_long(hid_t loc_id, const char *dset_name, long *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_float() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_FLOAT. + * + * \version 1.8.7 Fortran subroutine modified in this release to + * accommodate arrays with more than three dimensions. + */ H5_HLDLL herr_t H5LTread_dataset_float(hid_t loc_id, const char *dset_name, float *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buffer Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_double() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_NATIVE_DOUBLE. + * + * \version 1.8.7 Fortran subroutine modified in this release to + * accommodate arrays with more than three dimensions. + */ H5_HLDLL herr_t H5LTread_dataset_double(hid_t loc_id, const char *dset_name, double *buffer); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a dataset from disk. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] buf Buffer with data + * + * \return \herr_t + * + * \details H5LTread_dataset_string() reads a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * The HDF5 datatype is #H5T_C_S1. + * + */ H5_HLDLL herr_t H5LTread_dataset_string(hid_t loc_id, const char *dset_name, char *buf); /*------------------------------------------------------------------------- @@ -95,11 +548,67 @@ H5_HLDLL herr_t H5LTread_dataset_string(hid_t loc_id, const char *dset_name, cha *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Gets the dimensionality of a dataset + * + * \param[in] loc_id Identifier of the object to + * locate the dataset within + * \param[in] dset_name The dataset name + * \param[out] rank The dimensionality of the dataset + * + * \return \herr_t + * + * \details H5LTget_dataset_ndims() gets the dimensionality of a dataset + * named \p dset_name exists attached to the object \p loc_id. + * + */ H5_HLDLL herr_t H5LTget_dataset_ndims(hid_t loc_id, const char *dset_name, int *rank); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Retrieves information about a dataset + * + * \param[in] loc_id Identifier of the object to locate + * the dataset within + * \param[in] dset_name The dataset name + * \param[out] dims The dimensions of the dataset + * \param[out] type_class The class identifier. #H5T_class_t is defined in + * H5Tpublic.h. See H5Tget_class() for a list + * of class types. + * \param[out] type_size The size of the datatype in bytes + * + * \return \herr_t + * + * \details H5LTget_dataset_info() retrieves information about a dataset + * named \p dset_name attached to the object \p loc_id. + * + */ H5_HLDLL herr_t H5LTget_dataset_info(hid_t loc_id, const char *dset_name, hsize_t *dims, H5T_class_t *type_class, size_t *type_size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Determines whether a dataset exists. + * + * \param[in] loc_id Identifier of the group containing the dataset + * \param[in] name Dataset name + * + * \return \htri_t + * + * \details H5LTfind_dataset() determines whether a dataset named + * \p name exists in the group specified by \p loc_id. + * + * \p loc_id must be a group identifier and \p name must + * specify a dataset that is a member of that group. + * + */ H5_HLDLL herr_t H5LTfind_dataset(hid_t loc_id, const char *name); /*------------------------------------------------------------------------- @@ -109,39 +618,343 @@ H5_HLDLL herr_t H5LTfind_dataset(hid_t loc_id, const char *name); *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes a string attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] attr_data Buffer with data to be written to the attribute + * + * \return \herr_t + * + * \details H5LTset_attribute_string() creates and writes a string attribute + * named \p attr_name and attaches it to the object specified by + * the name \p obj_name. If the attribute already exists, + * it is overwritten. + * + */ H5_HLDLL herr_t H5LTset_attribute_string(hid_t loc_id, const char *obj_name, const char *attr_name, const char *attr_data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_char() creates and writes a numerical attribute + * named \p attr_name and attaches it to the object specified by the + * name \p obj_name. The attribute has a dimensionality of 1. + * The HDF5 datatype of the attribute is #H5T_NATIVE_CHAR. + * + */ H5_HLDLL herr_t H5LTset_attribute_char(hid_t loc_id, const char *obj_name, const char *attr_name, const char *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_uchar() creates and writes a numerical attribute + * named \p attr_name and attaches it to the object specified by the + * name \p obj_name. The attribute has a dimensionality of 1. + * The HDF5 datatype of the attribute is #H5T_NATIVE_UCHAR. + * + */ H5_HLDLL herr_t H5LTset_attribute_uchar(hid_t loc_id, const char *obj_name, const char *attr_name, const unsigned char *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_short() creates and writes a numerical attribute + * named \p attr_name and attaches it to the object specified by the + * name \p obj_name. The attribute has a dimensionality of 1. + * The HDF5 datatype of the attribute is #H5T_NATIVE_SHORT. + * + */ H5_HLDLL herr_t H5LTset_attribute_short(hid_t loc_id, const char *obj_name, const char *attr_name, const short *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_ushort() creates and writes a numerical attribute + * named \p attr_name and attaches it to the object specified by the + * name \p obj_name. The attribute has a dimensionality of 1. + * The HDF5 datatype of the attribute is #H5T_NATIVE_USHORT. + * + */ H5_HLDLL herr_t H5LTset_attribute_ushort(hid_t loc_id, const char *obj_name, const char *attr_name, const unsigned short *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_int() creates and writes a numerical integer + * attribute named \p attr_name and attaches it to the object + * specified by the name \p obj_name. The attribute has a + * dimensionality of 1. The HDF5 datatype of the attribute + * is #H5T_NATIVE_INT. + * + */ H5_HLDLL herr_t H5LTset_attribute_int(hid_t loc_id, const char *obj_name, const char *attr_name, const int *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_uint() creates and writes a numerical integer + * attribute named \p attr_name and attaches it to the object specified + * by the name \p obj_name. The attribute has a dimensionality of 1. + * The HDF5 datatype of the attribute is #H5T_NATIVE_UINT. + * + */ H5_HLDLL herr_t H5LTset_attribute_uint(hid_t loc_id, const char *obj_name, const char *attr_name, const unsigned int *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_long() creates and writes a numerical + * attribute named \p attr_name and attaches it to the object + * specified by the name \p obj_name. The attribute has a + * dimensionality of 1. The HDF5 datatype of the attribute + * is #H5T_NATIVE_LONG. + * + */ H5_HLDLL herr_t H5LTset_attribute_long(hid_t loc_id, const char *obj_name, const char *attr_name, const long *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Location of the object to which the attribute + * is to be attached + * \param[in] obj_name That object's name + * \param[in] attr_name Attribute name + * \param[in] buffer Attribute value + * \param[in] size Attribute size + * + * \return \herr_t + * + * \details H5LTset_attribute_long_long() creates and writes a numerical + * attribute named \p attr_name and attaches it to the object + * specified by the name \p obj_name. + * + * The attribute has a dimensionality of 1 and its HDF5 datatype + * is #H5T_NATIVE_LLONG. + * + */ H5_HLDLL herr_t H5LTset_attribute_long_long(hid_t loc_id, const char *obj_name, const char *attr_name, const long long *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_ulong() creates and writes a numerical + * attribute named \p attr_name and attaches it to the object + * specified by the name \p obj_name. The attribute has a + * dimensionality of 1. The HDF5 datatype of the attribute + * is #H5T_NATIVE_ULONG. + * + */ H5_HLDLL herr_t H5LTset_attribute_ulong(hid_t loc_id, const char *obj_name, const char *attr_name, const unsigned long *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Location of the object to which the attribute + * is to be attached + * \param[in] obj_name That object's name + * \param[in] attr_name Attribute name + * \param[in] buffer Attribute value + * \param[in] size Attribute size + * + * \return \herr_t + * + * \details H5LTset_attribute_ullong() creates and writes a numerical + * attribute named \p attr_name and attaches it to the object + * specified by the name \p obj_name. + * + * The attribute has a dimensionality of 1 and its HDF5 datatype + * is #H5T_NATIVE_ULLONG. + * + */ +H5_HLDLL herr_t H5LTset_attribute_ullong(hid_t loc_id, const char *obj_name, const char *attr_name, + const unsigned long long *buffer, size_t size); + +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_float() creates and writes a numerical + * floating point attribute named \p attr_name and attaches + * it to the object specified by the name \p obj_name. + * The attribute has a dimensionality of 1. The HDF5 datatype + * of the attribute is #H5T_NATIVE_FLOAT. + * + */ H5_HLDLL herr_t H5LTset_attribute_float(hid_t loc_id, const char *obj_name, const char *attr_name, const float *buffer, size_t size); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates and writes an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to create the attribute within + * \param[in] obj_name The name of the object to attach the attribute + * \param[in] attr_name The attribute name + * \param[in] buffer Buffer with data to be written to the attribute + * \param[in] size The size of the 1D array (one in the case of a + * scalar attribute). This value is used by + * H5Screate_simple() to create the dataspace. + * + * \return \herr_t + * + * \details H5LTset_attribute_double() creates and writes a numerical + * attribute named \p attr_name and attaches + * it to the object specified by the name \p obj_name. + * The attribute has a dimensionality of 1. The HDF5 datatype + * of the attribute is #H5T_NATIVE_DOUBLE. + * + */ H5_HLDLL herr_t H5LTset_attribute_double(hid_t loc_id, const char *obj_name, const char *attr_name, const double *buffer, size_t size); @@ -152,39 +965,337 @@ H5_HLDLL herr_t H5LTset_attribute_double(hid_t loc_id, const char *obj_name, con *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[in] mem_type_id Identifier of the memory datatype + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute() reads an attribute named + * \p attr_name with the memory type \p mem_type_id. + * + */ H5_HLDLL herr_t H5LTget_attribute(hid_t loc_id, const char *obj_name, const char *attr_name, hid_t mem_type_id, void *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_string() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The datatype is a string. + * + * \version 1.8.9 The content of the buffer returned by the Fortran + * subroutine has changed in this release:\n + * If the returned buffer requires padding, + * h5ltget_attribute_string_f() now employs space + * padding; this buffer was previously returned with a C NULL terminator. + * + */ H5_HLDLL herr_t H5LTget_attribute_string(hid_t loc_id, const char *obj_name, const char *attr_name, char *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_char() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The datatype of the attribute + * is #H5T_NATIVE_CHAR. + * + */ H5_HLDLL herr_t H5LTget_attribute_char(hid_t loc_id, const char *obj_name, const char *attr_name, char *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_uchar() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_UCHAR + * + */ H5_HLDLL herr_t H5LTget_attribute_uchar(hid_t loc_id, const char *obj_name, const char *attr_name, unsigned char *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_short() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_SHORT + * + */ H5_HLDLL herr_t H5LTget_attribute_short(hid_t loc_id, const char *obj_name, const char *attr_name, short *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_ushort() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_USHORT. + * + */ H5_HLDLL herr_t H5LTget_attribute_ushort(hid_t loc_id, const char *obj_name, const char *attr_name, unsigned short *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_int() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_INT. + * + */ H5_HLDLL herr_t H5LTget_attribute_int(hid_t loc_id, const char *obj_name, const char *attr_name, int *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_uint() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_INT. + * + */ H5_HLDLL herr_t H5LTget_attribute_uint(hid_t loc_id, const char *obj_name, const char *attr_name, unsigned int *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_long() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_LONG. + * + */ H5_HLDLL herr_t H5LTget_attribute_long(hid_t loc_id, const char *obj_name, const char *attr_name, long *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads a \e long \e long attribute. + * + * \param[in] loc_id Location of the object to which + * the attribute is attached + * \param[in] obj_name That object's name + * \param[in] attr_name Attribute name + * \param[out] data Attribute value + * + * \return \herr_t + * + * \details H5LTget_attribute_long_long() reads the attribute + * specified by \p loc_id and \p obj_name. + * + */ H5_HLDLL herr_t H5LTget_attribute_long_long(hid_t loc_id, const char *obj_name, const char *attr_name, long long *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_ulong() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_ULONG. + * + */ H5_HLDLL herr_t H5LTget_attribute_ulong(hid_t loc_id, const char *obj_name, const char *attr_name, unsigned long *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_ullong() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_ULLONG. + * + */ +H5_HLDLL herr_t H5LTget_attribute_ullong(hid_t loc_id, const char *obj_name, const char *attr_name, + unsigned long long *data); + +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_float() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_FLOAT. + * + */ H5_HLDLL herr_t H5LTget_attribute_float(hid_t loc_id, const char *obj_name, const char *attr_name, float *data); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Reads an attribute from disk. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] data Buffer with data + * + * \return \herr_t + * + * \details H5LTget_attribute_double() reads an attribute named + * \p attr_name that is attached to the object specified + * by the name \p obj_name. The HDF5 datatype of the + * attribute is #H5T_NATIVE_DOUBLE. + * + */ H5_HLDLL herr_t H5LTget_attribute_double(hid_t loc_id, const char *obj_name, const char *attr_name, double *data); @@ -195,8 +1306,55 @@ H5_HLDLL herr_t H5LTget_attribute_double(hid_t loc_id, const char *obj_name, con *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Gets the dimensionality of an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] rank The dimensionality of the attribute + * + * \return \herr_t + * + * \details H5LTget_attribute_ndims() gets the dimensionality of an attribute + * named \p attr_name that is attached to the object specified + * by the name \p obj_name. + * + */ H5_HLDLL herr_t H5LTget_attribute_ndims(hid_t loc_id, const char *obj_name, const char *attr_name, int *rank); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Gets information about an attribute. + * + * \param[in] loc_id Identifier of the object (dataset or group) + * to read the attribute from + * \param[in] obj_name The name of the object that the attribute is + * attached to + * \param[in] attr_name The attribute name + * \param[out] dims The dimensions of the attribute + * \param[out] type_class The class identifier. #H5T_class_t is + * defined in H5Tpublic.h. For a list of valid class + * types see: H5Tget_class(). + * \param[out] type_size The size of the datatype in bytes + * + * \return \herr_t + * + * \details H5LTget_attribute_info() gets information about an attribute + * named \p attr_name attached to the object specified by + * the name \p obj_name. + * + * \par Example + * \snippet H5LT_examples.c get_attribute_info + * + */ H5_HLDLL herr_t H5LTget_attribute_info(hid_t loc_id, const char *obj_name, const char *attr_name, hsize_t *dims, H5T_class_t *type_class, size_t *type_size); @@ -207,7 +1365,74 @@ H5_HLDLL herr_t H5LTget_attribute_info(hid_t loc_id, const char *obj_name, const *------------------------------------------------------------------------- */ -H5_HLDLL hid_t H5LTtext_to_dtype(const char *text, H5LT_lang_t lang_type); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates an HDF5 datatype given a text description. + * + * \param[in] text A character string containing a DDL + * definition of the datatype to be created + * \param[in] lang_type The language used to describe the datatype. + * The only currently supported language is + * #H5LT_DDL. + * + * \return Returns the datatype identifier(non-negative) if successful; + * otherwise returns a negative value. + * + * \details Given a text description of a datatype, this function creates + * an HDF5 datatype and returns the datatype identifier. + * The text description of the datatype has to comply with the + * \p lang_type definition of HDF5 datatypes. + * Currently, only the DDL(#H5LT_DDL) is supported. + * The complete DDL definition of HDF5 datatypes can be found in + * the last chapter of the + * + * HDF5 User's Guide. + * + * \par Example + * An example of DDL definition of \c enum type is shown as follows. + * \snippet H5LT_examples.c enum + * + */ +H5_HLDLL hid_t H5LTtext_to_dtype(const char *text, H5LT_lang_t lang_type); + +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Creates a text description of an HDF5 datatype. + * + * \param[in] dtype Identifier of the datatype to be converted + * \param[out] str Buffer for the text description of the datatype + * \param[in] lang_type The language used to describe the datatype. + * The currently supported language is #H5LT_DDL. + * \param[out] len The size of buffer needed to store the text description + * + * \return \herr_t + * + * \details Given an HDF5 datatype identifier, this function creates + * a description of this datatype in \p lang_type language format. + * A preliminary H5LTdtype_to_text() call can be made to determine + * the size of the buffer needed with a NULL passed in for \p str. + * This value is returned as \p len. That value can then be assigned + * to len for a second H5Ttype_to_text() call, which will + * retrieve the actual text description for the datatype. + * + * If \p len is not big enough for the description, the text + * description will be truncated to fit in the buffer. + * + * Currently only DDL (#H5LT_DDL) is supported for \p lang_type. + * The complete DDL definition of HDF5 data types can be found in + * the last chapter of the + * + * HDF5 User's Guide. + * + * \par Example + * An example of DDL definition of \c enum type is shown as follows. + * \snippet H5LT_examples.c enum + * + */ H5_HLDLL herr_t H5LTdtype_to_text(hid_t dtype, char *str, H5LT_lang_t lang_type, size_t *len); /*------------------------------------------------------------------------- @@ -217,8 +1442,115 @@ H5_HLDLL herr_t H5LTdtype_to_text(hid_t dtype, char *str, H5LT_lang_t lang_type, *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Determines whether an attribute exists. + * + * \param[in] loc_id Identifier of the object to which the attribute + * is expected to be attached + * \param[in] name Attribute name + * + * \return \htri_t + * + * \details H5LTfind_attribute() determines whether an attribute named + * \p name exists attached to the object specified + * by \p loc_id. + * + * \p loc_id must be an object identifier and \p name + * must specify an attribute that is expected to be attached + * to that object. + * + */ H5_HLDLL herr_t H5LTfind_attribute(hid_t loc_id, const char *name); +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Determines whether an HDF5 path is valid and, optionally, + * whether the path resolves to an HDF5 object. + * + * \param[in] loc_id Identifier of an object in the file + * \param[in] path The path to the object to check; + * links in \p path may be of any type. + * \param[in] check_object_valid If TRUE, determine whether the final + * component of \p path resolves to + * an object; if FALSE, do not check. + * + * \return Upon success: + * \return If \p check_object_valid is set to \c FALSE: + * \return Returns \c TRUE if the path is valid; + * otherwise returns \c FALSE. + * \return If \p check_object_valid is set to \c TRUE: + * \return Returns \c TRUE if the path is valid and + * resolves to an HDF5 object; + * otherwise returns \c FALSE. + * + * \return Upon error, returns a negative value. + * + * \details H5LTpath_valid() checks the validity of \p path relative + * to the identifier of an object, \p loc_id. Optionally, + * \p check_object_valid can be set to determine whether the + * final component of \p path resolves to an HDF5 object; + * if not, the final component is a dangling link. + * + * The meaning of the function's return value depends on the + * value of \p check_object_valid: + * + * If \p check_object_valid is set to \c FALSE, H5LTpath_valid() + * will check all links in \p path to verify that they exist. + * If all the links in \p path exist, the function will + * return \c TRUE; otherwise the function will return \c FALSE. + * + * If \p check_object_valid is set to \c TRUE, + * H5LTpath_valid() will first check the links in \p path, + * as described above. If all the links exist, + * \p check_object_valid will then determine whether the final + * component of \p path resolves to an actual HDF5 object. + * H5LTpath_valid() will return \c TRUE if all the links in + * \p path exist and the final component resolves to an + * actual object; otherwise, it will return \c FALSE. + * + * \p path can be any one of the following: + * + * - An absolute path, which starts with a slash (\c /) + * indicating the file's root group, followed by the members + * - A relative path with respect to \p loc_id + * - A dot (\c .), if \p loc_id is the object identifier for + * the object itself. + * + * If \p path is an absolute path, then \p loc_id can be an + * identifier for any object in the file as it is used only to + * identify the file. If \p path is a relative path, then + * \p loc_id must be a file or a group identifier. + * + * \note + * Note on Behavior Change: + * The behavior of H5LTpath_valid() was changed in the 1.10.0 release + * in the case where the root group, “/”, is the value of path. + * This change is described below: + * - Let \p loc_id denote a valid HDF5 file identifier, and let + * \p check_object_valid be set to true or false. + * A call to H5LTpath_valid() with arguments \p loc_id, “/”, + * and \p check_object_valid returns a positive value; + * in other words, H5LTpath_valid(loc_id, "/", check_object_valid) + * returns a positive value. + * In HDF5 version 1.8.16, this function returns 0. + * - Let ‘root’ denote a valid HDF5 group identifier that refers + * to the root group of an HDF5 file, and let \p check_object_valid + * be set to true or false. + * A call to H5LTpath_valid() with arguments ‘root’, “/”, and + * \p check_object_valid returns a positive value; + * in other words, H5LTpath_valid(root, "/", check_object_valid) + * returns a positive value. + * In HDF5 version 1.8.16, this function returns 0. + * + * \version 1.10.0 Function behavior changed in this release. + * See the “Note on Behavior Change” section above. + * + */ H5_HLDLL htri_t H5LTpath_valid(hid_t loc_id, const char *path, hbool_t check_object_valid); /*------------------------------------------------------------------------- @@ -228,6 +1560,80 @@ H5_HLDLL htri_t H5LTpath_valid(hid_t loc_id, const char *path, hbool_t check_obj *------------------------------------------------------------------------- */ +/** + *------------------------------------------------------------------------- + * \ingroup H5LT + * + * \brief Opens an HDF5 file image in memory. + * + * \param[in] buf_ptr A pointer to the supplied initial image + * \param[in] buf_size Size of the supplied buffer + * \param[in] flags Flags specifying whether to open the image + * read-only or read/write, whether HDF5 is to + * take control of the buffer, and instruction + * regarding releasing the buffer. + * + * \return Returns a file identifier if successful; + * otherwise returns a negative value. + * \warning \Bold{Failure Modes:} + * \warning H5LTopen_file_image() will fail if either \p buf_ptr is NULL + * or \p buf_size equals 0 (zero). + * + * + * \details H5LTopen_file_image() opens the HDF5 file image that is + * located in system memory at the address indicated by + * \p buf_ptr of size \p buf_size. + * H5LTopen_file_image() opens a file image with the + * Core driver, #H5FD_CORE. + * + * A value of NULL for \p buf_ptr is invalid and will + * cause the function to fail. + * + * A value of 0 for \p buf_size is invalid and will cause + * the function to fail. + * + * The flags passed in \p flags specify whether to open the image + * read-only or read/write, whether HDF5 is to take control of the + * buffer, and instruction regarding releasing the buffer. + * Valid values are: + * - #H5LT_FILE_IMAGE_OPEN_RW + * - Specifies opening the file image in read/write mode. + * - Default without this flag: File image will be opened read-only. + * + * - #H5LT_FILE_IMAGE_DONT_COPY + * - Specifies to not copy the provided file image buffer; + * the buffer will be used directly. HDF5 will release the + * file image when finished. + * - Default without this flag: Copy the file image buffer and + * open the copied file image. + * + * - #H5LT_FILE_IMAGE_DONT_RELEASE + * - Specifies that HDF5 is not to release the buffer when + * the file opened with H5LTopen_file_image() is closed; + * releasing the buffer will be left to the application. + * - Default without this flag: HDF5 will automatically + * release the file image buffer after the file image is + * closed. This flag is valid only when used with + * #H5LT_FILE_IMAGE_DONT_COPY. + * + * \note **Motivation:** + * \note H5LTopen_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. + * + * \note **Recommended Reading:** + * \note 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 There is no "See Also" section??? + * + * \since 1.8.9 + */ H5_HLDLL hid_t H5LTopen_file_image(void *buf_ptr, size_t buf_size, unsigned flags); #ifdef __cplusplus diff --git a/libs/windows/include/H5LaccProp.h b/libs/windows/include/H5LaccProp.h index 4fa516c..53389e2 100644 --- a/libs/windows/include/H5LaccProp.h +++ b/libs/windows/include/H5LaccProp.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -32,7 +31,7 @@ class H5_DLLCPP LinkAccPropList : public PropList { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("LinkAccPropList"); } @@ -52,7 +51,7 @@ class H5_DLLCPP LinkAccPropList : public PropList { size_t getNumLinks() const; // Noop destructor - virtual ~LinkAccPropList(); + virtual ~LinkAccPropList() override; #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/libs/windows/include/H5LcreatProp.h b/libs/windows/include/H5LcreatProp.h index aea38e7..233a98b 100644 --- a/libs/windows/include/H5LcreatProp.h +++ b/libs/windows/include/H5LcreatProp.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -32,7 +31,7 @@ class H5_DLLCPP LinkCreatPropList : public PropList { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("LinkCreatPropList"); } @@ -59,7 +58,7 @@ class H5_DLLCPP LinkCreatPropList : public PropList { H5T_cset_t getCharEncoding() const; // Noop destructor - virtual ~LinkCreatPropList(); + virtual ~LinkCreatPropList() override; #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/libs/windows/include/H5Ldevelop.h b/libs/windows/include/H5Ldevelop.h new file mode 100644 index 0000000..148a5a5 --- /dev/null +++ b/libs/windows/include/H5Ldevelop.h @@ -0,0 +1,324 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * This file contains public declarations for the H5L (link) developer + * support routines. + */ + +#ifndef H5Ldevelop_H +#define H5Ldevelop_H + +/* Include package's public header */ +#include "H5Lpublic.h" + +/*****************/ +/* Public Macros */ +/*****************/ + +/** + * \brief Current version of the H5L_class_t struct + */ +#define H5L_LINK_CLASS_T_VERS 1 + +/** + * \brief Version of external link format + */ +#define H5L_EXT_VERSION 0 + +/** + * \brief Valid flags for external links + */ +#define H5L_EXT_FLAGS_ALL 0 + +/*******************/ +/* Public Typedefs */ +/*******************/ + +/* 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 + * functions defined below. + */ +/* Callback prototypes for user-defined links */ +/** + * \brief Link creation callback + */ +typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group, const void *lnkdata, + size_t lnkdata_size, hid_t lcpl_id); +/** + * \brief Callback for link move + */ +typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, + size_t lnkdata_size); +/** + * \brief Callback for link copy + */ +typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, + size_t lnkdata_size); +/** + * \brief Callback during link traversal + */ +typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, + size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id); +/** + * \brief Callback for link deletion + */ +typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata, + size_t lnkdata_size); +/** + * \brief Callback for querying the link. + * + * Returns the size of the buffer needed. + */ +typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, size_t lnkdata_size, + void *buf /*out*/, size_t buf_size); + +/** + * \brief Link prototype + * + * 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 + * functions defined elsewhere. + */ +//! +typedef struct { + int version; /**< Version number of this struct */ + H5L_type_t id; /**< Link type ID */ + const char *comment; /**< Comment for debugging */ + H5L_create_func_t create_func; /**< Callback during link creation */ + H5L_move_func_t move_func; /**< Callback after moving link */ + H5L_copy_func_t copy_func; /**< Callback after copying link */ + H5L_traverse_func_t trav_func; /**< Callback during link traversal */ + H5L_delete_func_t del_func; /**< Callback for link deletion */ + H5L_query_func_t query_func; /**< Callback for queries */ +} H5L_class_t; +//! + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \ingroup H5LA + * + * \brief Registers a user-defined link class or changes behavior of an + * existing class + * + * \param[in] cls Pointer to a buffer containing the struct describing the + * user-defined link class + * + * \return \herr_t + * + * \details H5Lregister() registers a class of user-defined links, or changes + * the behavior of an existing class. + * + * \p cls is a pointer to a buffer containing a copy of the + * H5L_class_t struct. This struct is defined in H5Lpublic.h as + * follows: + * \snippet this H5L_class_t_snip + * + * The class definition passed with \p cls must include at least the + * following: + * \li An H5L_class_t version (which should be #H5L_LINK_CLASS_T_VERS) + * \li A link class identifier, \c class_id + * \li A traversal function, \c trav_func + * + * Remaining \c struct members are optional and may be passed as NULL. + * + * The link class passed in \c class_id must be in the user-definable + * range between #H5L_TYPE_UD_MIN and #H5L_TYPE_UD_MAX + * (see the table below) and will override + * any existing link class with that identifier. + * + * As distributed, valid values of \c class_id used in HDF5 include + * the following (defined in H5Lpublic.h): + * \link_types + * + * The hard and soft link class identifiers cannot be modified or + * reassigned, but the external link class is implemented as an + * example in the user-definable link class identifier range. + * H5Lregister() is used to register additional link classes. It could + * also be used to modify the behavior of the external link class, + * though that is not recommended. + * + * The following table summarizes existing link types and values and + * the reserved and user-definable link class identifier value ranges. + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + * + *
Link class identifier or Value rangeDescriptionLink class or label
0 to 63Reserved range
64 to 255User-definable range
64Minimum user-defined value#H5L_TYPE_UD_MIN
64External link#H5L_TYPE_EXTERNAL
255Maximum user-defined value#H5L_TYPE_UD_MAX
255Maximum value#H5L_TYPE_MAX
-1Error#H5L_TYPE_ERROR
+ * + * Note that HDF5 internally registers user-defined link classes only + * by the numeric value of the link class identifier. An application, + * on the other hand, will generally use a name for a user-defined + * class, if for no other purpose than as a variable name. Assume, + * for example, that a complex link type is registered with the link + * class identifier 73 and that the code includes the following + * assignment: + * \code + * H5L_TYPE_COMPLEX_A = 73 + * \endcode + * The application can refer to the link class with a term, + * \c H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing + * the code, while HDF5 recognizes it by the more cryptic numeric + * identifier, 73. + * + * \attention Important details and considerations include the following: + * \li If you plan to distribute files or software with a + * user-defined link class, please contact the Help Desk at + * The HDF Group to help prevent collisions between \c class_id + * values. See below. + * \li As distributed with HDF5, the external link class is + * implemented as an example of a user-defined link class with + * #H5L_TYPE_EXTERNAL equal to #H5L_TYPE_UD_MIN. \c class_id in + * the H5L_class_t \c struct must not equal #H5L_TYPE_UD_MIN + * unless you intend to overwrite or modify the behavior of + * external links. + * \li H5Lregister() can be used only with link class identifiers + * in the user-definable range (see table above). + * \li The hard and soft links defined by the HDF5 library, + * #H5L_TYPE_HARD and #H5L_TYPE_SOFT, reside in the reserved + * range below #H5L_TYPE_UD_MIN and cannot be redefined or + * modified. + * \li H5Lis_registered() can be used to determine whether a desired + * link class identifier is available. \Emph{Note that this + * function will tell you only whether the link class identifier + * has been registered with the installed copy of HDF5; it + * cannot tell you whether the link class has been registered + * with The HDF Group.} + * \li #H5L_TYPE_MAX is the maximum allowed value for a link type + * identifier. + * \li #H5L_TYPE_UD_MIN equals #H5L_TYPE_EXTERNAL. + * \li #H5L_TYPE_UD_MAX equals #H5L_TYPE_MAX. + * \li #H5L_TYPE_ERROR indicates that an error has occurred. + * + * \note \Bold{Registration with The HDF Group:}\n + * There are sometimes reasons to take a broader approach to registering + * a user-defined link class than just invoking H5Lregister(). For + * example: + * \li A user-defined link class is intended for use across an + * organization, among collaborators, or across a community of users. + * \li An application or library overlying HDF5 invokes a user-defined + * link class that must be shipped with the software. + * \li Files are distributed that make use of a user-defined link class. + * \li Or simply, a specific user-defined link class is thought to be + * widely useful. + * + * In such cases, you are encouraged to register that link class with + * The HDF Group's Helpdesk. The HDF Group maintains a registry of known + * user-defined link classes and tracks the selected link class + * identifiers. This registry is intended to reduce the risk of + * collisions between \c class_id values and to help coordinate the use + * of specialized link classes. + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Lregister(const H5L_class_t *cls); +/** + * \ingroup H5LA + * + * \brief Unregisters a class of user-defined links + * + * \param[in] id User-defined link class identifier + * + * \return \herr_t + * + * \details H5Lunregister() unregisters a class of user-defined links, + * preventing them from being traversed, queried, moved, etc. + * + * \note A link class can be re-registered using H5Lregister(). + * + * \since 1.8.0 + * + */ +H5_DLL herr_t H5Lunregister(H5L_type_t id); + +#ifdef __cplusplus +} +#endif + +/* Symbols defined for compatibility with previous versions of the HDF5 API. + * + * Use of these symbols is deprecated. + */ +#ifndef H5_NO_DEPRECATED_SYMBOLS + +/* Previous versions of the H5L_class_t struct */ +#define H5L_LINK_CLASS_T_VERS_0 0 + +/** Callback during link traversal */ +typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, + size_t lnkdata_size, hid_t lapl_id); + +/** User-defined link types */ +typedef struct { + int version; /**< Version number of this struct */ + H5L_type_t id; /**< Link type ID */ + const char *comment; /**< Comment for debugging */ + H5L_create_func_t create_func; /**< Callback during link creation */ + H5L_move_func_t move_func; /**< Callback after moving link */ + H5L_copy_func_t copy_func; /**< Callback after copying link */ + H5L_traverse_0_func_t trav_func; /**< Callback during link traversal */ + H5L_delete_func_t del_func; /**< Callback for link deletion */ + H5L_query_func_t query_func; /**< Callback for queries */ +} H5L_class_0_t; + +#endif /* H5_NO_DEPRECATED_SYMBOLS */ + +#endif /* H5Ldevelop_H */ diff --git a/libs/windows/include/H5Library.h b/libs/windows/include/H5Library.h index 3df8d56..3770639 100644 --- a/libs/windows/include/H5Library.h +++ b/libs/windows/include/H5Library.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * diff --git a/libs/windows/include/H5Location.h b/libs/windows/include/H5Location.h index 740d0ce..ee45d67 100644 --- a/libs/windows/include/H5Location.h +++ b/libs/windows/include/H5Location.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -15,7 +14,7 @@ #ifndef H5Location_H #define H5Location_H -#include "H5Classes.h" // constains forward class declarations +#include "H5Classes.h" // contains forward class declarations namespace H5 { @@ -108,11 +107,11 @@ class H5_DLLCPP H5Location : public IdComponent { // Creates a new dataset in this location. DataSet createDataSet(const char *name, const DataType &data_type, const DataSpace &data_space, const DSetCreatPropList &create_plist = DSetCreatPropList::DEFAULT, - const DSetAccPropList & dapl = DSetAccPropList::DEFAULT, + const DSetAccPropList &dapl = DSetAccPropList::DEFAULT, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT) const; DataSet createDataSet(const H5std_string &name, const DataType &data_type, const DataSpace &data_space, const DSetCreatPropList &create_plist = DSetCreatPropList::DEFAULT, - const DSetAccPropList & dapl = DSetAccPropList::DEFAULT, + const DSetAccPropList &dapl = DSetAccPropList::DEFAULT, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT) const; // Deprecated to add LinkCreatPropList and DSetAccPropList - 1.10.3 @@ -124,12 +123,12 @@ class H5_DLLCPP H5Location : public IdComponent { // Opens an existing dataset at this location. // DSetAccPropList is added - 1.10.3 DataSet openDataSet(const char *name, const DSetAccPropList &dapl = DSetAccPropList::DEFAULT) const; - DataSet openDataSet(const H5std_string & name, + DataSet openDataSet(const H5std_string &name, const DSetAccPropList &dapl = DSetAccPropList::DEFAULT) const; - H5L_info2_t getLinkInfo(const char * link_name, + H5L_info2_t getLinkInfo(const char *link_name, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; - H5L_info2_t getLinkInfo(const H5std_string & link_name, + H5L_info2_t getLinkInfo(const H5std_string &link_name, const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Returns the value of a symbolic link. @@ -216,26 +215,26 @@ class H5_DLLCPP H5Location : public IdComponent { // Creates a soft link from link_name to target_name. void link(const char *target_name, const char *link_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; void link(const H5std_string &target_name, const H5std_string &link_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Creates a hard link from new_name to curr_name. void link(const char *curr_name, const Group &new_loc, const char *new_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; void link(const H5std_string &curr_name, const Group &new_loc, const H5std_string &new_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Creates a hard link from new_name to curr_name in same location. void link(const char *curr_name, const hid_t same_loc, const char *new_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; void link(const H5std_string &curr_name, const hid_t same_loc, const H5std_string &new_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Creates a link of the specified type from new_name to current_name; // both names are interpreted relative to the specified location id. @@ -258,34 +257,34 @@ class H5_DLLCPP H5Location : public IdComponent { // Copies a link from a group to another. void copyLink(const char *src_name, const Group &dst, const char *dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; void copyLink(const H5std_string &src_name, const Group &dst, const H5std_string &dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Makes a copy of a link in the same group. void copyLink(const char *src_name, const char *dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; void copyLink(const H5std_string &src_name, const H5std_string &dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Renames a link in this group and moves to a new location. void moveLink(const char *src_name, const Group &dst, const char *dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; void moveLink(const H5std_string &src_name, const Group &dst, const H5std_string &dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Renames a link in this group. void moveLink(const char *src_name, const char *dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; void moveLink(const H5std_string &src_name, const H5std_string &dst_name, const LinkCreatPropList &lcpl = LinkCreatPropList::DEFAULT, - const LinkAccPropList & lapl = LinkAccPropList::DEFAULT) const; + const LinkAccPropList &lapl = LinkAccPropList::DEFAULT) const; // Renames an object at this location. // Deprecated due to inadequate functionality. @@ -334,7 +333,7 @@ class H5_DLLCPP H5Location : public IdComponent { #endif // DOXYGEN_SHOULD_SKIP_THIS // Noop destructor. - virtual ~H5Location(); + virtual ~H5Location() override; }; // end of H5Location } // namespace H5 diff --git a/libs/windows/include/H5Lpublic.h b/libs/windows/include/H5Lpublic.h index bf1de86..03b47c5 100644 --- a/libs/windows/include/H5Lpublic.h +++ b/libs/windows/include/H5Lpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -14,8 +13,6 @@ /*------------------------------------------------------------------------- * * Created: H5Lpublic.h - * Dec 1 2005 - * James Laird * * Purpose: Public declarations for the H5L package (links) * @@ -24,11 +21,10 @@ #ifndef H5Lpublic_H #define H5Lpublic_H -/* Public headers needed by this file */ -#include "H5public.h" /* Generic Functions */ -#include "H5Ipublic.h" /* IDs */ -#include "H5Opublic.h" /* Object Headers */ -#include "H5Tpublic.h" /* Datatypes */ +#include "H5public.h" /* Generic Functions */ +#include "H5Ipublic.h" /* Identifiers */ +#include "H5Opublic.h" /* Object Headers */ +#include "H5Tpublic.h" /* Datatypes */ /*****************/ /* Public Macros */ @@ -39,17 +35,12 @@ * * The maximum length of a link's name is encoded in a 32-bit unsigned integer. */ -#define H5L_MAX_LINK_NAME_LEN ((uint32_t)(-1)) /* (4GB - 1) */ +#define H5L_MAX_LINK_NAME_LEN UINT32_MAX /** * \brief Macro to indicate operation occurs on same location */ -#define H5L_SAME_LOC (hid_t)0 - -/** - * \brief Current version of the H5L_class_t struct - */ -#define H5L_LINK_CLASS_T_VERS 1 +#define H5L_SAME_LOC 0 /* (hid_t) */ #ifdef __cplusplus extern "C" { @@ -105,65 +96,6 @@ typedef struct { } H5L_info2_t; //! -/* 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 - * functions defined below. - */ -/* Callback prototypes for user-defined links */ -/** - * \brief Link creation callback - */ -typedef herr_t (*H5L_create_func_t)(const char *link_name, hid_t loc_group, const void *lnkdata, - size_t lnkdata_size, hid_t lcpl_id); -/** - * \brief Callback for link move - */ -typedef herr_t (*H5L_move_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, - size_t lnkdata_size); -/** - * \brief Callback for link copy - */ -typedef herr_t (*H5L_copy_func_t)(const char *new_name, hid_t new_loc, const void *lnkdata, - size_t lnkdata_size); -/** - * \brief Callback during link traversal - */ -typedef hid_t (*H5L_traverse_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, - size_t lnkdata_size, hid_t lapl_id, hid_t dxpl_id); -/** - * \brief Callback for link deletion - */ -typedef herr_t (*H5L_delete_func_t)(const char *link_name, hid_t file, const void *lnkdata, - size_t lnkdata_size); -/** - * \brief Callback for querying the link. - * - * Returns the size of the buffer needed. - */ -typedef ssize_t (*H5L_query_func_t)(const char *link_name, const void *lnkdata, size_t lnkdata_size, - void *buf /*out*/, size_t buf_size); - -/** - * \brief Link prototype - * - * 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 - * functions defined elsewhere. - */ -//! -typedef struct { - int version; /**< Version number of this struct */ - H5L_type_t id; /**< Link type ID */ - const char * comment; /**< Comment for debugging */ - H5L_create_func_t create_func; /**< Callback during link creation */ - H5L_move_func_t move_func; /**< Callback after moving link */ - H5L_copy_func_t copy_func; /**< Callback after copying link */ - H5L_traverse_func_t trav_func; /**< Callback during link traversal */ - H5L_delete_func_t del_func; /**< Callback for link deletion */ - H5L_query_func_t query_func; /**< Callback for queries */ -} H5L_class_t; -//! - /** * \brief Prototype for H5Literate2(), H5Literate_by_name2() operator * @@ -266,7 +198,7 @@ H5_DLL herr_t H5Lmove(hid_t src_loc, const char *src_name, hid_t dst_loc, const * \p dst_name. * * If \p dst_loc_id is a file identifier, \p dst_name will be - * interpreted relative to that file’s root group. + * interpreted relative to that file's root group. * * The new link is created with the creation and access property lists * specified by \p lcpl_id and \p lapl_id. The interpretation of @@ -274,7 +206,7 @@ H5_DLL herr_t H5Lmove(hid_t src_loc, const char *src_name, hid_t dst_loc, const * * H5Lcopy() retains the creation time and the target of the original * link. However, since the link may be renamed, the character - * encoding is that specified in \p lcpl_id rather than that of the + * encoding is specified in \p lcpl_id rather than in that of the * original link. Other link creation properties are ignored. * * If the link is a soft link, also known as a symbolic link, its @@ -353,6 +285,19 @@ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Lcreate_hard_async(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); +#endif /** * \ingroup H5L * @@ -389,7 +334,7 @@ H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, hid_t dst_loc, * * For instance, if target_path is \c ./foo, \p link_loc_id specifies * \c ./x/y/bar, and the name of the new link is \c new_link, then a - * subsequent request for \c ./x/y/bar/new_link will return same the + * subsequent request for \c ./x/y/bar/new_link will return the same * object as would be found at \c ./foo. * * \note H5Lcreate_soft() is for use only if the target object is in the @@ -397,7 +342,7 @@ H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, hid_t dst_loc, * the new link, use H5Lcreate_external() to create an external link. * * \note Soft links and external links are also known as symbolic links as they - * use a name to point to an object; hard links employ an object’s + * use a name to point to an object; hard links employ an object's * address in the file. * * \note Unlike hard links, a soft link in an HDF5 file is allowed to dangle, @@ -417,6 +362,19 @@ H5_DLL herr_t H5Lcreate_hard(hid_t cur_loc, const char *cur_name, hid_t dst_loc, */ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Lcreate_soft_async(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); +#endif /** * \ingroup H5L * @@ -454,6 +412,17 @@ H5_DLL herr_t H5Lcreate_soft(const char *link_target, hid_t link_loc_id, const c * */ H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Ldelete} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Ldelete_async(hid_t loc_id, const char *name, hid_t lapl_id, hid_t es_id); +#endif /** * \ingroup H5L * @@ -482,6 +451,19 @@ H5_DLL herr_t H5Ldelete(hid_t loc_id, const char *name, hid_t lapl_id); */ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Ldelete_by_idx_async(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); +#endif /** * \ingroup H5L * @@ -495,7 +477,7 @@ H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t * * \return \herr_t * - * \details H5Lget_val() returns tha value of link \p name. For smbolic links, + * \details H5Lget_val() returns the value of link \p name. For symbolic links, * this is the path to which the link points, including the null * terminator. For external and user-defined links, it is the link * buffer. @@ -525,7 +507,7 @@ H5_DLL herr_t H5Ldelete_by_idx(hid_t loc_id, const char *group_name, H5_index_t * * This function should be used only after H5Lget_info() has been * called to verify that \p name is a symbolic link. This can be - * deteremined from the \c link_type field of the \ref H5L_info_t + * determined from the \c link_type field of the \ref H5L_info_t * \c struct. * * \note This function will fail if called on a hard link. @@ -613,7 +595,7 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t * name includes either a relative path or an absolute path to the * target link, intermediate steps along the path must be verified * before the existence of the target link can be safely checked. If - * the path is not verified and an intermediate element of the path + * the path is not verified, and an intermediate element of the path * does not exist, H5Lexists() will fail. The example in the next * paragraph illustrates one step-by-step method for verifying the * existence of a link with a relative or absolute path. @@ -622,7 +604,7 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t * the link \c datasetD in the \c group group1/group2/softlink_to_group3/, * where \c group1 is a member of the group specified by \c loc_id: * - * 1. First use H5Lexists() to verify that \c group1 exists. + * 1. First, use H5Lexists() to verify that the \c group1 exists. * 2. If \c group1 exists, use H5Lexists() again, this time with name * set to \c group1/group2, to verify that \c group2 exists. * 3. If \c group2 exists, use H5Lexists() with name set to @@ -635,11 +617,11 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t * * If the link to be verified is specified with an absolute path, the * same approach should be used, but starting with the first link in - * the file’s root group. For instance, if \c datasetD were in + * the file's root group. For instance, if \c datasetD were in * \c /group1/group2/softlink_to_group3, the first call to H5Lexists() * would have name set to \c /group1. * - * Note that this is an outline and does not include all necessary + * Note that this is an outline and does not include all the necessary * details. Depending on circumstances, for example, you may need to * verify that an intermediate link points to a group and that a soft * link points to an existing target. @@ -653,13 +635,13 @@ H5_DLL herr_t H5Lget_val_by_idx(hid_t loc_id, const char *group_name, H5_index_t * H5Lexists() with arguments \c file, \c "/", and \c lapl * returns a positive value; in other words, * \Code{H5Lexists(file, "/", lapl)} returns a positive value. - * In HDF5 version 1.8.16, this function returns 0. + * In the HDF5 1.8 release, this function returns 0. *
  • Let \c root denote a valid HDF5 group identifier that refers to the * root group of an HDF5 file, and let \c lapl denote a valid link * access property list identifier. A call to H5Lexists() with * arguments c root, \c "/", and \c lapl returns a positive value; - * in other words, \Code{H5Lexists(root, "/", lapl)} returns a postive - * value. In HDF5 version 1.8.16, this function returns 0.
    • + * in other words, \Code{H5Lexists(root, "/", lapl)} returns a positive + * value. In the HDF5 1.8 release, this function returns 0. * * Note that the function accepts link names and path names. This is * potentially misleading to callers, and we plan to separate the @@ -680,6 +662,17 @@ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Lexists_async(hid_t loc_id, const char *name, hbool_t *exists, hid_t lapl_id, hid_t es_id); +#endif /** * \ingroup H5L * @@ -717,11 +710,11 @@ H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id); * There will be additional valid values if user-defined links have * been registered. * - * \p corder specifies the link’s creation order position while + * \p corder specifies the link's creation order position, while * \p corder_valid indicates whether the value in corder is valid. * - * If \p corder_valid is \c TRUE, the value in \p corder is known to - * be valid; if \p corder_valid is \c FALSE, the value in \p corder is + * If \p corder_valid is \c true, the value in \p corder is known to + * be valid; if \p corder_valid is \c false, the value in \p corder is * presumed to be invalid; \p corder starts at zero (0) and is * incremented by one (1) as new links are created. But * higher-numbered entries are not adjusted when a lower-numbered link @@ -733,10 +726,10 @@ H5_DLL htri_t H5Lexists(hid_t loc_id, const char *name, hid_t lapl_id); * \p cset specifies the character set in which the link name is * encoded. Valid values include the following: * \csets - * This value is set with H5Pset_char_encoding(). + * This value is set with #H5Pset_char_encoding. * * \c token is the location that a hard link points to, and - * \c val_size is the size of a soft link or user defined link value. + * \c val_size is the size of a soft link or user-defined link value. * H5O_token_t is used in the VOL layer. It is defined in H5public.h * as: * \snippet H5public.h H5O_token_t_snip @@ -888,10 +881,12 @@ H5_DLL ssize_t H5Lget_name_by_idx(hid_t loc_id, const char *group_name, H5_index * not been indexed by the index type, they will first be sorted by * that index then the iteration will begin; if the links have been * so indexed, the sorting step will be unnecessary, so the iteration - * may begin more quickly. + * may begin more quickly. Valid values include the following: + * \indexes * * \p order specifies the order in which objects are to be inspected - * along the index \p idx_type. + * along the index \p idx_type. Valid values include the following: + * \orders * * \p idx_p tracks the iteration and allows an iteration to be * resumed if it was stopped before all members were processed. It is @@ -924,6 +919,24 @@ 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 + * + * \warning The returned value of the callback routine op will not be set + * in the return value for H5Literate_async(), so the \p herr_t value + * should not be used for determining the return state of the callback routine. + * + * \async_variant_of{H5Literate} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Literate_async(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); +#endif /** * \ingroup TRAV * @@ -967,6 +980,12 @@ H5_DLL herr_t H5Literate2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t ord * passed in by the application with a starting point and returned by * the library with the point at which the iteration stopped. * + * \warning H5Literate_by_name2() assumes that the membership of the group being + * iterated over remains unchanged through the iteration; if any of the + * links in the group change during the iteration, the function's + * behavior is undefined. Note, however, that objects pointed to by the + * links can be modified. + * * \note H5Literate_by_name2() is not recursive. In particular, if a member of * \p group_name is found to be a group, call it \c subgroup_a, * H5Literate_by_name2() does not examine the members of \c subgroup_a. @@ -974,12 +993,6 @@ H5_DLL herr_t H5Literate2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t ord * recursion, explicitly calling H5Literate_by_name2() on discovered * subgroups. * - * \note H5Literate_by_name2() assumes that the membership of the group being - * iterated over remains unchanged through the iteration; if any of the - * links in the group change during the iteration, the function’s - * behavior is undefined. Note, however, that objects pointed to by the - * links can be modified. - * * \note H5Literate_by_name2() is the same as H5Literate2(), except that * H5Literate2() always proceeds in alphanumeric order. * @@ -1099,10 +1112,10 @@ H5_DLL herr_t H5Lvisit2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order * The group serving as the root of the iteration is specified by the * \p loc_id / \p group_name parameter pair. \p loc_id specifies a * file or group; group_name specifies either a group in the file - * (with an absolute name based in the file’s root group) or a group + * (with an absolute name based in the file's root group) or a group * relative to \p loc_id. If \p loc_id fully specifies the group that * is to serve as the root of the iteration, group_name should be '.' - * (a dot). (Note that when \p loc_id fully specifies the the group + * (a dot). (Note that when \p loc_id fully specifies the group * that is to serve as the root of the iteration, the user may wish to * consider using H5Lvisit2() instead of H5Lvisit_by_name2().) * @@ -1112,7 +1125,7 @@ H5_DLL herr_t H5Lvisit2(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order * \p idx_type specifies the index to be used. If the links have not * been indexed by the index type, they will first be sorted by that * index then the iteration will begin; if the links have been so - * indexed, the sorting step will be unnecesary, so the iteration may + * indexed, the sorting step will be unnecessary, so the iteration may * begin more quickly. Valid values include the following: * \indexes * @@ -1201,179 +1214,6 @@ H5_DLL herr_t H5Lvisit_by_name2(hid_t loc_id, const char *group_name, H5_index_t */ H5_DLL herr_t H5Lcreate_ud(hid_t link_loc_id, const char *link_name, H5L_type_t link_type, const void *udata, size_t udata_size, hid_t lcpl_id, hid_t lapl_id); -/** - * \ingroup H5LA - * - * \brief Registers a user-defined link class or changes behavior of an - * existing class - * - * \param[in] cls Pointer to a buffer containing the struct describing the - * user-defined link class - * - * \return \herr_t - * - * \details H5Lregister() registers a class of user-defined links, or changes - * the behavior of an existing class. - * - * \p cls is a pointer to a buffer containing a copy of the - * H5L_class_t struct. This struct is defined in H5Lpublic.h as - * follows: - * \snippet this H5L_class_t_snip - * - * The class definition passed with \p cls must include at least the - * following: - * \li An H5L_class_t version (which should be #H5L_LINK_CLASS_T_VERS) - * \li A link class identifier, \c class_id - * \li A traversal function, \c trav_func - * - * Remaining \c struct members are optional and may be passed as NULL. - * - * The link class passed in \c class_id must be in the user-definable - * range between #H5L_TYPE_UD_MIN and #H5L_TYPE_UD_MAX - * (see the table below) and will override - * any existing link class with that identifier. - * - * As distributed, valid values of \c class_id used in HDF5 include - * the following (defined in H5Lpublic.h): - * \link_types - * - * The hard and soft link class identifiers cannot be modified or - * reassigned, but the external link class is implemented as an - * example in the user-definable link class identifier range. - * H5Lregister() is used to register additional link classes. It could - * also be used to modify the behavior of the external link class, - * though that is not recommended. - * - * The following table summarizes existing link types and values and - * the reserved and user-definable link class identifier value ranges. - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
    Link class identifier or Value rangeDescriptionLink class or label
    0 to 63Reserved range
    64 to 255User-definable range
    64Minimum user-defined value#H5L_TYPE_UD_MIN
    64External link#H5L_TYPE_EXTERNAL
    255Maximum user-defined value#H5L_TYPE_UD_MAX
    255Maximum value#H5L_TYPE_MAX
    -1Error#H5L_TYPE_ERROR
    - * - * Note that HDF5 internally registers user-defined link classes only - * by the numeric value of the link class identifier. An application, - * on the other hand, will generally use a name for a user-defined - * class, if for no other purpose than as a variable name. Assume, - * for example, that a complex link type is registered with the link - * class identifier 73 and that the code includes the following - * assignment: - * \code - * H5L_TYPE_COMPLEX_A = 73 - * \endcode - * The application can refer to the link class with a term, - * \c H5L_TYPE_COMPLEX_A, that conveys meaning to a human reviewing - * the code, while HDF5 recognizes it by the more cryptic numeric - * identifier, 73. - * - * \attention Important details and considerations include the following: - * \li If you plan to distribute files or software with a - * user-defined link class, please contact the Help Desk at - * The HDF Group to help prevent collisions between \c class_id - * values. See below. - * \li As distributed with HDF5, the external link class is - * implemented as an example of a user-defined link class with - * #H5L_TYPE_EXTERNAL equal to #H5L_TYPE_UD_MIN. \c class_id in - * the H5L_class_t \c struct must not equal #H5L_TYPE_UD_MIN - * unless you intend to overwrite or modify the behavior of - * external links. - * \li H5Lregister() can be used only with link class identifiers - * in the user-definable range (see table above). - * \li The hard and soft links defined by the HDF5 library, - * #H5L_TYPE_HARD and #H5L_TYPE_SOFT, reside in the reserved - * range below #H5L_TYPE_UD_MIN and cannot be redefined or - * modified. - * \li H5Lis_registered() can be used to determine whether a desired - * link class identifier is available. \Emph{Note that this - * function will tell you only whether the link class identifier - * has been registered with the installed copy of HDF5; it - * cannot tell you whether the link class has been registered - * with The HDF Group.} - * \li #H5L_TYPE_MAX is the maximum allowed value for a link type - * identifier. - * \li #H5L_TYPE_UD_MIN equals #H5L_TYPE_EXTERNAL. - * \li #H5L_TYPE_UD_MAX equals #H5L_TYPE_MAX. - * \li #H5L_TYPE_ERROR indicates that an error has occurred. - * - * \note \Bold{Registration with The HDF Group:}\n - * There are sometimes reasons to take a broader approach to registering - * a user-defined link class than just invoking H5Lregister(). For - * example: - * \li A user-defined link class is intended for use across an - * organization, among collaborators, or across a community of users. - * \li An application or library overlying HDF5 invokes a user-defined - * link class that must be shipped with the software. - * \li Files are distributed that make use of a user-defined link class. - * \li Or simply, a specific user-defined link class is thought to be - * widely useful. - * - * In such cases, you are encouraged to register that link class with - * The HDF Group's Helpdesk. The HDF Group maintains a registry of known - * user-defined link classes and tracks the selected link class - * identifiers. This registry is intended to reduce the risk of - * collisions between \c class_id values and to help coordinate the use - * of specialized link classes. - * - * \since 1.8.0 - * - */ -H5_DLL herr_t H5Lregister(const H5L_class_t *cls); -/** - * \ingroup H5LA - * - * \brief Unregisters a class of user-defined links - * - * \param[in] id User-defined link class identifier - * - * \return \herr_t - * - * \details H5Lunregister() unregisters a class of user-defined links, - * preventing them from being traversed, queried, moved, etc. - * - * \note A link class can be re-registered using H5Lregister(). - * - * \since 1.8.0 - * - */ -H5_DLL herr_t H5Lunregister(H5L_type_t id); /** * \ingroup H5LA * @@ -1461,7 +1301,7 @@ H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_si * \p file_name identifies the target file containing the target * object; \p obj_name specifies the path of the target object within * that file. \p obj_name must be an absolute pathname in - * \p file_name, i.e., it must start at the target file’s root group, + * \p file_name, i.e., it must start at the target file's root group, * but it is not interpreted until an application attempts to traverse * it. * @@ -1520,7 +1360,7 @@ H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_si * If that target file does not exist, the new \p file_name after * stripping will be \c A.h5. * - For Windows, there are 6 cases: - * -# \p file_name is an absolute drive with absolute pathname. + * -# \p file_name is an absolute drive with an absolute pathname. * For example, consider a \p file_name of \c /tmp/A.h5. If that * target file does not exist, the new \p file_name after * stripping will be \c A.h5. @@ -1528,16 +1368,16 @@ H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_si * name. For example, consider a \p file_name of \c /tmp/A.h5. * If that target file does not exist, the new \p file_name after * stripping will be \c A.h5. - * -# \p file_name is an absolute drive with relative pathname. + * -# \p file_name is an absolute drive with a relative pathname. * For example, consider a \p file_name of \c /tmp/A.h5. If that * target file does not exist, the new \p file_name after * stripping will be \c tmp\A.h5. * -# \p file_name is in UNC (Uniform Naming Convention) format with - * server name, share name, and pathname. For example, consider + * a server name, share name, and pathname. For example, consider * a \p file_name of \c /tmp/A.h5. If that target file does not * exist, the new \p file_name after stripping will be \c A.h5. * -# \p file_name is in Long UNC (Uniform Naming Convention) format - * with server name, share name, and pathname. For example, + * with a server name, share name, and pathname. For example, * consider a \p file_name of \c /tmp/A.h5. If that target file * does not exist, the new \p file_name after stripping will be * \c A.h5. @@ -1547,7 +1387,7 @@ H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_si * does not exist, the new \p file_name after stripping will be * \c A.h5. * - * The library opens target file \p file_name with the file access + * The library opens the target file \p file_name with the file access * property list that is set via H5Pset_elink_fapl() when the external * link link_name is accessed. If no such property list is set, the * library uses the file access property list associated with the file @@ -1571,6 +1411,30 @@ H5_DLL herr_t H5Lunpack_elink_val(const void *ext_linkval /*in*/, size_t link_si H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hid_t link_loc_id, const char *link_name, hid_t lcpl_id, hid_t lapl_id); +/// \cond DEV +/* API Wrappers for async routines */ +/* (Must be defined _after_ the function prototype) */ +/* (And must only defined when included in application code, not the library) */ +#ifndef H5L_MODULE +#define H5Lcreate_hard_async(...) H5Lcreate_hard_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Lcreate_soft_async(...) H5Lcreate_soft_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Ldelete_async(...) H5Ldelete_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Ldelete_by_idx_async(...) H5Ldelete_by_idx_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Lexists_async(...) H5Lexists_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Literate_async(...) H5Literate_async(__FILE__, __func__, __LINE__, __VA_ARGS__) + +/* Define "wrapper" versions of function calls, to allow compile-time values to + * be passed in by language wrapper or library layer on top of HDF5. + */ +#define H5Lcreate_hard_async_wrap H5_NO_EXPAND(H5Lcreate_hard_async) +#define H5Lcreate_soft_async_wrap H5_NO_EXPAND(H5Lcreate_soft_async) +#define H5Ldelete_async_wrap H5_NO_EXPAND(H5Ldelete_async) +#define H5Ldelete_by_idx_async_wrap H5_NO_EXPAND(H5Ldelete_by_idx_async) +#define H5Lexists_async_wrap H5_NO_EXPAND(H5Lexists_async) +#define H5Literate_async_wrap H5_NO_EXPAND(H5Literate_async) +#endif /* H5L_MODULE */ +/// \endcond + /* Symbols defined for compatibility with previous versions of the HDF5 API. * * Use of these symbols is deprecated. @@ -1579,9 +1443,6 @@ H5_DLL herr_t H5Lcreate_external(const char *file_name, const char *obj_name, hi /* Macros */ -/* Previous versions of the H5L_class_t struct */ -#define H5L_LINK_CLASS_T_VERS_0 0 - /* Typedefs */ //! @@ -1600,23 +1461,6 @@ typedef struct { } H5L_info1_t; //! -/** Callback during link traversal */ -typedef hid_t (*H5L_traverse_0_func_t)(const char *link_name, hid_t cur_group, const void *lnkdata, - size_t lnkdata_size, hid_t lapl_id); - -/** User-defined link types */ -typedef struct { - int version; /**< Version number of this struct */ - H5L_type_t id; /**< Link type ID */ - const char * comment; /**< Comment for debugging */ - H5L_create_func_t create_func; /**< Callback during link creation */ - H5L_move_func_t move_func; /**< Callback after moving link */ - H5L_copy_func_t copy_func; /**< Callback after copying link */ - H5L_traverse_0_func_t trav_func; /**< Callback during link traversal */ - H5L_delete_func_t del_func; /**< Callback for link deletion */ - H5L_query_func_t query_func; /**< Callback for queries */ -} H5L_class_0_t; - /** Prototype for H5Literate1() / H5Literate_by_name1() operator */ //! typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_t *info, void *op_data); @@ -1663,16 +1507,16 @@ typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_ * There will be additional valid values if user-defined links have * been registered. * - * \c corder specifies the link’s creation order position while + * \c corder specifies the link's creation order position while * \c corder_valid indicates whether the value in \c corder is valid. * - * If \c corder_valid is \c TRUE, the value in \c corder is known to - * be valid; if \c corder_valid is \c FALSE, the value in \c corder is + * If \c corder_valid is \c true, the value in \c corder is known to + * be valid; if \c corder_valid is \c false, the value in \c corder is * presumed to be invalid; * * \c corder starts at zero (0) and is incremented by one (1) as new * links are created. But higher-numbered entries are not adjusted - * when a lower-numbered link is deleted; the deleted link’s creation + * when a lower-numbered link is deleted; the deleted link's creation * order position is simply left vacant. In such situations, the value * of \c corder for the last link created will be larger than the * number of links remaining in the group. @@ -1680,7 +1524,7 @@ typedef herr_t (*H5L_iterate1_t)(hid_t group, const char *name, const H5L_info1_ * \c cset specifies the character set in which the link name is * encoded. Valid values include the following: * \csets - * This value is set with H5Pset_char_encoding(). + * This value is set with #H5Pset_char_encoding. * * \c address and \c val_size are returned for hard and symbolic * links, respectively. Symbolic links include soft and external links @@ -1796,10 +1640,12 @@ H5_DLL herr_t H5Lget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index * not been indexed by the index type, they will first be sorted by * that index then the iteration will begin; if the links have been * so indexed, the sorting step will be unnecessary, so the iteration - * may begin more quickly. + * may begin more quickly. Valid values include the following: + * \indexes * * \p order specifies the order in which objects are to be inspected - * along the index \p idx_type. + * along the index \p idx_type. Valid values include the following: + * \orders * * \p idx_p tracks the iteration and allows an iteration to be * resumed if it was stopped before all members were processed. It is @@ -1824,7 +1670,6 @@ H5_DLL herr_t H5Lget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index * This does not limit the ability to change link destinations * while iterating, but caution is advised. * - * * \version 1.12.0 Function was deprecated in this release. * \since 1.8.0 * @@ -1881,6 +1726,12 @@ H5_DLL herr_t H5Literate1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t ord * passed in by the application with a starting point and returned by * the library with the point at which the iteration stopped. * + * \warning H5Literate_by_name1() assumes that the membership of the group being + * iterated over remains unchanged through the iteration; if any of the + * links in the group change during the iteration, the function's + * behavior is undefined. Note, however, that objects pointed to by the + * links can be modified. + * * \note H5Literate_by_name1() is not recursive. In particular, if a member of * \p group_name is found to be a group, call it \c subgroup_a, * H5Literate_by_name1() does not examine the members of \c subgroup_a. @@ -1888,12 +1739,6 @@ H5_DLL herr_t H5Literate1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t ord * recursion, explicitly calling H5Literate_by_name1() on discovered * subgroups. * - * \note H5Literate_by_name1() assumes that the membership of the group being - * iterated over remains unchanged through the iteration; if any of the - * links in the group change during the iteration, the function’s - * behavior is undefined. Note, however, that objects pointed to by the - * links can be modified. - * * \note H5Literate_by_name1() is the same as H5Giterate(), except that * H5Giterate() always proceeds in lexicographic order. * @@ -2027,10 +1872,10 @@ H5_DLL herr_t H5Lvisit1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order * The group serving as the root of the iteration is specified by the * \p loc_id / \p group_name parameter pair. \p loc_id specifies a * file or group; group_name specifies either a group in the file - * (with an absolute name based in the file’s root group) or a group + * (with an absolute name based in the file's root group) or a group * relative to \p loc_id. If \p loc_id fully specifies the group that * is to serve as the root of the iteration, group_name should be '.' - * (a dot). (Note that when \p loc_id fully specifies the the group + * (a dot). (Note that when \p loc_id fully specifies the group * that is to serve as the root of the iteration, the user may wish to * consider using H5Lvisit1() instead of H5Lvisit_by_name1().) * @@ -2040,7 +1885,7 @@ H5_DLL herr_t H5Lvisit1(hid_t grp_id, H5_index_t idx_type, H5_iter_order_t order * \p idx_type specifies the index to be used. If the links have not * been indexed by the index type, they will first be sorted by that * index then the iteration will begin; if the links have been so - * indexed, the sorting step will be unnecesary, so the iteration may + * indexed, the sorting step will be unnecessary, so the iteration may * begin more quickly. Valid values include the following: * \indexes * diff --git a/libs/windows/include/H5MMpublic.h b/libs/windows/include/H5MMpublic.h index 70ac644..62172c9 100644 --- a/libs/windows/include/H5MMpublic.h +++ b/libs/windows/include/H5MMpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -14,8 +13,6 @@ /*------------------------------------------------------------------------- * * Created: H5MMpublic.h - * Jul 10 1997 - * Robb Matzke * * Purpose: Public declarations for the H5MM (memory management) * package. @@ -25,8 +22,7 @@ #ifndef H5MMpublic_H #define H5MMpublic_H -/* Public headers needed by this file */ -#include "H5public.h" +#include "H5public.h" /* Generic Functions */ /* These typedefs are currently used for VL datatype allocation/freeing */ //! @@ -37,11 +33,4 @@ typedef void *(*H5MM_allocate_t)(size_t size, void *alloc_info); typedef void (*H5MM_free_t)(void *mem, void *free_info); //! -#ifdef __cplusplus -extern "C" { -#endif - -#ifdef __cplusplus -} -#endif #endif /* H5MMpublic_H */ diff --git a/libs/windows/include/H5Mpublic.h b/libs/windows/include/H5Mpublic.h index f645bc9..48625a5 100644 --- a/libs/windows/include/H5Mpublic.h +++ b/libs/windows/include/H5Mpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -20,11 +19,12 @@ #ifndef H5Mpublic_H #define H5Mpublic_H -/* System headers needed by this file */ +#include "H5public.h" /* Generic Functions */ +#include "H5Ipublic.h" /* Identifiers */ +#include "H5VLpublic.h" /* Virtual Object Layer */ -/* Public headers needed by this file */ -#include "H5public.h" -#include "H5Ipublic.h" +/* Exposes VOL connector types, so it needs the connector header */ +#include "H5VLconnector.h" /*****************/ /* Public Macros */ @@ -68,6 +68,115 @@ typedef enum H5VL_map_specific_t { typedef herr_t (*H5M_iterate_t)(hid_t map_id, const void *key, void *op_data); //! +/* Parameters for map operations */ +typedef union H5VL_map_args_t { + /* H5VL_MAP_CREATE */ + struct { + H5VL_loc_params_t loc_params; /* Location parameters for object */ + const char *name; /* Name of new map object */ + hid_t lcpl_id; /* Link creation property list for map */ + hid_t key_type_id; /* Datatype for map keys */ + hid_t val_type_id; /* Datatype for map values */ + hid_t mcpl_id; /* Map creation property list */ + hid_t mapl_id; /* Map access property list */ + void *map; /* Pointer to newly created map object (OUT) */ + } create; + + /* H5VL_MAP_OPEN */ + struct { + H5VL_loc_params_t loc_params; /* Location parameters for object */ + const char *name; /* Name of new map object */ + hid_t mapl_id; /* Map access property list */ + void *map; /* Pointer to newly created map object (OUT) */ + } open; + + /* H5VL_MAP_GET_VAL */ + struct { + hid_t key_mem_type_id; /* Memory datatype for key */ + const void *key; /* Pointer to key */ + hid_t value_mem_type_id; /* Memory datatype for value */ + void *value; /* Buffer for value (OUT) */ + } get_val; + + /* H5VL_MAP_EXISTS */ + struct { + hid_t key_mem_type_id; /* Memory datatype for key */ + const void *key; /* Pointer to key */ + hbool_t exists; /* Flag indicating whether key exists in map (OUT) */ + } exists; + + /* H5VL_MAP_PUT */ + struct { + hid_t key_mem_type_id; /* Memory datatype for key */ + const void *key; /* Pointer to key */ + hid_t value_mem_type_id; /* Memory datatype for value */ + const void *value; /* Pointer to value */ + } put; + + /* H5VL_MAP_GET */ + struct { + H5VL_map_get_t get_type; /* 'get' operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_MAP_GET_MAPL */ + struct { + hid_t mapl_id; /* Map access property list ID (OUT) */ + } get_mapl; + + /* H5VL_MAP_GET_MCPL */ + struct { + hid_t mcpl_id; /* Map creation property list ID (OUT) */ + } get_mcpl; + + /* H5VL_MAP_GET_KEY_TYPE */ + struct { + hid_t type_id; /* Datatype ID for map's keys (OUT) */ + } get_key_type; + + /* H5VL_MAP_GET_VAL_TYPE */ + struct { + hid_t type_id; /* Datatype ID for map's values (OUT) */ + } get_val_type; + + /* H5VL_MAP_GET_COUNT */ + struct { + hsize_t count; /* # of KV pairs in map (OUT) */ + } get_count; + } args; + } get; + + /* H5VL_MAP_SPECIFIC */ + struct { + H5VL_map_specific_t specific_type; /* 'specific' operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_MAP_ITER */ + struct { + H5VL_loc_params_t loc_params; /* Location parameters for object */ + hsize_t idx; /* Start/end iteration index (IN/OUT) */ + hid_t key_mem_type_id; /* Memory datatype for key */ + H5M_iterate_t op; /* Iteration callback routine */ + void *op_data; /* Pointer to callback context */ + } iterate; + + /* H5VL_MAP_DELETE */ + struct { + H5VL_loc_params_t loc_params; /* Location parameters for object */ + hid_t key_mem_type_id; /* Memory datatype for key */ + const void *key; /* Pointer to key */ + } del; + } args; + } specific; + + /* H5VL_MAP_OPTIONAL */ + /* Unused */ + + /* H5VL_MAP_CLOSE */ + /* No args */ +} H5VL_map_args_t; + /********************/ /* Public Variables */ /********************/ @@ -102,7 +211,7 @@ extern "C" { * \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 + * loc_id specifies the location to create the map object and \p * name specifies the name of the link to the map object relative to * \p loc_id. * @@ -111,6 +220,19 @@ extern "C" { */ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Mcreate_async(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); +#endif /** * \ingroup H5M @@ -139,10 +261,21 @@ H5_DLL hid_t H5Mcreate_anon(hid_t loc_id, hid_t key_type_id, hid_t val_type_id, * H5Mclose() when the application is not longer interested in * accessing it. * - * \since 1.13.0 + * \since 1.12.0 * */ H5_DLL hid_t H5Mopen(hid_t loc_id, const char *name, hid_t mapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mopen} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Mopen_async(hid_t loc_id, const char *name, hid_t mapl_id, hid_t es_id); +#endif /** * \ingroup H5M @@ -162,6 +295,17 @@ H5_DLL hid_t H5Mopen(hid_t loc_id, const char *name, hid_t mapl_id); * */ H5_DLL herr_t H5Mclose(hid_t map_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Mclose} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Mclose_async(hid_t map_id, hid_t es_id); +#endif /** * \ingroup H5M @@ -208,7 +352,10 @@ H5_DLL hid_t H5Mget_val_type(hid_t map_id); * \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 + * The creation property list identifier should be released with + * H5Pclose() to prevent resource leaks. + * + * \since 1.12.0 * */ H5_DLL hid_t H5Mget_create_plist(hid_t map_id); @@ -277,6 +424,19 @@ H5_DLL herr_t H5Mget_count(hid_t map_id, hsize_t *count, hid_t dxpl_id); */ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Mput_async(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); +#endif /** * \ingroup H5M @@ -310,6 +470,19 @@ H5_DLL herr_t H5Mput(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t */ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Mget_async(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); +#endif /** * \ingroup H5M @@ -369,6 +542,9 @@ H5_DLL herr_t H5Mexists(hid_t map_id, hid_t key_mem_type_id, const void *key, hb * * Any further options can be specified through the property list \p dxpl_id. * + * \warning Adding or removing key-value pairs to the map during iteration + * will lead to undefined behavior. + * * \since 1.12.0 * */ @@ -410,6 +586,9 @@ H5_DLL herr_t H5Miterate(hid_t map_id, hsize_t *idx, hid_t key_mem_type_id, H5M_ * * Any further options can be specified through the property list \p dxpl_id. * + * \warning Adding or removing key-value pairs to the map during iteration + * will lead to undefined behavior. + * * \since 1.12.0 * */ @@ -440,6 +619,27 @@ H5_DLL herr_t H5Miterate_by_name(hid_t loc_id, const char *map_name, hsize_t *id */ H5_DLL herr_t H5Mdelete(hid_t map_id, hid_t key_mem_type_id, const void *key, hid_t dxpl_id); +/// \cond DEV +/* API Wrappers for async routines */ +/* (Must be defined _after_ the function prototype) */ +/* (And must only defined when included in application code, not the library) */ +#ifndef H5M_MODULE +#define H5Mcreate_async(...) H5Mcreate_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Mopen_async(...) H5Mopen_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Mclose_async(...) H5Mclose_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Mput_async(...) H5Mput_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Mget_async(...) H5Mget_async(__FILE__, __func__, __LINE__, __VA_ARGS__) + +/* Define "wrapper" versions of function calls, to allow compile-time values to + * be passed in by language wrapper or library layer on top of HDF5. */ +#define H5Mcreate_async_wrap H5_NO_EXPAND(H5Mcreate_async) +#define H5Mopen_async_wrap H5_NO_EXPAND(H5Mopen_async) +#define H5Mclose_async_wrap H5_NO_EXPAND(H5Mclose_async) +#define H5Mput_async_wrap H5_NO_EXPAND(H5Mput_async) +#define H5Mget_async_wrap H5_NO_EXPAND(H5Mget_async) +#endif /* H5M_MODULE */ +/// \endcond + /* Symbols defined for compatibility with previous versions of the HDF5 API. * * Use of these symbols is deprecated. diff --git a/libs/windows/include/H5Object.h b/libs/windows/include/H5Object.h index bc2f14a..1e93c0c 100644 --- a/libs/windows/include/H5Object.h +++ b/libs/windows/include/H5Object.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -50,16 +49,16 @@ typedef int (*visit_operator_t)(H5Object &obj, const H5std_string attr_name, con class UserData4Aiterate { public: attr_operator_t op; - void * opData; - H5Object * location; // Consider changing to H5Location + void *opData; + H5Object *location; // Consider changing to H5Location }; // User data for visit iteration class UserData4Visit { public: visit_operator_t op; - void * opData; - H5Object * obj; + void *opData; + H5Object *obj; }; class H5_DLLCPP H5Object : public H5Location { @@ -106,7 +105,7 @@ class H5_DLLCPP H5Object : public H5Location { void removeAttr(const H5std_string &name) const; // Returns an identifier. - virtual hid_t getId() const H5_OVERRIDE = 0; + virtual hid_t getId() const override = 0; // Gets the name of this HDF5 object, i.e., Group, DataSet, or // DataType. @@ -122,10 +121,10 @@ class H5_DLLCPP H5Object : public H5Location { // Sets the identifier of this object to a new value. - this one // doesn't increment reference count - virtual void p_setId(const hid_t new_id) H5_OVERRIDE = 0; + virtual void p_setId(const hid_t new_id) override = 0; // Noop destructor. - virtual ~H5Object() H5_OVERRIDE; + virtual ~H5Object() override; #endif // DOXYGEN_SHOULD_SKIP_THIS diff --git a/libs/windows/include/H5OcreatProp.h b/libs/windows/include/H5OcreatProp.h index 7f6d411..6d752ed 100644 --- a/libs/windows/include/H5OcreatProp.h +++ b/libs/windows/include/H5OcreatProp.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -44,7 +43,7 @@ class H5_DLLCPP ObjCreatPropList : public PropList { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("ObjCreatPropList"); } @@ -57,7 +56,7 @@ class H5_DLLCPP ObjCreatPropList : public PropList { ObjCreatPropList(const hid_t plist_id); // Noop destructor - virtual ~ObjCreatPropList(); + virtual ~ObjCreatPropList() override; #ifndef DOXYGEN_SHOULD_SKIP_THIS diff --git a/libs/windows/include/H5Opublic.h b/libs/windows/include/H5Opublic.h index 3c44421..f35bdd0 100644 --- a/libs/windows/include/H5Opublic.h +++ b/libs/windows/include/H5Opublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -14,35 +13,31 @@ /*------------------------------------------------------------------------- * * Created: H5Opublic.h - * Aug 5 1997 - * Robb Matzke * * Purpose: Public declarations for the H5O (object header) - * package. + * package * *------------------------------------------------------------------------- */ #ifndef H5Opublic_H #define H5Opublic_H -/* Public headers needed by this file */ -#include "H5public.h" /* Generic Functions */ -#include "H5Ipublic.h" /* IDs */ -#include "H5Lpublic.h" /* Links */ +#include "H5public.h" /* Generic Functions */ +#include "H5Ipublic.h" /* Identifiers */ /*****************/ /* Public Macros */ /*****************/ /* Flags for object copy (H5Ocopy) */ -#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /* Copy only immediate members */ -#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /* Expand soft links into new objects */ -#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /* Expand external links into new objects */ -#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /* Copy objects that are pointed by references */ -#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /* Copy object without copying attributes */ -#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /* Copy NULL messages (empty space) */ -#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /* Merge committed datatypes in dest file */ -#define H5O_COPY_ALL (0x007Fu) /* All object copying flags (for internal checking) */ +#define H5O_COPY_SHALLOW_HIERARCHY_FLAG (0x0001u) /**< Copy only immediate members */ +#define H5O_COPY_EXPAND_SOFT_LINK_FLAG (0x0002u) /**< Expand soft links into new objects */ +#define H5O_COPY_EXPAND_EXT_LINK_FLAG (0x0004u) /**< Expand external links into new objects */ +#define H5O_COPY_EXPAND_REFERENCE_FLAG (0x0008u) /**< Copy objects that are pointed by references */ +#define H5O_COPY_WITHOUT_ATTR_FLAG (0x0010u) /**< Copy object without copying attributes */ +#define H5O_COPY_PRESERVE_NULL_FLAG (0x0020u) /**< Copy NULL messages (empty space) */ +#define H5O_COPY_MERGE_COMMITTED_DTYPE_FLAG (0x0040u) /**< Merge committed datatypes in dest file */ +#define H5O_COPY_ALL (0x007Fu) /**< All object copying flags (for internal checking) */ /* Flags for shared message indexes. * Pass these flags in using the mesg_type_flags parameter in @@ -51,25 +46,27 @@ * but we need to assign each kind of message to a different bit so that * one index can hold multiple types.) */ -#define H5O_SHMESG_NONE_FLAG 0x0000 /* No shared messages */ -#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /* Simple Dataspace Message. */ -#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /* Datatype Message. */ -#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /* Fill Value Message. */ -#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /* Filter pipeline message. */ -#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /* Attribute Message. */ +#define H5O_SHMESG_NONE_FLAG 0x0000 /**< No shared messages */ +#define H5O_SHMESG_SDSPACE_FLAG ((unsigned)1 << 0x0001) /**< Simple Dataspace Message. */ +#define H5O_SHMESG_DTYPE_FLAG ((unsigned)1 << 0x0003) /**< Datatype Message. */ +#define H5O_SHMESG_FILL_FLAG ((unsigned)1 << 0x0005) /**< Fill Value Message. */ +#define H5O_SHMESG_PLINE_FLAG ((unsigned)1 << 0x000b) /**< Filter pipeline message. */ +#define H5O_SHMESG_ATTR_FLAG ((unsigned)1 << 0x000c) /**< Attribute Message. */ #define H5O_SHMESG_ALL_FLAG \ (H5O_SHMESG_SDSPACE_FLAG | H5O_SHMESG_DTYPE_FLAG | H5O_SHMESG_FILL_FLAG | H5O_SHMESG_PLINE_FLAG | \ H5O_SHMESG_ATTR_FLAG) +/* clang-format off */ /* Object header status flag definitions */ -#define H5O_HDR_CHUNK0_SIZE 0x03 /* 2-bit field indicating # of bytes to store the size of chunk 0's data */ -#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /* Attribute creation order is tracked */ -#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /* Attribute creation order has index */ -#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /* Non-default attribute storage phase change values stored */ -#define H5O_HDR_STORE_TIMES 0x20 /* Store access, modification, change & birth times for object */ +#define H5O_HDR_CHUNK0_SIZE 0x03 /**< 2-bit field indicating # of bytes to store the size of chunk 0's data */ +#define H5O_HDR_ATTR_CRT_ORDER_TRACKED 0x04 /**< Attribute creation order is tracked */ +#define H5O_HDR_ATTR_CRT_ORDER_INDEXED 0x08 /**< Attribute creation order has index */ +#define H5O_HDR_ATTR_STORE_PHASE_CHANGE 0x10 /**< Non-default attribute storage phase change values stored */ +#define H5O_HDR_STORE_TIMES 0x20 /**< Store access, modification, change & birth times for object */ #define H5O_HDR_ALL_FLAGS \ (H5O_HDR_CHUNK0_SIZE | H5O_HDR_ATTR_CRT_ORDER_TRACKED | H5O_HDR_ATTR_CRT_ORDER_INDEXED | \ H5O_HDR_ATTR_STORE_PHASE_CHANGE | H5O_HDR_STORE_TIMES) +/* clang-format on */ /* Maximum shared message values. Number of indexes is 8 to allow room to add * new types of messages. @@ -78,26 +75,26 @@ #define H5O_SHMESG_MAX_LIST_SIZE 5000 /* Flags for H5Oget_info. - * Theses flags determine which fields will be filled in in the H5O_info_t + * These flags determine which fields will be filled in the H5O_info_t * struct. */ -#define H5O_INFO_BASIC 0x0001u /* Fill in the fileno, addr, type, and rc fields */ -#define H5O_INFO_TIME 0x0002u /* Fill in the atime, mtime, ctime, and btime fields */ -#define H5O_INFO_NUM_ATTRS 0x0004u /* Fill in the num_attrs field */ +#define H5O_INFO_BASIC 0x0001u /**< Fill in the fileno, addr, type, and rc fields */ +#define H5O_INFO_TIME 0x0002u /**< Fill in the atime, mtime, ctime, and btime fields */ +#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 \ref H5O_native_info_t struct. + * Flags for H5Oget_native_info(). These flags determine which fields will be + * filled in the \ref H5O_native_info_t struct. */ -#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_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) //! /* 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))) +#define H5O_IS_TOKEN_UNDEF(token) (!memcmp(&(token), &(H5O_TOKEN_UNDEF), sizeof(H5O_token_t))) /*******************/ /* Public Typedefs */ @@ -146,15 +143,15 @@ typedef struct H5O_hdr_info_t { * (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 */ - 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 */ + unsigned long fileno; /**< File number that object is located in */ + H5O_token_t token; /**< Token representing the object */ + 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; /**< Number of attributes attached to object */ } H5O_info2_t; //! @@ -165,11 +162,10 @@ typedef struct H5O_info2_t { */ typedef struct H5O_native_info_t { 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 */ - } meta_size; + } meta_size; /**< Extra metadata storage for obj & attributes */ } H5O_native_info_t; //! @@ -181,6 +177,17 @@ typedef uint32_t H5O_msg_crt_idx_t; //! /** * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (version 3) + * + * \param[in] obj Object that serves as the root of the iteration; + * the same value as the H5Ovisit3() \c obj_id parameter + * \param[in] name Name of object, relative to \p obj, being examined at current + * step of the iteration + * \param[out] info Information about that object + * \param[in,out] op_data User-defined pointer to data required by the application + * in processing the object; a pass-through of the \c op_data + * pointer provided with the H5Ovisit3() function call + * \return \herr_t_iter + * */ typedef herr_t (*H5O_iterate2_t)(hid_t obj, const char *name, const H5O_info2_t *info, void *op_data); //! @@ -235,7 +242,7 @@ extern "C" { * * H5Oopen() cannot be used to open a dataspace, attribute, property list, or file. * - * Once an object of unknown type has been opened with H5Oopen(), + * Once an object of an unknown type has been opened with H5Oopen(), * the type of that object can be determined by means of an H5Iget_type() call. * * \p loc_id may be a file, group, dataset, named datatype, or attribute. @@ -257,6 +264,17 @@ extern "C" { * */ H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Oopen} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Oopen_async(hid_t loc_id, const char *name, hid_t lapl_id, hid_t es_id); +#endif /** *------------------------------------------------------------------------- @@ -272,10 +290,6 @@ H5_DLL hid_t H5Oopen(hid_t loc_id, const char *name, hid_t lapl_id); * \details H5Oopen_by_token() opens an object specified by the object * identifier, \p loc_id and object token, \p token. * - * \par Example - * An example snippet from examples/h5_extlink.c: - * \snippet h5_extlink.c H5Open_by_token_snip - * * \since 1.12.0 * */ @@ -296,7 +310,7 @@ H5_DLL hid_t H5Oopen_by_token(hid_t loc_id, H5O_token_t token); * * \return \hid_tv{object} * - * \details H5Open_by_idx() opens the nth object in the group specified by \p loc_id + * \details H5Oopen_by_idx() opens the nth object in the group specified by \p loc_id * and \p group_name. * * \p loc_id specifies a location identifier. @@ -338,6 +352,19 @@ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Oopen_by_idx_async(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); +#endif /** *------------------------------------------------------------------------- @@ -353,7 +380,7 @@ H5_DLL hid_t H5Oopen_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx * the \p loc_id and \p name combination exists. * \return Returns 0 if the object pointed to by * the \p loc_id and \p name combination does not exist. - * \return Returns a negatvie value when the function fails. + * \return Returns a negative value when the function fails. * * \details H5Oexists_by_name() allows an application to determine whether * the link \p name in the group or file specified with \p loc_id @@ -377,22 +404,22 @@ H5_DLL hid_t H5Oopen_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx * where \c group1 is a member of the group specified by \c loc_id: * * \par - * - First use H5Lexists() to verify that a link named \c group1 exists. + * - First, use H5Lexists() to verify that a link named \c group1 exists. * - If \c group1 exists, use H5Oexists_by_name() to verify that the * link \c group1 resolves to an object. - * - If \c group1 exists, use H5Lexists() again, this time with name + * - If \c group1 exists, use H5Lexists() again, this time with the name * set to \c group1/group2, to verify that the link \c group2 exists * in \c group1. * - If the \c group2 link exists, use H5Oexists_by_name() to verify * that \c group1/group2 resolves to an object. - * - If \c group2 exists, use H5Lexists() again, this time with name + * - If \c group2 exists, use H5Lexists() again, this time with the name * set to \c group1/group2/softlink_to_group3, to verify that the * link \c softlink_to_group3 exists in \c group2. * - If the \c softlink_to_group3 link exists, use H5Oexists_by_name() * to verify that \c group1/group2/softlink_to_group3 resolves to * an object. * - If \c softlink_to_group3 exists, you can now safely use H5Lexists - * with name set to \c group1/group2/softlink_to_group3/datasetD to + * with the name set to \c group1/group2/softlink_to_group3/datasetD to * verify that the target link, \c datasetD, exists. * - And finally, if the link \c datasetD exists, use H5Oexists_by_name * to verify that \c group1/group2/softlink_to_group3/datasetD @@ -401,17 +428,17 @@ H5_DLL hid_t H5Oopen_by_idx(hid_t loc_id, const char *group_name, H5_index_t idx * \par * If the link to be verified is specified with an absolute path, * the same approach should be used, but starting with the first - * link in the file’s root group. For instance, if \c datasetD + * link in the file's root group. For instance, if \c datasetD * were in \c /group1/group2/softlink_to_group3, the first call to * H5Lexists() would have name set to \c /group1. * * \par - * Note that this is an outline and does not include all necessary + * Note that this is an outline and does not include all the necessary * details. Depending on circumstances, for example, an application * may need to verify the type of an object also. * * \warning \Bold{Failure Modes:} - * \warning If \p loc_id and \p name both exist but the combination does not + * \warning If \p loc_id and \p name both exist, but the combination does not * resolve to an object, the function will return 0 (zero); * the function does not fail in this case. * \warning If either the location or the link specified by the \p loc_id @@ -445,28 +472,7 @@ H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id); * \return \herr_t * * \details H5Oget_info3() specifies an object by its identifier, \p loc_id , and - * retrieves the metadata describing that object in \p oinfo , an H5O_info2_t \c struct. - * - * The H5O_info2_t \c struct is defined in H5Opublic.h as follows : - * \snippet this H5O_info2_t_snip - * - * Note the following about H5O_info2_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - * The H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by H5O_type_t. + * retrieves the metadata describing that object in \p oinfo. * * The \p fields parameter contains flags to determine which fields will be filled in * the H5O_info2_t \c struct returned in \p oinfo. @@ -482,7 +488,7 @@ H5_DLL htri_t H5Oexists_by_name(hid_t loc_id, const char *name, hid_t lapl_id); * \note If you are iterating through a lot of different objects to * retrieve information via the H5Oget_info() family of routines, * you may see memory building up. This can be due to memory - * allocation for metadata such as object headers and messages + * allocation for metadata, such as object headers and messages, * when the iterated objects are put into the metadata cache. * \note * If the memory buildup is not desirable, you can configure a @@ -504,40 +510,17 @@ H5_DLL herr_t H5Oget_info3(hid_t loc_id, H5O_info2_t *oinfo, unsigned fields); * location and relative name * * \fgdta_loc_obj_id{loc_id} - * \param[in] name Name of group, relative to \p loc_id + * \param[in] name Name of object, relative to \p loc_id * \param[out] oinfo Buffer in which to return object information * \param[in] fields Flags specifying the fields to include in \p oinfo * \lapl_id * * \return \herr_t * - * \details H5Oget_info_by_name3() specifies an object’s location and name, + * \details H5Oget_info_by_name3() specifies an object's location and name, * \p loc_id and \p name, respectively, and retrieves the metadata * describing that object in \p oinfo, an H5O_info2_t struct. * - * \p oinfo, in which the object information is returned, is a \c struct of - * type H5O_info2_t, which is defined in H5Opublic.h in the HDF5 source code: - * - * \snippet this H5O_info2_t_snip - * - * Note the following about H5O_info2_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - * The H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by H5O_type_t. - * * The \p fields parameter contains flags to determine which fields will be filled in * the H5O_info2_t \c struct returned in \p oinfo. * These flags are defined in the H5Opublic.h file: @@ -556,6 +539,19 @@ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Oget_info_by_name_async(hid_t loc_id, const char *name, H5O_info2_t *oinfo /*out*/, + unsigned fields, hid_t lapl_id, hid_t es_id); +#endif /** *------------------------------------------------------------------------- @@ -579,40 +575,12 @@ H5_DLL herr_t H5Oget_info_by_name3(hid_t loc_id, const char *name, H5O_info2_t * * object in the \c struct \p oinfo, as specified by the location, * \p loc_id, group name, \p group_name, the index by which objects * in that group are tracked, \p idx_type, the order by which the - * index is to be traversed, \p order, and an object’s position + * index is to be traversed, \p order, and an object's position * \p n within that index. * * If \p loc_id fully specifies the group in which the object resides, * \p group_name can be a dot (\c .). * - * \p idx_type is of type #H5_index_t, defined in H5public.h as: - * \snippet H5public.h H5_index_t_snip - * - * \p order is of type #H5_iter_order_t defined in H5public.h as: - * \snippet H5public.h H5_iter_order_t_snip - * - * \p oinfo, in which the object information is returned, is a \c struct of - * type H5O_info2_t, which is defined in H5Opublic.h in the HDF5 source code: - * \snippet this H5O_info2_t_snip - * - * Note the following about H5O_info2_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - * H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The #H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by #H5O_type_t. - * * The \p fields parameter contains flags to determine which fields will be filled in * the H5O_info2_t \c struct returned in \p oinfo. * These flags are defined in the H5Opublic.h file: @@ -645,11 +613,7 @@ H5_DLL herr_t H5Oget_info_by_idx3(hid_t loc_id, const char *group_name, H5_index * \return \herr_t * * \details H5Oget_native_info() retrieves the native file format information for an object - * specified by \p loc_id. The information is retrieved into the - * buffer specified by \p oinfo, which is defined as a \c struct of - * type H5O_native_info_t in H5Opublic.h: - * - * \snippet this H5O_native_info_t_snip + * specified by \p loc_id. * * The \p fields parameter indicates which fields to fill in * H5O_native_info_t. Possible values defined in H5Opublic.h are: @@ -680,12 +644,9 @@ H5_DLL herr_t H5Oget_native_info(hid_t loc_id, H5O_native_info_t *oinfo, unsigne * * \return \herr_t * - * \details H5Oget_native_info_by_name() retrieves the native file format information for an object - * specified by \p loc_id and the name \p name. The information is - * retrieved into the buffer specified by \p oinfo, which is defined - * as a \c struct of type H5O_native_info_t in H5Opublic.h: - * - * \snippet this H5O_native_info_t_snip + * \details H5Oget_native_info_by_name() retrieves the native file format + * information for an object specified by \p loc_id and the name \p + * name. * * The \p fields parameter which fields to fill in H5O_native_info_t. * Possible values defined in H5Opublic.h are: @@ -724,16 +685,7 @@ H5_DLL herr_t H5Oget_native_info_by_name(hid_t loc_id, const char *name, H5O_nat * specified by \p loc_id, group name, \p group_name, the index by which * objects in the group are tracked, \p idx_type, the order by which * the index is to be traversed, \p order , and an object's position - * \p n within that index. The information is retrieved into the - * buffer specified by \p oinfo, which is defined as a \c struct of - * type H5O_native_info_t in H5Opublic.h: - * \snippet this H5O_native_info_t_snip - * - * \p idx_type is of type #H5_index_t, defined in H5public.h as: - * \snippet H5public.h H5_index_t_snip - * - * \p order is of type #H5_iter_order_t defined in H5public.h as: - * \snippet H5public.h H5_iter_order_t_snip + * \p n within that index. * * The \p fields parameter indicates which fields to fill in H5O_native_info_t. * Possible values defined in H5Opublic.h are: @@ -766,7 +718,7 @@ H5_DLL herr_t H5Oget_native_info_by_idx(hid_t loc_id, const char *group_name, H5 * * \details H5Olink() creates a new hard link to an object in an HDF5 file. * \p new_loc_id and \p \p new_link_name specify the location and name of the - * new link while \p object_id identifies the object that the link + * new link, while \p object_id identifies the object that the link * points to. * * H5Olink() is designed for two purposes: @@ -793,7 +745,7 @@ H5_DLL herr_t H5Oget_native_info_by_idx(hid_t loc_id, const char *group_name, H5 * hid_t lcpl_id = H5Pcreate(H5P_LINK_CREATE); * * // Sets "create missing intermediate groups" property in that LCPL. - * int status = H5Pset_create_intermediate_group(lcpl_id, TRUE); + * int status = H5Pset_create_intermediate_group(lcpl_id, true); * * // Creates a group without linking it into the file structure. * hid_t gid = H5Gcreate_anon(file_id, H5P_DEFAULT, H5P_DEFAULT); @@ -833,12 +785,12 @@ H5_DLL herr_t H5Olink(hid_t obj_id, hid_t new_loc_id, const char *new_name, hid_ * an object by address is added. When the link is deleted, * H5Odecr_refcount() should be used. * - * An object’s reference count is the number of hard links in the + * An object's reference count is the number of hard links in the * file that point to that object. See the “Programming Model” - * section of the HDF5 Groups chapter in the -- HDF5 User’s Guide - * for a more complete discussion of reference counts. + * section of the HDF5 Groups chapter in the -- \ref UG + * for a complete discussion of reference counts. * - * If a user application needs to determine an object’s reference + * If a user application needs to determine an object's reference * count, an H5Oget_info() call is required; the reference count * is returned in the \c rc field of the #H5O_info_t \c struct. * @@ -868,12 +820,12 @@ H5_DLL herr_t H5Oincr_refcount(hid_t object_id); * an object by address is deleted. In general, H5Oincr_refcount() will have * been used previously, when the link was created. * - * An object’s reference count is the number of hard links in the + * An object's reference count is the number of hard links in the * file that point to that object. See the “Programming Model” - * section of the HDF5 Groups chapter in the HDF5 User’s Guide + * section of the HDF5 Groups chapter in the \ref UG * for a more complete discussion of reference counts. * - * If a user application needs to determine an object’s reference + * If a user application needs to determine an object's reference * count, an H5Oget_info() call is required; the reference count * is returned in the \c rc field of the #H5O_info_t \c struct. * @@ -911,13 +863,13 @@ H5_DLL herr_t H5Odecr_refcount(hid_t object_id); * The destination location, as specified in dst_loc_id, may * be a group in the current file or a location in a different * file. If dst_loc_id is a file identifier, the copy will be - * placed in that file’s root group. + * placed in that file's root group. * * The copy will be created with the path specified in \p dst_name, * which must not pre-exist in the destination location. If * \p dst_name already exists at the location \p dst_loc_id, * H5Ocopy() will fail. If \p dst_name is an absolute path, - * the copy will be created relative to the file’s root group. + * the copy will be created relative to the file's root group. * * The copy of the object is created with the property lists * specified by \p ocpypl_id and \p lcpl_id. #H5P_DEFAULT can be passed @@ -979,6 +931,19 @@ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Ocopy_async(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); +#endif /** *------------------------------------------------------------------------- @@ -996,7 +961,7 @@ H5_DLL herr_t H5Ocopy(hid_t src_loc_id, const char *src_name, hid_t dst_loc_id, * is overwritten. * * The target object is specified by an identifier, \p obj_id. - * If \p comment is the empty string or a null pointer, any existing + * If \p comment is an empty string or a null pointer, any existing * comment message is removed from the object. * * Comments should be relatively short, null-terminated, ASCII strings. @@ -1038,10 +1003,10 @@ H5_DLL herr_t H5Oset_comment(hid_t obj_id, const char *comment); * \p name can be one of the following: * * - The name of the object specified as a path relative to \p loc_id - * - An absolute name of the object, starting from \c /, the file’s root group + * - An absolute name of the object, starting from \c /, the file's root group * - A dot (\c .), if \p loc_id fully specifies the object * - * If \p comment is the empty string or a null pointer, any existing + * If \p comment is an empty string or a null pointer, any existing * comment message is removed from the object. * * Comments should be relatively short, null-terminated, ASCII strings. @@ -1095,7 +1060,7 @@ H5_DLL herr_t H5Oset_comment_by_name(hid_t loc_id, const char *name, const char * only \p bufsize bytes of the comment, without a \c NULL terminator, * are returned in \p comment. * - * If an object does not have a comment, the empty string is + * If an object does not have a comment, an empty string is * returned in \p comment. * * \version 1.8.11 Fortran subroutine introduced in this release. @@ -1130,7 +1095,7 @@ H5_DLL ssize_t H5Oget_comment(hid_t obj_id, char *comment, size_t bufsize); * \p name can be one of the following: * * - The name of the object relative to \p loc_id - * - An absolute name of the object, starting from \c /, the file’s root group + * - An absolute name of the object, starting from \c /, the file's root group * - A dot (\c .), if \p loc_id fully specifies the object * * The size in bytes of the comment, including the \c NULL terminator, @@ -1143,7 +1108,7 @@ H5_DLL ssize_t H5Oget_comment(hid_t obj_id, char *comment, size_t bufsize); * only \p bufsize bytes of the comment, without a \c NULL terminator, * are returned in \p comment. * - * If an object does not have a comment, the empty string is + * If an object does not have a comment, an empty string is * returned in \p comment. * * \p lapl_id contains a link access property list identifier. A @@ -1192,7 +1157,7 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * * If \p obj_id is a group identifier, that group serves as the * root of a recursive iteration. If \p obj_id is a file identifier, - * that file’s root group serves as the root of the recursive + * that file's root group serves as the root of the recursive * iteration. If \p obj_id is an attribute identifier, * then the object where the attribute is attached will be iterated. * If \p obj_id is any other type of object, such as a dataset or @@ -1205,81 +1170,23 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes - * + * unnecessary, so the iteration may begin more quickly. + * Note that the index type passed in \p idx_type is a * best effort setting. If the application passes in * a value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * name order. (Name order is the native order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate2_t_snip - * - * The parameters of this callback function have the following values - * or meanings: - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
    \c objObject that serves as root of the iteration; - * same value as the H5Ovisit() \p obj_id parameter
    \c nameName of object, relative to \c obj, being examined at - * current step of the iteration
    \c infoH5O_info2_t \c struct containing information - * regarding that object
    \c op_dataUser-defined pointer to data required by the application in - * processing the object; a pass-through of the \c op_data pointer - * provided with the H5Ovisit() function call
    - * - * The H5O_info2_t \c struct is defined in H5Opublic.h as follows: - * \snippet this H5O_info2_t_snip - * - * H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The #H5O_type_t enum indicates the object type and is - * defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p obj_id - * refers only to the types specified by #H5O_type_t. - * - * The return values from an operator are: - * - Zero causes the visit iterator to continue, returning zero when all - * group members have been processed. - * - A positive value causes the visit iterator to immediately return that - * positive value, indicating short-circuit success. - * - A negative value causes the visit iterator to immediately return that - * value, indicating failure. + * along the index specified in \p idx_type. * * The H5Ovisit3() \p op_data parameter is a user-defined pointer to the data * required to process objects in the course of the iteration. This pointer * is passed back to each step of the iteration in the callback - * function’s \p op_data parameter. + * function's \p op_data parameter. * * The \p fields parameter contains flags to determine which fields will * be retrieved by the \p op callback function. These flags are defined @@ -1298,24 +1205,6 @@ H5_DLL ssize_t H5Oget_comment_by_name(hid_t loc_id, const char *name, char *comm * group change during the iteration, the resulting behavior * is undefined. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \par Example * An example snippet from test/links.c: * \snippet links.c H5Ovisit3_snip @@ -1366,7 +1255,7 @@ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a file or an object in a file; if \p loc_id is an attribute identifier, * the object where the attribute is attached will be used. * \p obj_name specifies either an object in the file (with an absolute - * name based in the file’s root group) or an object name relative + * name based on the file's root group) or an object name relative * to \p loc_id. If \p loc_id fully specifies the object that is to serve * as the root of the iteration, \p obj_name should be '\c .' (a dot). * (Note that when \p loc_id fully specifies the object that is to serve @@ -1380,68 +1269,23 @@ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * best effort setting. If the application passes in a * value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * name order. (Name order is the native order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate2_t_snip - * - * The parameters of this callback function have the following - * values or meanings: - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
    \c objObject that serves as root of the iteration
    \c nameName of object, relative to \c obj, being examined at - * current step of the iteration
    \c infoH5O_info2_t \c struct containing information - * regarding that object
    \c op_dataUser-defined pointer to data required by the application in - * processing the object
    - * - * The H5O_info2_t \c struct is defined in H5Opublic.h as follows: - * \snippet this H5O_info2_t_snip - * - * H5O_token_t is defined in H5public.h as follows: - * \snippet H5public.h H5O_token_t_snip - * - * The #H5O_type_t enum indicates the object type and is - * defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip + * along the index specified in \p idx_type. * * The H5Ovisit_by_name3() \p op_data parameter is a user-defined * pointer to the data required to process objects in the course * of the iteration. This pointer is passed back to each step of - * the iteration in the callback function’s \p op_data parameter. + * the iteration in the callback function's \p op_data parameter. * * \p lapl_id is a link access property list. In the general case, * when default link access properties are acceptable, this can @@ -1464,24 +1308,6 @@ H5_DLL herr_t H5Ovisit3(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * in the file has been presented to the application for whatever * processing the application requires. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \par Example * An example snippet from test/links.c: * \snippet links.c H5Ovisit_by_name3_snip @@ -1518,6 +1344,17 @@ 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} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Oclose_async(hid_t object_id, hid_t es_id); +#endif /** *------------------------------------------------------------------------- @@ -1533,7 +1370,10 @@ H5_DLL herr_t H5Oclose(hid_t object_id); * flushed to disk without removing the data from the cache. * * The object associated with \p object_id can be any named object in an - * HDF5 file including a dataset, a group, or a committed datatype. + * HDF5 file, including a dataset, a group, or a committed datatype. + * + * \warning H5Oflush doesn't work correctly with parallel. It causes an assertion + * failure in metadata cache during H5Fclose(). * * \note HDF5 does not possess full control over buffering. H5Oflush() * flushes the internal HDF5 buffers and then asks the operating @@ -1541,32 +1381,27 @@ H5_DLL herr_t H5Oclose(hid_t object_id); * files. After that, the OS is responsible for ensuring that * the data is actually flushed to disk. * - * \par See Also: - * - H5Dflush() - * - H5Drefresh() - * - H5Oflush() - * - H5Grefresh() - * - H5Oflush() - * - H5Orefresh() - * - H5Tflush() - * - H5Trefresh() - * \par - * - \c H5DOappend() - * - H5Fstart_swmr_write() - * - H5Pget_append_flush() - * - H5Pget_object_flush_cb() - * - H5Pset_append_flush() - * - H5Pset_object_flush_cb() - * \par - * - H5Oare_mdc_flushes_disabled() - * - H5Odisable_mdc_flushes() - * - H5Oenable_mdc_flushes() + * \see H5Dflush(), H5Drefresh(), H5Oflush(), H5Grefresh(), H5Oflush(), + * H5Orefresh(), H5Tflush(), H5Trefresh() + * \see H5DOappend(), H5Fstart_swmr_write(), H5Pget_append_flush(), + * H5Pget_object_flush_cb(), H5Pset_append_flush(), H5Pset_object_flush_cb() + * \see H5Oare_mdc_flushes_disabled(), H5Odisable_mdc_flushes(), H5Oenable_mdc_flushes() * * \since 1.10.0 * */ H5_DLL herr_t H5Oflush(hid_t obj_id); - +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Oflush} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Oflush_async(hid_t obj_id, hid_t es_id); +#endif /** *------------------------------------------------------------------------- * \ingroup H5O @@ -1592,6 +1427,17 @@ H5_DLL herr_t H5Oflush(hid_t obj_id); * */ H5_DLL herr_t H5Orefresh(hid_t oid); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Orefresh} + */ +#ifndef H5_DOXYGEN +H5_DLL herr_t H5Orefresh_async(const char *app_file, const char *app_func, unsigned app_line, hid_t oid, + hid_t es_id); +#else +H5_DLL herr_t H5Orefresh_async(hid_t oid, hid_t es_id); +#endif /** *------------------------------------------------------------------------- @@ -1607,9 +1453,9 @@ H5_DLL herr_t H5Orefresh(hid_t oid); * * \details H5Odisable_mdc_flushes(), H5Oenable_mdc_flushes() and associated flush * functions can be used to control the flushing of entries from - * a file’s metadata cache. + * a file's metadata cache. * - * This function prevents an object’s or cache’s dirty metadata + * This function prevents an object's or cache's dirty metadata * entries from being flushed from the cache by the usual cache * eviction/flush policy. Instead, users must manually flush the * cache or entries for individual objects via the appropriate @@ -1619,21 +1465,17 @@ H5_DLL herr_t H5Orefresh(hid_t oid); * HDF5 object level (datasets, groups, committed datatypes) * and the entire metadata cache level. * - * \note HDF5 objects include datasets, groups, and committed datatypes. - * Only #hid_t identifiers that represent these objects can be passed to the function. - * \note Passing in a #hid_t identifier that represents any other HDF5 entity is - * considered an error. - * \note It is an error to pass an HDF5 file identifier - * (obtained from H5Fopen() or H5Fcreate()) - * to this function. - * \note Misuse of this function can cause the cache to exhaust - * available memory. - * \note Objects can be returned to the default automatic flush behavior - * with H5Oenable_mdc_flushes(). - * \note Flush prevention only pertains to new or dirty metadata entries. - * Clean entries can be evicted from the cache. - * \note Calling this function on an object that has already had flushes - * disabled will return an error. + * \note HDF5 objects include datasets, groups, and committed datatypes. Only + * #hid_t identifiers that represent these objects can be passed to the + * function. Passing in a #hid_t identifier that represents any other + * HDF5 entity is considered an error. It is an error to pass an HDF5 + * file identifier (obtained from H5Fopen() or H5Fcreate()) to this + * function. Misuse of this function can cause the cache to exhaust + * available memory. Objects can be returned to the default automatic + * flush behavior with H5Oenable_mdc_flushes(). Flush prevention only + * pertains to new or dirty metadata entries. Clean entries can be + * evicted from the cache. Calling this function on an object that has + * already had flushes disabled will return an error. * * \since 1.10.0 * @@ -1644,7 +1486,7 @@ H5_DLL herr_t H5Odisable_mdc_flushes(hid_t object_id); *------------------------------------------------------------------------- * \ingroup H5O * - * \brief Enables flushing of dirty metadata entries from a file’s metadata cache + * \brief Enables flushing of dirty metadata entries from a file's metadata cache * * \param[in] object_id Identifier of the object that will have flushes re-enabled; * may be a group, named datatype, or dataset identifier @@ -1653,9 +1495,9 @@ H5_DLL herr_t H5Odisable_mdc_flushes(hid_t object_id); * * \details H5Oenable_mdc_flushes(), H5Odisable_mdc_flushes() * and associated flush functions can be used to control the flushing - * of entries from a file’s metadata cache. + * of entries from a file's metadata cache. * - * This function allows an object or cache’s dirty metadata entries to be + * This function allows an object or cache's dirty metadata entries to be * flushed from the cache by the usual cache eviction/flush policy. * * Metadata cache entries can be controlled at both the individual HDF5 @@ -1663,28 +1505,18 @@ H5_DLL herr_t H5Odisable_mdc_flushes(hid_t object_id); * metadata cache level. * * - * \note HDF5 objects include datasets, groups, and committed datatypes. - * Only #hid_t identifiers that represent these objects can be - * passed to the function. - * - * \note Passing in a #hid_t identifier that represents any other HDF5 entity - * is considered an error. - * - * \note It is an error to pass an HDF5 file identifier - * (obtained from H5Fopen() or H5Fcreate()) - * to this function. - * - * \note Using this function on an object that has not had flushes disabled - * is considered an error. The state of an object can be determined - * with H5Oare_mdc_flushes_disabled(). - * - * \note An object will be returned to the default flush algorithm when it is closed. - * - * \note All objects will be returned to the default flush algorithm when - * the file is closed. - * - * \note An object’s entries will not necessarily be flushed as a result of - * calling this function. + * \note HDF5 objects include datasets, groups, and committed datatypes. Only + * #hid_t identifiers that represent these objects can be passed to the + * function. Passing in a #hid_t identifier that represents any other + * HDF5 entity is considered an error. It is an error to pass an HDF5 + * file identifier (obtained from H5Fopen() or H5Fcreate()) to this + * function. Using this function on an object that has not had flushes + * disabled is considered an error. The state of an object can be + * determined with H5Oare_mdc_flushes_disabled(). An object will be + * returned to the default flush algorithm when it is closed. All objects + * will be returned to the default flush algorithm when the file is + * closed. An object's entries will not necessarily be flushed as a + * result of calling this function. * * \since 1.10.0 * @@ -1710,7 +1542,7 @@ H5_DLL herr_t H5Oenable_mdc_flushes(hid_t object_id); * * The H5Oenable_mdc_flushes(), H5Odisable_mdc_flushes() and * associated flush functions can be used to control the flushing of - * entries from a file’s metadata cache. Metadata cache entries can be controlled + * entries from a file's metadata cache. Metadata cache entries can be controlled * at both the individual HDF5 object level (datasets, groups, * committed datatypes) and the entire metadata cache level. * @@ -1820,6 +1652,32 @@ H5_DLL herr_t H5Otoken_to_str(hid_t loc_id, const H5O_token_t *token, char **tok */ H5_DLL herr_t H5Otoken_from_str(hid_t loc_id, const char *token_str, H5O_token_t *token); +/// \cond DEV +/* API Wrappers for async routines */ +/* (Must be defined _after_ the function prototype) */ +/* (And must only defined when included in application code, not the library) */ +#ifndef H5O_MODULE +#define H5Oopen_async(...) H5Oopen_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Oopen_by_idx_async(...) H5Oopen_by_idx_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Oget_info_by_name_async(...) H5Oget_info_by_name_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Oclose_async(...) H5Oclose_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Oflush_async(...) H5Oflush_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Orefresh_async(...) H5Orefresh_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Ocopy_async(...) H5Ocopy_async(__FILE__, __func__, __LINE__, __VA_ARGS__) + +/* Define "wrapper" versions of function calls, to allow compile-time values to + * be passed in by language wrapper or library layer on top of HDF5. + */ +#define H5Oopen_async_wrap H5_NO_EXPAND(H5Oopen_async) +#define H5Oopen_by_idx_async_wrap H5_NO_EXPAND(H5Oopen_by_idx_async) +#define H5Oget_info_by_name_async_wrap H5_NO_EXPAND(H5Oget_info_by_name_async) +#define H5Oclose_async_wrap H5_NO_EXPAND(H5Oclose_async) +#define H5Oflush_async_wrap H5_NO_EXPAND(H5Oflush_async) +#define H5Orefresh_async_wrap H5_NO_EXPAND(H5Orefresh_async) +#define H5Ocopy_async_wrap H5_NO_EXPAND(H5Ocopy_async) +#endif +/// \endcond + /* The canonical 'undefined' token value */ #define H5O_TOKEN_UNDEF (H5OPEN H5O_TOKEN_UNDEF_g) H5_DLLVAR const H5O_token_t H5O_TOKEN_UNDEF_g; @@ -1833,8 +1691,8 @@ H5_DLLVAR const H5O_token_t H5O_TOKEN_UNDEF_g; /* Macros */ /* Deprecated flags for earlier versions of H5Oget_info* */ -#define H5O_INFO_HDR 0x0008u /* Fill in the hdr field */ -#define H5O_INFO_META_SIZE 0x0010u /* Fill in the meta_size field */ +#define H5O_INFO_HDR 0x0008u /**< Fill in the hdr field */ +#define H5O_INFO_META_SIZE 0x0010u /**< Fill in the meta_size field */ #undef H5O_INFO_ALL #define H5O_INFO_ALL (H5O_INFO_BASIC | H5O_INFO_TIME | H5O_INFO_NUM_ATTRS | H5O_INFO_HDR | H5O_INFO_META_SIZE) @@ -1867,7 +1725,7 @@ typedef struct H5O_info1_t { time_t mtime; /**< Modification time */ time_t ctime; /**< Change time */ time_t btime; /**< Birth time */ - hsize_t num_attrs; /**< # of attributes attached to object */ + hsize_t num_attrs; /**< Number of attributes attached to object */ H5O_hdr_info_t hdr; /**< Object header information */ /* Extra metadata storage for obj & attributes */ struct { @@ -1880,6 +1738,16 @@ typedef struct H5O_info1_t { //! /** * Prototype for H5Ovisit(), H5Ovisit_by_name() operator (versions 1 & 2) + * + * \param[in] obj Object that serves as the root of the iteration; + * the same value as the H5Ovisit1() \c obj_id parameter + * \param[in] name Name of object, relative to \p obj, being examined at current + * step of the iteration + * \param[out] info Information about that object + * \param[in,out] op_data User-defined pointer to data required by the application + * in processing the object + * \return \herr_t_iter + * */ typedef herr_t (*H5O_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t *info, void *op_data); //! @@ -1907,18 +1775,18 @@ typedef herr_t (*H5O_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t * * \p loc_id is a location identifier in the file. * - * The object’s address within the file, \p addr, is the byte offset of the first byte + * The object's address within the file, \p addr, is the byte offset of the first byte * of the object header from the beginning of the HDF5 file space, i.e., from the - * beginning of the super block (see the “HDF5 Storage Model” section of the The + * beginning of the superblock (see the “HDF5 Storage Model” section of the The * HDF5 Data Model and File Structure chapter of the HDF5 User's Guide.) * * \p addr can be obtained via either of two function calls. H5Gget_objinfo() returns - * the object’s address in the \c objno field of the H5G_stat_t \c struct; + * the object's address in the \c objno field of the H5G_stat_t \c struct; * H5Lget_info() returns the address in the \c address field of the #H5L_info_t \c struct. * * The address of the HDF5 file on a physical device has no effect on H5Oopen_by_addr(), * nor does the use of any file driver. As stated above, the object address is its - * offset within the HDF5 file; HDF5’s file drivers will transparently map this to an + * offset within the HDF5 file; HDF5's file drivers will transparently map this to an * address on a storage device. * * \warning This function must be used with care! @@ -1928,7 +1796,7 @@ typedef herr_t (*H5O_iterate1_t)(hid_t obj, const char *name, const H5O_info1_t * overcome by retrieving the object address with H5Gget_objinfo() or H5Lget_info() * immediately before calling H5Oopen_by_addr(). The immediacy of the operation can be * important; if time has elapsed and the object has been deleted from the file, - * the address will be invalid and file corruption can result. + * the address will be invalid, and file corruption can result. * * \version 1.8.4 Fortran subroutine added in this release. * @@ -1952,41 +1820,12 @@ H5_DLL hid_t H5Oopen_by_addr(hid_t loc_id, haddr_t addr); * the function H5Oget_info3() or the macro #H5Oget_info. * * \details H5Oget_info1() specifies an object by its identifier, \p loc_id , and - * retrieves the metadata describing that object in \p oinfo , - * defined as a \c struct of type H5O_info1_t : - * - * \snippet this H5O_info1_t_snip - * - * Note the following about H5O_info1_t : - * - Of the four time fields (\c atime, \c mtime, \c ctime, and \c btime) - * only \c ctime has been implemented. - * - The \c atime value is the last time the object was read or written. - * - The \c mtime value is the last time the raw data in the object was changed. - * - The \c ctime value is the last time the metadata for the object was changed. - * - The \c btime value is the time the object was created. - * - The fields nested in the \c meta_size field are for internal library use only. - * - * The #H5O_type_t \c enum indicates the object type and - * is defined in H5Opublic.h as follows: - * \snippet this H5O_type_t_snip - * - * Note that the object retrieved as indicated by \p loc_id - * refers only to the types specified by #H5O_type_t. - * - * An H5O_hdr_info_t \c struct holds object header metadata and is - * defined in H5Opublic.h as follows: - * \snippet this H5O_hdr_info_t_snip - * - * Valid values for the \c version field are \c H5O_VERSION_1 and \c H5O_VERSION_2. - * Version 2 of the object header is smaller and more efficient than version 1. - * - * Please be aware that the information held by H5O_hdr_info_t may only be useful to - * developers with extensive HDF5 experience. + * retrieves the metadata describing that object in \p oinfo. * * \note If you are iterating through a lot of different objects to * retrieve information via the H5Oget_info() family of routines, * you may see memory building up. This can be due to memory - * allocation for metadata such as object headers and messages + * allocation for metadata, such as object headers and messages, * when the iterated objects are put into the metadata cache. * \note * If the memory buildup is not desirable, you can configure a @@ -2020,7 +1859,7 @@ H5_DLL herr_t H5Oget_info1(hid_t loc_id, H5O_info1_t *oinfo); * by location and relative name * * \fgdta_loc_obj_id{loc_id} - * \param[in] name Name of group, relative to \p loc_id + * \param[in] name Name of object, relative to \p loc_id * \param[out] oinfo Buffer in which to return object information * \lapl_id * @@ -2029,7 +1868,7 @@ H5_DLL herr_t H5Oget_info1(hid_t loc_id, H5O_info1_t *oinfo); * \deprecated As of HDF5-1.12 this function has been deprecated in favor of * the function H5Oget_info_by_name2() or the macro #H5Oget_info_by_name. * - * \details H5Oget_info_by_name1() specifies an object’s location and name, \p loc_id + * \details H5Oget_info_by_name1() specifies an object's location and name, \p loc_id * and \p name, respectively, and retrieves the metadata describing that object * in \p oinfo, an H5O_info1_t \c struct. * @@ -2075,22 +1914,12 @@ H5_DLL herr_t H5Oget_info_by_name1(hid_t loc_id, const char *name, H5O_info1_t * * object in the \c struct \p oinfo, as specified by the location, * \p loc_id, group name, \p group_name, the index by which objects * in that group are tracked, \p idx_type, the order by which the - * index is to be traversed, \p order, and an object’s position + * index is to be traversed, \p order, and an object's position * \p n within that index. * * If \p loc_id fully specifies the group in which the object resides, * \p group_name can be a dot (\c .). * - * \p idx_type is of type #H5_index_t, defined in H5public.h as: - * \snippet H5public.h H5_index_t_snip - * - * \p order is of type #H5_iter_order_t defined in H5public.h as: - * \snippet H5public.h H5_iter_order_t_snip - * - * \p oinfo, in which the object information is returned, is a \c struct of - * type H5O_info1_t . - * \snippet this H5O_info1_t_snip - * * The link access property list, \c lapl_id, is not currently used; * it should be passed in as #H5P_DEFAULT. * @@ -2134,7 +1963,7 @@ H5_DLL herr_t H5Oget_info_by_idx1(hid_t loc_id, const char *group_name, H5_index * \note If you are iterating through a lot of different objects to * retrieve information via the H5Oget_info() family of routines, * you may see memory building up. This can be due to memory - * allocation for metadata such as object headers and messages + * allocation for metadata, such as object headers and messages, * when the iterated objects are put into the metadata cache. * \note * If the memory buildup is not desirable, you can configure a @@ -2156,7 +1985,7 @@ H5_DLL herr_t H5Oget_info2(hid_t loc_id, H5O_info1_t *oinfo, unsigned fields); * by location and relative name * * \fgdta_loc_obj_id{loc_id} - * \param[in] name Name of group, relative to \p loc_id + * \param[in] name Name of object, relative to \p loc_id * \param[out] oinfo Buffer in which to return object information * \param[in] fields Flags specifying the fields to include in \p oinfo * \lapl_id @@ -2166,7 +1995,7 @@ H5_DLL herr_t H5Oget_info2(hid_t loc_id, H5O_info1_t *oinfo, unsigned fields); * \deprecated As of HDF5-1.12 this function has been deprecated in favor of * the function H5Oget_info_by_name3() or the macro H5Oget_info_by_name(). * - * \details H5Oget_info_by_name2() specifies an object’s location and name, \p loc_id and + * \details H5Oget_info_by_name2() specifies an object's location and name, \p loc_id and * \p name, respectively, and retrieves the metadata describing * that object in \p oinfo, an H5O_info1_t \c struct. * @@ -2174,7 +2003,7 @@ H5_DLL herr_t H5Oget_info2(hid_t loc_id, H5O_info1_t *oinfo, unsigned fields); * in the H5Oget_info1() function entry. * * The \p fields parameter contains flags to determine which fields - * will be filled in in the H5O_info1_t \c struct returned in + * will be filled in the H5O_info1_t \c struct returned in * \p oinfo. These flags are defined in the H5Opublic.h file: * * \obj_info_fields @@ -2213,7 +2042,7 @@ H5_DLL herr_t H5Oget_info_by_name2(hid_t loc_id, const char *name, H5O_info1_t * * object in the \c struct \p oinfo, as specified by the location, * \p loc_id, group name, \p group_name, the index by which objects * in that group are tracked, \p idx_type, the order by which the - * index is to be traversed, \p order, and an object’s position + * index is to be traversed, \p order, and an object's position * \p n within that index. * * \p oinfo, in which the object information is returned, is a \c struct of @@ -2273,7 +2102,7 @@ H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index * * If \p obj_id is a group identifier, that group serves as the * root of a recursive iteration. If \p obj_id is a file identifier, - * that file’s root group serves as the root of the recursive + * that file's root group serves as the root of the recursive * iteration. If \p obj_id is an attribute identifier, * then the object where the attribute is attached will be iterated. * If \p obj_id is any other type of object, such as a dataset or @@ -2286,70 +2115,18 @@ H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * best effort setting. If the application passes in * a value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * name order. (Name order is the native order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate1_t_snip - * - * The parameters of this callback function have the following values - * or meanings: - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
    \c objObject that serves as root of the iteration; - * same value as the H5Ovisit1() \p obj_id parameter
    \c nameName of object, relative to \c obj, being examined at - * current step of the iteration
    \c infoH5O_info1_t \c struct containing information - * regarding that object
    \c op_dataUser-defined pointer to data required by the application in - * processing the object
    - * - * The H5O_info1_t \c struct is defined in H5Opublic.h: - * \snippet this H5O_info1_t_snip - * - * The return values from an operator are: - * - Zero causes the visit iterator to continue, returning zero when all - * group members have been processed. - * - A positive value causes the visit iterator to immediately return that - * positive value, indicating short-circuit success. - * - A negative value causes the visit iterator to immediately return that - * value, indicating failure. - * - * The H5Ovisit1() \p op_data parameter is a user-defined pointer to the data - * required to process objects in the course of the iteration. This pointer - * is passed back to each step of the iteration in the callback - * function’s \p op_data parameter. + * along the index specified in \p idx_type. * * H5Lvisit1() and H5Ovisit1() are companion functions: one for * examining and operating on links; the other for examining @@ -2363,24 +2140,6 @@ H5_DLL herr_t H5Oget_info_by_idx2(hid_t loc_id, const char *group_name, H5_index * group change during the iteration, the resulting behavior * is undefined. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \version 1.10.5 The macro #H5Ovisit was removed and the function * H5Ovisit1() was copied to H5Ovisit(). * \version 1.10.3 Function H5Ovisit() was copied to H5Ovisit1(), @@ -2434,7 +2193,7 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a file or an object in a file; if \p loc_id is an attribute identifier, * the object where the attribute is attached will be used. * \p obj_name specifies either an object in the file (with an absolute - * name based in the file’s root group) or an object name relative + * name based on the file's root group) or an object name relative * to \p loc_id. If \p loc_id fully specifies the object that is to serve * as the root of the iteration, \p obj_name should be '\c .' (a dot). * (Note that when \p loc_id fully specifies the object that is to serve @@ -2448,27 +2207,21 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * best effort setting. If the application passes in a * value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * name order. (Name order is the native order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders + * along the index specified in \p idx_type. * * The \p op callback function and the effect of the callback - * function’s return value on the application are described + * function's return value on the application are described * in H5Ovisit1(). * * The H5O_info1_t \c struct is defined in H5Opublic.h @@ -2477,7 +2230,7 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * The H5Ovisit_by_name1() \p op_data parameter is a user-defined * pointer to the data required to process objects in the course * of the iteration. This pointer is passed back to each step of - * the iteration in the callback function’s \p op_data parameter. + * the iteration in the callback function's \p op_data parameter. * * \p lapl_id is a link access property list. In the general case, * when default link access properties are acceptable, this can @@ -2495,24 +2248,6 @@ H5_DLL herr_t H5Ovisit1(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * in the file has been presented to the application for whatever * processing the application requires. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \version 1.10.5 The macro #H5Ovisit_by_name was removed and the function * H5Ovisit_by_name1() was copied to #H5Ovisit_by_name. * \version 1.10.3 The H5Ovisit_by_name() function was renamed to H5Ovisit_by_name1(), @@ -2562,7 +2297,7 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i * * If \p obj_id is a group identifier, that group serves as the * root of a recursive iteration. If \p obj_id is a file identifier, - * that file’s root group serves as the root of the recursive + * that file's root group serves as the root of the recursive * iteration. If \p obj_id is an attribute identifier, * then the object where the attribute is attached will be iterated. * If \p obj_id is any other type of object, such as a dataset or @@ -2575,71 +2310,18 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * best effort setting. If the application passes in * a value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * name order. (Name order is the native order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders - * - * The prototype of the callback function op is as follows (as - * defined in the source code file H5Opublic.h): - * - * \snippet this H5O_iterate1_t_snip - * - * The parameters of this callback function have the following values - * or meanings: - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
    \c objObject that serves as root of the iteration; - * same value as the H5Ovisit1() \p obj_id parameter
    \c nameName of object, relative to \c obj, being examined at - * current step of the iteration
    \c infoH5O_info1_t \c struct containing information - * regarding that object
    \c op_dataUser-defined pointer to data required by the application in - * processing the object; a pass-through of the \c op_data pointer - * provided with the H5Ovisit() function call
    - * - * The H5O_info1_t \c struct is defined in H5Opublic.h and - * described in the H5Oget_info1() function entry. - * - * The return values from an operator are: - * - Zero causes the visit iterator to continue, returning zero when all - * group members have been processed. - * - A positive value causes the visit iterator to immediately return that - * positive value, indicating short-circuit success. - * - A negative value causes the visit iterator to immediately return that - * value, indicating failure. - * - * The H5Ovisit2() \p op_data parameter is a user-defined pointer to the data - * required to process objects in the course of the iteration. This pointer - * is passed back to each step of the iteration in the callback - * function’s \p op_data parameter. + * along the index specified in \p idx_type. * * The \p fields parameter contains flags to determine which fields will * be retrieved by the \p op callback function. These flags are defined @@ -2658,23 +2340,6 @@ H5_DLL herr_t H5Ovisit_by_name1(hid_t loc_id, const char *obj_name, H5_index_t i * group change during the iteration, the resulting behavior * is undefined. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. * * \since 1.10.3 * @@ -2725,7 +2390,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a file or an object in a file; if \p loc_id is an attribute identifier, * the object where the attribute is attached will be used. * \p obj_name specifies either an object in the file (with an absolute - * name based in the file’s root group) or an object name relative + * name based in the file's root group) or an object name relative * to \p loc_id. If \p loc_id fully specifies the object that is to serve * as the root of the iteration, \p obj_name should be '\c .' (a dot). * (Note that when \p loc_id fully specifies the object that is to serve @@ -2739,27 +2404,21 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * a group have not been indexed by the index type, they will * first be sorted by that index then the iteration will begin; * if the links have been so indexed, the sorting step will be - * unnecessary, so the iteration may begin more quickly. Valid - * values include the following: - * - * \indexes + * unnecessary, so the iteration may begin more quickly. * * Note that the index type passed in \p idx_type is a * best effort setting. If the application passes in a * value indicating iteration in creation order and a group is * encountered that was not tracked in creation order, that group - * will be iterated over in alpha-numeric order by name, or + * will be iterated over in alphanumeric order by name, or * name order. (Name order is the native order * used by the HDF5 library and is always available.) * * \p order specifies the order in which objects are to be inspected - * along the index specified in \p idx_type. Valid values include - * the following: - * - * \orders + * along the index specified in \p idx_type. * * The \p op callback function and the effect of the callback - * function’s return value on the application are described + * function's return value on the application are described * in H5Ovisit2(). * * The H5O_info1_t \c struct is defined in H5Opublic.h @@ -2768,7 +2427,7 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * The H5Ovisit_by_name2() \p op_data parameter is a user-defined * pointer to the data required to process objects in the course * of the iteration. This pointer is passed back to each step of - * the iteration in the callback function’s \p op_data parameter. + * the iteration in the callback function's \p op_data parameter. * * \p lapl_id is a link access property list. In the general case, * when default link access properties are acceptable, this can @@ -2791,24 +2450,6 @@ H5_DLL herr_t H5Ovisit2(hid_t obj_id, H5_index_t idx_type, H5_iter_order_t order * in the file has been presented to the application for whatever * processing the application requires. * - * \note \Bold{Programming Note for C++ Developers Using C Functions:} - * \note If a C routine that takes a function pointer as an argument is - * called from within C++ code, the C routine should be returned - * from normally. - * - * \note Examples of this kind of routine include callbacks such as - * H5Pset_elink_cb() and H5Pset_type_conv_cb() and - * functions such as H5Tconvert() and H5Ewalk2(). - * - * \note Exiting the routine in its normal fashion allows the HDF5 - * C library to clean up its work properly. In other words, if - * the C++ application jumps out of the routine back to the C++ - * “catch” statement, the library is not given the opportunity - * to close any temporary data structures that were set up when - * the routine was called. The C++ application should save some - * state as the routine is started so that any problem that occurs - * might be diagnosed. - * * \since 1.10.3 * */ diff --git a/libs/windows/include/H5PLextern.h b/libs/windows/include/H5PLextern.h index 7f3df5e..d136051 100644 --- a/libs/windows/include/H5PLextern.h +++ b/libs/windows/include/H5PLextern.h @@ -2,7 +2,7 @@ * Copyright by The HDF Group. * * All rights reserved. * * * - * This file is part of HDF5. The full HDF5 copyright notice, including * + * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * * distribution tree, or in https://www.hdfgroup.org/licenses. * diff --git a/libs/windows/include/H5PLpublic.h b/libs/windows/include/H5PLpublic.h index 55ff594..ca99697 100644 --- a/libs/windows/include/H5PLpublic.h +++ b/libs/windows/include/H5PLpublic.h @@ -2,7 +2,7 @@ * Copyright by The HDF Group. * * All rights reserved. * * * - * This file is part of HDF5. The full HDF5 copyright notice, including * + * This file is part of HDF5. The full HDF5 copyright notice, including * * terms governing use, modification, and redistribution, is contained in * * the COPYING file, which can be found at the root of the source code * * distribution tree, or in https://www.hdfgroup.org/licenses. * @@ -17,8 +17,7 @@ #ifndef H5PLpublic_H #define H5PLpublic_H -/* Public headers needed by this file */ -#include "H5public.h" /* Generic Functions */ +#include "H5public.h" /* Generic Functions */ /*******************/ /* Public Typedefs */ @@ -35,14 +34,16 @@ typedef enum H5PL_type_t { H5PL_TYPE_ERROR = -1, /**< Error */ H5PL_TYPE_FILTER = 0, /**< Filter */ - H5PL_TYPE_VOL = 1, /**< VOL driver */ - H5PL_TYPE_NONE = 2 /**< Sentinel: This must be last! */ + H5PL_TYPE_VOL = 1, /**< VOL connector */ + H5PL_TYPE_VFD = 2, /**< VFD */ + H5PL_TYPE_NONE = 3 /**< Sentinel: This must be last! */ } H5PL_type_t; //! /* Common dynamic plugin type flags used by the set/get_loading_state functions */ #define H5PL_FILTER_PLUGIN 0x0001 #define H5PL_VOL_PLUGIN 0x0002 +#define H5PL_VFD_PLUGIN 0x0004 #define H5PL_ALL_PLUGIN 0xFFFF #ifdef __cplusplus @@ -93,9 +94,9 @@ H5_DLL herr_t H5PLset_loading_state(unsigned int plugin_control_mask); * \brief Queries the loadability of dynamic plugin types * * \param[out] plugin_control_mask List of dynamic plugin types that are enabled or disabled.\n - * A plugin bit set to 0 (zero) indicates that that the dynamic plugin type is + * A plugin bit set to 0 (zero) indicates that the dynamic plugin type is * disabled.\n - * A plugin bit set to 1 (one) indicates that that the dynamic plugin type is + * A plugin bit set to 1 (one) indicates that the dynamic plugin type is * enabled.\n * If the value of \p plugin_control_mask is negative, all dynamic plugin * types are enabled.\n @@ -103,7 +104,7 @@ H5_DLL herr_t H5PLset_loading_state(unsigned int plugin_control_mask); * are disabled. * \return \herr_t * - * \details H5PLget_loading_state() retrieves the bitmask that controls whether a certain type of plugins + * \details H5PLget_loading_state() retrieves the bitmask that controls whether a certain type of plugin * (e.g.: filters, VOL drivers) will be loaded by the HDF5 library. * * Bit positions allocated to date are specified in \ref H5PL_type_t as follows: diff --git a/libs/windows/include/H5PTpublic.h b/libs/windows/include/H5PTpublic.h index d74baa5..3016e77 100644 --- a/libs/windows/include/H5PTpublic.h +++ b/libs/windows/include/H5PTpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -18,19 +17,204 @@ extern "C" { #endif +/** \page H5PT_UG The HDF5 High Level Packet Table + * @todo Under Construction + */ + +/**\defgroup H5PT HDF5 Packet Table APIs (H5PT) + * + * Creating and manipulating HDF5 datasets to support append- + * and read-only operations on table data (H5PT) + * + * The HDF5 Packet Table API is designed to allow records to be + * appended to and read from a table. Packet Table datasets are + * chunked, allowing them to grow as needed. + * + * The Packet Table API, with the H5PT prefix, is not to be confused with + * the H5TB Table API (H5TB prefix). The H5TB APIs are stateless + * (H5TB Tables do not need to be opened or closed) but H5PT Packet Tables + * require less performance overhead. Also, H5TB Tables support insertions + * and deletions, while H5PT Packet Tables support only append operations. + * H5TB functions should not be called on tables created with the + * H5PT API, or vice versa. + * + * Packet Tables are datasets in an HDF5 file, so while their contents + * should not be changed outside of the H5PT API calls, the datatypes of + * Packet Tables can be queried using \ref H5Dget_type. + * Packet Tables can also be given attributes using the normal HDF5 APIs. + * + * \note \Bold{Programming hints:} + * \note The following line includes the HDF5 Packet Table package, H5PT, + * in C applications: + * \code #include "hdf5_hl.h" \endcode + * Without this include, an application will not have access to + * these functions. + * + * - \ref H5PTappend + * \n Appends packets to the end of a packet table. + * - \ref H5PTclose + * \n Closes an open packet table. + * - \ref H5PTcreate + * \n Creates a packet table to store fixed-length + * or variable-length packets. + * - \ref H5PTcreate_fl + * \n Creates a packet table to store fixed-length packets. + * - \ref H5PTcreate_index + * \n Resets a packet table's index to the first packet. + * - \ref H5PTfree_vlen_buff + * \n Releases memory allocated in the process of + * reading variable-length packets. + * - \ref H5PTget_dataset + * \n Returns the backend dataset of this packet table. + * - \ref H5PTget_index + * \n Gets the current record index for a packet table + * - \ref H5PTget_next + * \n Reads packets from a packet table starting at the + * current index. + * - \ref H5PTget_num_packets + * \n Returns the number of packets in a packet table. + * - \ref H5PTget_type + * \n Returns the backend datatype of this packet table. + * - \ref H5PTis_valid + * \n Determines whether an identifier points to a packet table. + * - \ref H5PTis_varlen + * \n Determines whether a packet table contains variable-length + * or fixed-length packets. + * - \ref H5PTopen + * \n Opens an existing packet table. + * - \ref H5PTread_packets + * \n Reads a number of packets from a packet table. + * - \ref H5PTset_index + * \n Sets a packet table's index. + * + */ + /*------------------------------------------------------------------------- * Create/Open/Close functions *------------------------------------------------------------------------- */ /* NOTE: H5PTcreate is replacing H5PTcreate_fl for better name due to the removal of H5PTcreate_vl. H5PTcreate_fl may be retired in 1.8.19. */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Creates a packet table to store fixed-length or + * variable-length packets. + * + * \fg_loc_id + * \param[in] dset_name The name of the packet table to create + * \param[in] dtype_id The datatype of the packet + * \param[in] chunk_size The size in number of table entries per chunk + * \param[in] plist_id Identifier of the property list. Can be used to + * specify the compression of the packet table. + * + * \return Returns an identifier for the new packet table or + * #H5I_INVALID_HID on error. + * + * \details The H5PTcreate() creates and opens a packet table named + * \p dset_name attached to the object specified by the + * identifier \p loc_id. The created packet table should be closed + * with H5PTclose(), eventually. + * + * The datatype, \p dtype_id, may specify any datatype, including + * variable-length data. If \p dtype_id specifies a compound + * datatype, one or more fields in that compound type may be + * variable-length. + * + * \p chunk_size is the size in number of table entries per chunk. + * Packet table datasets use HDF5 chunked storage + * to allow them to grow. This value allows the user + * to set the size of a chunk. The chunk size affects + * performance. + * + * \since 1.10.0 and 1.8.17 + * + */ H5_HLDLL hid_t H5PTcreate(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size, hid_t plist_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Opens an existing packet table. + * + * \fg_loc_id + * \param[in] dset_name The name of the packet table to open + * + * \return Returns an identifier for the packet table or + * #H5I_INVALID_HID on error. + * + * \details H5PTopen() opens an existing packet table in the file or group + * specified by \p loc_id. \p dset_name is the name of the packet + * table and is used to identify it in the file. This function is + * used to open both fixed-length packet tables and variable-length + * packet tables. The packet table should later be closed with + * H5PTclose(). + * + */ H5_HLDLL hid_t H5PTopen(hid_t loc_id, const char *dset_name); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Closes an open packet table. + * + * \param[in] table_id Identifier of packet table to be closed + * + * \return \herr_t + * + * \details The H5PTclose() ends access to a packet table specified + * by \p table_id. + * + */ H5_HLDLL herr_t H5PTclose(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Creates a packet table to store fixed-length packets + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[in] dtype_id The datatype of a packet. + * \param[in] chunk_size The size in number of table entries per + * chunk. + * \param[in] compression The compression level; + * a value of 0 through 9. + * + * \return Returns an identifier for the packet table or + * #H5I_INVALID_HID on error. + * + * \deprecated This function was deprecated in favor of the function + * H5PTcreate(). + * + * \details The H5PTcreate_fl() creates and opens a packet table + * named \p dset_name attached to the object specified by + * the identifier \p loc_id. It should be closed + * with H5PTclose(). + * + * The datatype, \p dtype_id, may specify any datatype, + * including variable-length data. If \p dtype_id specifies a + * compound datatype, one or more fields in that compound type + * may be variable-length. + * + * \p chunk_size is the size in number of table entries per chunk. + * Packet table datasets use HDF5 chunked storage + * to allow them to grow. This value allows the user + * to set the size of a chunk. The chunk size affects + * performance. + * + * \p compression is the compression level, a value of 0 through 9. + * Level 0 is faster but offers the least compression; + * level 9 is slower but offers maximum compression. + * A setting of -1 indicates that no compression is desired. + * + */ /* This function may be removed from the packet table in release 1.8.19. */ H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name, hid_t dtype_id, hsize_t chunk_size, int compression); @@ -39,24 +223,148 @@ H5_HLDLL hid_t H5PTcreate_fl(hid_t loc_id, const char *dset_name, hid_t dtype_id * Write functions *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Appends packets to the end of a packet table. + * + * \param[in] table_id Identifier of packet table to which + * packets should be appended + * \param[in] nrecords Number of packets to be appended + * \param[in] data Buffer holding data to write + * + * \return \herr_t + * + * \details The H5PTappend() writes \p nrecords packets to the end of a + * packet table specified by \p table_id. \p data is a buffer + * containing the data to be written. For a packet table holding + * fixed-length packets, this data should be in the packet + * table's datatype. For a variable-length packet table, + * the data should be in the form of #hvl_t structs. + * + */ H5_HLDLL herr_t H5PTappend(hid_t table_id, size_t nrecords, const void *data); /*------------------------------------------------------------------------- * Read functions *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Reads packets from a packet table starting at the current index. + * + * \param[in] table_id Identifier of packet table to read from + * \param[in] nrecords Number of packets to be read + * \param[out] data Buffer into which to read data + * + * \return \herr_t + * + * \details The H5PTget_next() reads \p nrecords packets starting with + * the "current index" from a packet table specified by \p table_id. + * The packet table's index is set and reset with H5PTset_index() + * and H5PTcreate_index(). \p data is a buffer into which the + * data should be read. + * + * For a packet table holding variable-length records, the data + * returned in the buffer will be in form of a #hvl_t struct + * containing the length of the data and a pointer to it in memory. + * The memory used by this data must be freed using H5PTfree_vlen_buff(). + * + */ H5_HLDLL herr_t H5PTget_next(hid_t table_id, size_t nrecords, void *data); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Reads a number of packets from a packet table. + * + * \param[in] table_id Identifier of packet table to read from + * \param[in] start Packet to start reading from + * \param[in] nrecords Number of packets to be read + * \param[out] data Buffer into which to read data. + * + * \return \herr_t + * + * \details The H5PTread_packets() reads \p nrecords packets starting at + * packet number \p start from a packet table specified by + * \p table_id. \p data is a buffer into which the data should + * be read. + * + * For a packet table holding variable-length records, the data + * returned in the buffer will be in form of #hvl_t structs, + * each containing the length of the data and a pointer to it in + * memory. The memory used by this data must be freed using + * H5PTfree_vlen_buff(). + * + */ H5_HLDLL herr_t H5PTread_packets(hid_t table_id, hsize_t start, size_t nrecords, void *data); /*------------------------------------------------------------------------- * Inquiry functions *------------------------------------------------------------------------- */ + +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Returns the number of packets in a packet table. + * + * \param[in] table_id Identifier of packet table to query + * \param[out] nrecords Number of packets in packet table + * + * \return \herr_t + * + * \details The H5PTget_num_packets() returns by reference the number + * of packets in a packet table specified by \p table_id. + * + */ H5_HLDLL herr_t H5PTget_num_packets(hid_t table_id, hsize_t *nrecords); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Determines whether an identifier points to a packet table. + * + * \param[in] table_id Identifier to query + * + * \return Returns a non-negative value if \p table_id is + * a valid packet table, otherwise returns a negative value. + * + * \details The H5PTis_valid() returns a non-negative value if + * \p table_id corresponds to an open packet table, + * and returns a negative value otherwise. + * + */ H5_HLDLL herr_t H5PTis_valid(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Determines whether a packet table contains + * variable-length or fixed-length packets. + * + * \param[in] table_id Packet table to query + * + * \return Returns 1 for a variable-length packet table, + * 0 for fixed-length, or a negative value on error. + * + * \details The H5PTis_varlen() returns 1 (TRUE) if \p table_id is + * a packet table containing variable-length records. + * It returns 0 (FALSE) if \p table_id is a packet table + * containing fixed-length records. If \p table_id is not a + * packet table, a negative value is returned. + * + * \version 1.10.0 and 1.8.17 Function re-introduced. + * Function had been removed in 1.8.3. + * + */ H5_HLDLL herr_t H5PTis_varlen(hid_t table_id); /*------------------------------------------------------------------------- @@ -66,8 +374,42 @@ H5_HLDLL herr_t H5PTis_varlen(hid_t table_id); *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Returns the backend dataset of this packet table. + * + * \param[in] table_id Identifier of the packet table + * + * \return Returns a dataset identifier or H5I_INVALID_HID on error. + * + * \details The H5PTget_dataset() returns the identifier of the dataset + * storing the packet table \p table_id. This dataset identifier + * will be closed by H5PTclose(). + * + * \since 1.10.0 and 1.8.17 + * + */ H5_HLDLL hid_t H5PTget_dataset(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Returns the backend datatype of this packet table. + * + * \param[in] table_id Identifier of the packet table + * + * \return Returns a datatype identifier or H5I_INVALID_HID on error. + * + * \details The H5PTget_type() returns the identifier of the datatype + * used by the packet table \p table_id. This datatype + * identifier will be closed by H5PTclose(). + * + * \since 1.10.0 and 1.8.17 + * + */ H5_HLDLL hid_t H5PTget_type(hid_t table_id); /*------------------------------------------------------------------------- @@ -77,10 +419,63 @@ H5_HLDLL hid_t H5PTget_type(hid_t table_id); *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Resets a packet table's index to the first packet. + * + * \param[in] table_id Identifier of packet table whose index + * should be initialized. + * + * \return \herr_t + * + * \details Each packet table keeps an index of the "current" packet + * so that \c get_next can iterate through the packets in order. + * H5PTcreate_index() initializes a packet table's index, and + * should be called before using \c get_next. The index must be + * initialized every time a packet table is created or opened; + * this information is lost when the packet table is closed. + * + */ H5_HLDLL herr_t H5PTcreate_index(hid_t table_id); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Sets a packet table's index. + * + * \param[in] table_id Identifier of packet table whose index is to be set + * \param[in] pt_index The packet to which the index should point + * + * \return \herr_t + * + * \details Each packet table keeps an index of the "current" packet + * so that \c get_next can iterate through the packets in order. + * H5PTset_index() sets this index to point to a user-specified + * packet (the packets are zero-indexed). + * + */ H5_HLDLL herr_t H5PTset_index(hid_t table_id, hsize_t pt_index); +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Gets the current record index for a packet table. + * + * \param[in] table_id Table identifier + * \param[out] pt_index Current record index + * + * \return \herr_t + * + * \details The H5PTget_index() returns the current record index + * \p pt_index for the table identified by \p table_id. + * + * \since 1.8.0 + * + */ H5_HLDLL herr_t H5PTget_index(hid_t table_id, hsize_t *pt_index); /*------------------------------------------------------------------------- @@ -90,6 +485,29 @@ H5_HLDLL herr_t H5PTget_index(hid_t table_id, hsize_t *pt_index); *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5PT + * + * \brief Releases memory allocated in the process of reading + * variable-length packets. + * + * \param[in] table_id Packet table whose memory should be freed. + * \param[in] bufflen Size of \p buff + * \param[in] buff Buffer that was used to read in variable-length + * packets + * + * \return \herr_t + * + * \details When variable-length packets are read, memory is automatically + * allocated to hold them, and must be freed. H5PTfree_vlen_buff() + * frees this memory, and should be called whenever packets are + * read from a variable-length packet table. + * + * \version 1.10.0 and 1.8.17 Function re-introduced. + * Function had been removed in 1.8.3. + * + */ H5_HLDLL herr_t H5PTfree_vlen_buff(hid_t table_id, size_t bufflen, void *buff); #ifdef __cplusplus diff --git a/libs/windows/include/H5PacketTable.h b/libs/windows/include/H5PacketTable.h index acd0ccf..8ef5ac3 100644 --- a/libs/windows/include/H5PacketTable.h +++ b/libs/windows/include/H5PacketTable.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -31,12 +30,9 @@ class H5_HLCPPDLL PacketTable { public: /* Null constructor - * Sets table_id to "invalid" + * Sets table_id to H5I_INVALID_HID */ - PacketTable() - { - table_id = H5I_INVALID_HID; - } + PacketTable(); /* "Open" Constructor * Opens an existing packet table, which can contain either fixed-length or @@ -57,39 +53,39 @@ class H5_HLCPPDLL PacketTable { * Use this after the constructor to ensure HDF did not have * any trouble making or opening the packet table. */ - bool IsValid(); + bool IsValid() const; /* IsVariableLength * Return 1 if this packet table uses variable-length datatype, * return 0 if it is Fixed Length. Returns -1 if the table is * invalid (not open). */ - int IsVariableLength(); + int IsVariableLength() const; /* ResetIndex * Sets the "current packet" index to point to the first packet in the * packet table */ - void ResetIndex(); + void ResetIndex() const; /* SetIndex * Sets the current packet to point to the packet specified by index. * Returns 0 on success, negative on failure (if index is out of bounds) */ - int SetIndex(hsize_t index); + int SetIndex(hsize_t index) const; /* GetIndex * Returns the position of the current packet. * On failure, returns 0 and error is set to negative. */ - hsize_t GetIndex(int &error); + hsize_t GetIndex(int &error) const; /* GetPacketCount * Returns the number of packets in the packet table. Error * is set to 0 on success. On failure, returns 0 and * error is set to negative. */ - hsize_t GetPacketCount(int &error); + hsize_t GetPacketCount(int &error) const; hsize_t GetPacketCount() @@ -101,7 +97,7 @@ class H5_HLCPPDLL PacketTable { /* GetTableId * Returns the identifier of the packet table. */ - hid_t GetTableId(); + hid_t GetTableId() const; /* GetDatatype * Returns the datatype identifier used by the packet table, on success, @@ -109,7 +105,7 @@ class H5_HLCPPDLL PacketTable { * Note: it is best to avoid using this identifier in applications, unless * the desired functionality cannot be performed via the packet table ID. */ - hid_t GetDatatype(); + hid_t GetDatatype() const; /* GetDataset * Returns the dataset identifier associated with the packet table, on @@ -117,7 +113,7 @@ class H5_HLCPPDLL PacketTable { * Note: it is best to avoid using this identifier in applications, unless * the desired functionality cannot be performed via the packet table ID. */ - hid_t GetDataset(); + hid_t GetDataset() const; /* FreeBuff * Frees the buffers created when variable-length packets are read. @@ -125,7 +121,7 @@ class H5_HLCPPDLL PacketTable { * location in memory. * Returns 0 on success, negative on error. */ - int FreeBuff(size_t numStructs, hvl_t *buffer); + int FreeBuff(size_t numStructs, hvl_t *buffer) const; protected: hid_t table_id; @@ -166,7 +162,7 @@ class H5_HLCPPDLL FL_PacketTable : virtual public PacketTable { /* Destructor * Cleans up the packet table */ - virtual ~FL_PacketTable() + ~FL_PacketTable() override { } diff --git a/libs/windows/include/H5Ppublic.h b/libs/windows/include/H5Ppublic.h index 5adb05e..8410a82 100644 --- a/libs/windows/include/H5Ppublic.h +++ b/libs/windows/include/H5Ppublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -18,20 +17,18 @@ #ifndef H5Ppublic_H #define H5Ppublic_H -/* System headers needed by this file */ - -/* Public headers needed by this file */ -#include "H5public.h" -#include "H5ACpublic.h" -#include "H5Dpublic.h" -#include "H5Fpublic.h" -#include "H5FDpublic.h" -#include "H5Ipublic.h" -#include "H5Lpublic.h" -#include "H5Opublic.h" -#include "H5MMpublic.h" -#include "H5Tpublic.h" -#include "H5Zpublic.h" +#include "H5public.h" /* Generic Functions */ +#include "H5ACpublic.h" /* Metadata Cache */ +#include "H5Dpublic.h" /* Datasets */ +#include "H5Fpublic.h" /* Files */ +#include "H5FDpublic.h" /* (Virtual) File Drivers */ +#include "H5Ipublic.h" /* Identifiers */ +#include "H5Lpublic.h" /* Links */ +#include "H5MMpublic.h" /* Memory Management */ +#include "H5Opublic.h" /* Object Headers */ +#include "H5Spublic.h" /* Dataspaces */ +#include "H5Tpublic.h" /* Datatypes */ +#include "H5Zpublic.h" /* Data Filters */ /*****************/ /* Public Macros */ @@ -99,8 +96,10 @@ #define H5P_CRT_ORDER_TRACKED 0x0001 #define H5P_CRT_ORDER_INDEXED 0x0002 -/* Default value for all property list classes */ -#define H5P_DEFAULT (hid_t)0 +/** + * Default value of type \ref hid_t for all property list classes + */ +#define H5P_DEFAULT 0 /* (hid_t) */ #ifdef __cplusplus extern "C" { @@ -112,14 +111,72 @@ extern "C" { /* Define property list class callback function pointer types */ //! +/** + * \brief Callback function for H5Pcreate_class() + * + * \param[in] prop_id The identifier of the property list class being created + * \param[in] create_data User pointer to any class creation data required + * \return \herr_t + * + * \details This function is called when a new property list of the class + * with which this function was registered is being created. The + * function is called after any registered parent create function is + * called for each property value. + * + * If the create function returns a negative value, the new list is not + * returned to the user and the property list creation routine returns + * an error value. + * + * \since 1.4.0 + * + */ typedef herr_t (*H5P_cls_create_func_t)(hid_t prop_id, void *create_data); //! //! +/** + * \brief Callback function for H5Pcreate_class() + * + * \param[in] new_prop_id The identifier of the property list copy + * \param[in] old_prop_id The identifier of the property list being copied + * \param[in] copy_data User pointer to any copy data required + * \return \herr_t + * + * \details This function is called when an existing property list of this + * class is copied. The copy callback function is called after any + * registered parent copy callback function is called for each property + * value. + * + * If the copy routine returns a negative value, the new list is not + * returned to the user and the property list copy function returns an + * error value. + * + * \since 1.4.0 + * + */ typedef herr_t (*H5P_cls_copy_func_t)(hid_t new_prop_id, hid_t old_prop_id, void *copy_data); //! //! +/** + * \brief Callback function for H5Pcreate_class() + * + * \param[in] prop_id The identifier of the property list class being created + * \param[in] close_data User pointer to any close data required + * \return \herr_t + * + * \details This function is called when a property list of the class + * with which this function was registered is being closed. The + * function is called after any registered parent close function is + * called for each property value. + * + * If the close function returns a negative value, the new list is not + * returned to the user and the property list close routine returns + * an error value. + * + * \since 1.4.0 + * + */ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); //! @@ -133,8 +190,8 @@ typedef herr_t (*H5P_cls_close_func_t)(hid_t prop_id, void *close_data); * \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. + * \details The H5P_prp_cb1_t() function 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); //! @@ -149,8 +206,8 @@ typedef herr_t (*H5P_prp_cb1_t)(const char *name, size_t size, void *value); * \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. + * \details The H5P_prp_cb2_t() function 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); //! @@ -158,12 +215,49 @@ typedef herr_t (*H5P_prp_cb2_t)(hid_t prop_id, const char *name, size_t size, vo 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; +//! +/** + * \brief Callback function for encoding property values + * + * \param[in] value The property value to be encoded + * \param[out] buf The encoded property value + * \param[out] size The size of \p buf + * \return \herr_t + * + * \note There is currently no public API which exposes a callback of this type. + * + */ typedef herr_t (*H5P_prp_encode_func_t)(const void *value, void **buf, size_t *size); +//! +//! +/** + * \brief Callback function for decoding property values + * + * \param[in] buf A buffer containing an encoded property value + * \param[out] value The decoded property value + * \return \herr_t + * + * \note There is currently no public API which exposes a callback of this type. + * + */ 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; //! +/** + * \brief Callback function for comparing property values + * + * \param[in] value1 A property value + * \param[in] value2 A property value + * \param[in] size The size of the \p value1 and \p value2 buffers + * \return Returns a positive value if \c value1 is greater than \c value2, a + * negative value if \c value2 is greater than \c value1 and zero if + * \c value1 and \c value2 are equal. + * + * \see H5Pregister(), H5Pinsert() + */ typedef int (*H5P_prp_compare_func_t)(const void *value1, const void *value2, size_t size); //! @@ -171,6 +265,21 @@ typedef H5P_prp_cb1_t H5P_prp_close_func_t; /* Define property list iteration function type */ //! +/** + * \brief Callback function for H5Piterate() + * + * \param[in] id The identifier of a property list or property list class + * \param[in] name The name of the current property + * \param[in,out] iter_data The user context passed to H5Piterate() + * \return \herr_t_iter + * + * \details This function is called for each property encountered when + * iterating over a property list or property list class + * via H5Piterate(). + * + * \since 1.4.0 + * + */ typedef herr_t (*H5P_iterate_t)(hid_t id, const char *name, void *iter_data); //! @@ -216,7 +325,6 @@ typedef enum H5D_mpio_actual_io_mode_t { 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; @@ -232,24 +340,93 @@ typedef enum H5D_mpio_no_collective_cause_t { 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 */ + /**< Collective I/O was not performed because datatype conversions were required and selection I/O was not + possible (see below) */ 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! */ + /**< Collective I/O was disabled by environment variable (\Code{HDF5_MPI_OPT_TYPES}) */ 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! */ + /**< Collective I/O was not performed because parallel filtered writes are disabled */ H5D_MPIO_ERROR_WHILE_CHECKING_COLLECTIVE_POSSIBLE = 0x80, - /**< \todo FIXME! */ - H5D_MPIO_NO_COLLECTIVE_MAX_CAUSE = 0x100 + /**< Error */ + H5D_MPIO_NO_SELECTION_IO = 0x100, + /**< Collective I/O would be supported by selection or vector I/O but that feature was disabled + (see causes via H5Pget_no_selection_io_cause()) */ + H5D_MPIO_NO_COLLECTIVE_MAX_CAUSE = 0x200 /**< Sentinel */ } H5D_mpio_no_collective_cause_t; //! +/** + * Causes for H5Pget_no_selection_io_cause() property + */ +#define H5D_SEL_IO_DISABLE_BY_API \ + (0x0001u) /**< Selection I/O was not performed because \ + the feature was disabled by the API */ +#define H5D_SEL_IO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET \ + (0x0002u) /**< Selection I/O was not performed because the \ + dataset was neither contiguous nor chunked */ +#define H5D_SEL_IO_CONTIGUOUS_SIEVE_BUFFER \ + (0x0004u) /**< Selection I/O was not performed because of \ + sieve buffer for contiguous dataset */ +#define H5D_SEL_IO_NO_VECTOR_OR_SELECTION_IO_CB \ + (0x0008u) /**< Selection I/O was not performed because the VFD \ + does not have vector or selection I/O callback */ +#define H5D_SEL_IO_PAGE_BUFFER \ + (0x0010u) /**< Selection I/O was not performed because of \ + page buffer */ +#define H5D_SEL_IO_DATASET_FILTER \ + (0x0020u) /**< Selection I/O was not performed because of \ + dataset filters */ +#define H5D_SEL_IO_CHUNK_CACHE \ + (0x0040u) /**< Selection I/O was not performed because of \ + chunk cache */ +#define H5D_SEL_IO_TCONV_BUF_TOO_SMALL \ + (0x0080u) /**< Selection I/O was not performed because the \ + type conversion buffer is too small */ +#define H5D_SEL_IO_BKG_BUF_TOO_SMALL \ + (0x0100u) /**< Selection I/O was not performed because the \ + type conversion background buffer is too small */ +#define H5D_SEL_IO_DEFAULT_OFF \ + (0x0200u) /**< Selection I/O was not performed because the \ + selection I/O mode is DEFAULT and the library \ + chose it to be off for this case */ + +/* Causes for H5D_MPIO_NO_SELECTION_IO */ +#define H5D_MPIO_NO_SELECTION_IO_CAUSES \ + (H5D_SEL_IO_DISABLE_BY_API | H5D_SEL_IO_TCONV_BUF_TOO_SMALL | H5D_SEL_IO_BKG_BUF_TOO_SMALL | \ + H5D_SEL_IO_DATASET_FILTER | H5D_SEL_IO_CHUNK_CACHE) + +//! +/** + * Selection I/O mode property + * + * \details The default value, #H5D_SELECTION_IO_MODE_DEFAULT, + * indicates selection I/O can be ON or OFF as + * determined by library internal. + */ +typedef enum H5D_selection_io_mode_t { + H5D_SELECTION_IO_MODE_DEFAULT = 0, + /**< Default selection I/O mode. */ + H5D_SELECTION_IO_MODE_OFF, + /**< Selection I/O is off. */ + H5D_SELECTION_IO_MODE_ON + /**< Selection I/O is on. */ +} H5D_selection_io_mode_t; +//! + +/** + * Causes for H5Pget_actual_selection_io_mode() property + */ +#define H5D_SCALAR_IO (0x0001u) /**< Scalar (or legacy MPIO) I/O was performed */ +#define H5D_VECTOR_IO (0x0002u) /**< Vector I/O was performed */ +#define H5D_SELECTION_IO (0x0004u) /**< Selection I/O was performed */ + /********************/ /* Public Variables */ /********************/ @@ -279,7 +456,7 @@ H5_DLLVAR hid_t H5P_CLS_LINK_ACCESS_ID_g; H5_DLLVAR hid_t H5P_CLS_VOL_INITIALIZE_ID_g; H5_DLLVAR hid_t H5P_CLS_REFERENCE_ACCESS_ID_g; -/* Default roperty list IDs */ +/* Default property list IDs */ /* (Internal to library, do not use! Use macros above) */ H5_DLLVAR hid_t H5P_LST_FILE_CREATE_ID_g; H5_DLLVAR hid_t H5P_LST_FILE_ACCESS_ID_g; @@ -308,7 +485,7 @@ H5_DLLVAR hid_t H5P_LST_REFERENCE_ACCESS_ID_g; /* Generic property list routines */ /** - * \ingroup GPLO + * \ingroup PLCR * * \brief Terminates access to a property list * @@ -326,7 +503,7 @@ H5_DLLVAR hid_t H5P_LST_REFERENCE_ACCESS_ID_g; */ H5_DLL herr_t H5Pclose(hid_t plist_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Closes an existing property list class * @@ -343,7 +520,7 @@ H5_DLL herr_t H5Pclose(hid_t plist_id); */ H5_DLL herr_t H5Pclose_class(hid_t plist_id); /** - * \ingroup GPLO + * \ingroup PLCR * * \brief Copies an existing property list to create a new property list * @@ -360,7 +537,7 @@ H5_DLL herr_t H5Pclose_class(hid_t plist_id); */ H5_DLL hid_t H5Pcopy(hid_t plist_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Copies a property from one list or class to another * @@ -396,7 +573,7 @@ H5_DLL hid_t H5Pcopy(hid_t plist_id); */ H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name); /** - * \ingroup GPLO + * \ingroup PLCR * * \brief Creates a new property list as an instance of a property list class * @@ -520,7 +697,7 @@ H5_DLL herr_t H5Pcopy_prop(hid_t dst_id, hid_t src_id, const char *name); */ H5_DLL hid_t H5Pcreate(hid_t cls_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Creates a new property list class * @@ -549,77 +726,12 @@ H5_DLL hid_t H5Pcreate(hid_t cls_id); * those existing properties, only add or remove their own class * properties. Property list classes defined and supported in the * HDF5 library distribution are listed and briefly described in - * H5Pcreate(). The \p create routine is called when a new property - * list of this class is being created. The #H5P_cls_create_func_t - * callback function is defined as follows: + * H5Pcreate(). The \p create, \p copy, \p close functions are called + * when a property list of the new class is created, copied, or closed, + * respectively. * - * \snippet this H5P_cls_create_func_t_snip - * - * The parameters to this callback function are defined as follows: - * - * - * - * - * - * - * - * - * - *
    \ref hid_t \c prop_idIN: The identifier of the property list being created
    \Code{void * create_data}IN: User pointer to any class creation data required
    - * - * The \p create routine is called after any registered - * \p create function is called for each property value. If the - * \p create routine returns a negative value, the new list is not - * returned to the user and the property list creation routine returns - * an error value. - * - * The \p copy routine is called when an existing property - * list of this class is copied. The #H5P_cls_copy_func_t callback - * function is defined as follows: - * \snippet this H5P_cls_copy_func_t_snip - * - * The parameters to this callback function are defined as follows: - * - * - * - * - * - * - * - * - * - *
    \ref hid_t \c prop_idIN: The identifier of the property list created by copying
    \Code{void * copy_data}IN: User pointer to any class copy data required
    - * - * The \p copy routine is called after any registered \p copy function - * is called for each property value. If the \p copy routine returns a - * negative value, the new list is not returned to the user and the - * property list \p copy routine returns an error value. - * - * The \p close routine is called when a property list of this class - * is being closed. The #H5P_cls_close_func_t callback function is - * defined as follows: - * \snippet this H5P_cls_close_func_t_snip - * - * The parameters to this callback function are defined as follows: - * - * - * - * - * - * - * - * - * - *
    \ref hid_t \c prop_idIN: The identifier of the property list being closed
    \Code{void * close_data}IN: User pointer to any class close data required
    - * - * The \p close routine is called before any registered \p close - * function is called for each property value. If the \p close routine - * returns a negative value, the property list close routine returns - * an error value but the property list is still closed. - * - * H5Pclose_class() can be used to release the property list class - * identifier returned by this function so that resources leaks will - * not develop. + * H5Pclose_class() must be used to release the property list class + * identifier returned by this function. * * \since 1.4.0 * @@ -628,7 +740,7 @@ H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func H5P_cls_copy_func_t copy, void *copy_data, H5P_cls_close_func_t close, void *close_data); /** - * \ingroup GPLO + * \ingroup PLCR * * \brief Decodes property list received in a binary object buffer and * returns a new property list identifier @@ -657,7 +769,7 @@ H5_DLL hid_t H5Pcreate_class(hid_t parent, const char *name, H5P_cls_create_func */ H5_DLL hid_t H5Pdecode(const void *buf); /** - * \ingroup GPLO + * \ingroup PLCR * * \brief Encodes the property values in a property list into a binary * buffer @@ -711,7 +823,7 @@ H5_DLL hid_t H5Pdecode(const void *buf); */ H5_DLL herr_t H5Pencode2(hid_t plist_id, void *buf, size_t *nalloc, hid_t fapl_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Compares two property lists or classes for equality * @@ -731,7 +843,7 @@ H5_DLL herr_t H5Pencode2(hid_t plist_id, void *buf, size_t *nalloc, hid_t fapl_i */ H5_DLL htri_t H5Pequal(hid_t id1, hid_t id2); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Queries whether a property name exists in a property list or * class @@ -749,7 +861,7 @@ H5_DLL htri_t H5Pequal(hid_t id1, hid_t id2); */ H5_DLL htri_t H5Pexist(hid_t plist_id, const char *name); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Queries the value of a property * @@ -781,7 +893,7 @@ H5_DLL htri_t H5Pexist(hid_t plist_id, const char *name); */ H5_DLL herr_t H5Pget(hid_t plist_id, const char *name, void *value); /** - *\ingroup GPLO + * \ingroup PLCR * * \brief Returns the property list class identifier for a property list * @@ -811,14 +923,14 @@ H5_DLL herr_t H5Pget(hid_t plist_id, const char *name, void *value); * \code * plist_class_id = H5Pget_class (dsetA_plist); * - * if H5Pequal (plist_class_id, H5P_OBJECT_CREATE) = TRUE; + * if H5Pequal (plist_class_id, H5P_OBJECT_CREATE) = true; * [ H5P_OBJECT_CREATE is the property list class ] * [ returned by H5Pget_class. ] * - * else if H5Pequal (plist_class_id, H5P_DATASET_CREATE) = TRUE; + * else if H5Pequal (plist_class_id, H5P_DATASET_CREATE) = true; * [ H5P_DATASET_CREATE is the property list class. ] * - * else if H5Pequal (plist_class_id, H5P_DATASET_XFER) = TRUE; + * else if H5Pequal (plist_class_id, H5P_DATASET_XFER) = true; * [ H5P_DATASET_XFER is the property list class. ] * * . @@ -844,7 +956,7 @@ H5_DLL herr_t H5Pget(hid_t plist_id, const char *name, void *value); */ H5_DLL hid_t H5Pget_class(hid_t plist_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Retrieves the name of a class * @@ -988,7 +1100,7 @@ H5_DLL hid_t H5Pget_class(hid_t plist_id); */ H5_DLL char *H5Pget_class_name(hid_t pclass_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Retrieves the parent class of a property class * @@ -1004,7 +1116,7 @@ H5_DLL char *H5Pget_class_name(hid_t pclass_id); */ H5_DLL hid_t H5Pget_class_parent(hid_t pclass_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Queries the number of properties in a property list or class * @@ -1027,7 +1139,7 @@ H5_DLL hid_t H5Pget_class_parent(hid_t pclass_id); */ H5_DLL herr_t H5Pget_nprops(hid_t id, size_t *nprops); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Queries the size of a property value in bytes * @@ -1048,7 +1160,7 @@ H5_DLL herr_t H5Pget_nprops(hid_t id, size_t *nprops); */ H5_DLL herr_t H5Pget_size(hid_t id, const char *name, size_t *size); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Registers a temporary property with a property list * @@ -1298,7 +1410,7 @@ H5_DLL herr_t H5Pinsert2(hid_t plist_id, const char *name, size_t size, void *va H5P_prp_get_func_t get, H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Determines whether a property list is a member of a class * @@ -1318,7 +1430,7 @@ H5_DLL herr_t H5Pinsert2(hid_t plist_id, const char *name, size_t size, void *va */ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Iterates over properties in a property class or list * @@ -1348,36 +1460,13 @@ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); * returned in this case, the iterator cannot be restarted if * one of the calls to its operator returns non-zero. * - * The prototype for the #H5P_iterate_t operator is as follows: - * \snippet this H5P_iterate_t_snip - * - * The operation receives the property list or class + * The operation \p iter_func receives the property list or class * identifier for the object being iterated over, \p id, the * name of the current property within the object, \p name, * and the pointer to the operator data passed in to H5Piterate(), - * \p iter_data. The valid return values from an operator are - * as follows: + * \p iter_data. * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
    ZeroCauses the iterator to continue, returning zero when all - * properties have been processed
    PositiveCauses the iterator to immediately return that positive - * value, indicating short-circuit success. The iterator - * can be restarted at the index of the next property
    NegativeCauses the iterator to immediately return that value, - * indicating failure. The iterator can be restarted at the - * index of the next property
    - * H5Piterate() assumes that the properties in the object + * \warning H5Piterate() assumes that the properties in the object * identified by \p id remain unchanged through the iteration. * If the membership changes during the iteration, the function's * behavior is undefined. @@ -1387,7 +1476,7 @@ H5_DLL htri_t H5Pisa_class(hid_t plist_id, hid_t pclass_id); */ H5_DLL int H5Piterate(hid_t id, int *idx, H5P_iterate_t iter_func, void *iter_data); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Registers a permanent property with a property list class * @@ -1668,7 +1757,7 @@ H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *de H5P_prp_delete_func_t prp_del, H5P_prp_copy_func_t copy, H5P_prp_compare_func_t compare, H5P_prp_close_func_t close); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Removes a property from a property list * @@ -1694,7 +1783,7 @@ H5_DLL herr_t H5Pregister2(hid_t cls_id, const char *name, size_t size, void *de */ H5_DLL herr_t H5Premove(hid_t plist_id, const char *name); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Sets a property list value * @@ -1726,7 +1815,7 @@ H5_DLL herr_t H5Premove(hid_t plist_id, const char *name); */ H5_DLL herr_t H5Pset(hid_t plist_id, const char *name, const void *value); /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Removes a property from a property list class * @@ -1745,8 +1834,6 @@ H5_DLL herr_t H5Pset(hid_t plist_id, const char *name, const void *value); */ H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name); -/* Object creation property list (OCPL) routines */ - /** * \ingroup DCPL * @@ -1766,6 +1853,9 @@ H5_DLL herr_t H5Punregister(hid_t pclass_id, const char *name); * */ H5_DLL htri_t H5Pall_filters_avail(hid_t plist_id); + +/* Object creation property list (OCPL) routines */ + /** * \ingroup OCPL * @@ -1849,9 +1939,6 @@ H5_DLL herr_t H5Pget_attr_phase_change(hid_t plist_id, unsigned *max_compact, un * * \brief Returns information about a filter in a pipeline * - * \todo Signature for H5Pget_filter2 is different in H5Pocpl.c than in - * H5Ppublic.h - * * \ocpl_id{plist_id} * \param[in] idx Sequence number within the filter pipeline of the filter * for which information is sought @@ -2001,7 +2088,7 @@ H5_DLL int H5Pget_nfilters(hid_t plist_id); * are being recorded * * \plist_id - * \param[out] track_times Boolean value, 1 (TRUE) or 0 (FALSE), + * \param[out] track_times Boolean value, 1 (true) or 0 (false), * specifying whether object times are being recorded * * \return \herr_t @@ -2210,7 +2297,7 @@ H5_DLL herr_t H5Pset_attr_creation_order(hid_t plist_id, unsigned crt_order_flag */ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, unsigned min_dense); /** - * \ingroup OCPL + * \ingroup DCPL * * \brief Sets deflate (GNU gzip) compression method and compression level * @@ -2219,6 +2306,8 @@ H5_DLL herr_t H5Pset_attr_phase_change(hid_t plist_id, unsigned max_compact, uns * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_deflate() sets the deflate compression method and the * compression level, \p level, for a dataset or group creation * property list, \p plist_id. @@ -2297,10 +2386,13 @@ H5_DLL herr_t H5Pset_deflate(hid_t plist_id, unsigned level); * (#H5Z_FILTER_DEFLATE) and the Fletcher32 error detection filter * (#H5Z_FILTER_FLETCHER32). * - * The array \p c_values contains \p cd_nelmts integers which are - * auxiliary data for the filter. The integer values will be - * stored in the dataset object header as part of the filter - * information. + * The array \p cd_values contains \p cd_nelmts unsigned integers + * which are auxiliary data for the filter. The values are typically + * used as parameters to control the filter. In a filter's + * \p set_local method (called from \p H5Dcreate), the values are + * interpreted and possibly modified before they are used to control + * the filter. These, possibly modified values, are then stored in + * the dataset object header as auxiliary data for the filter. * * The \p flags argument is a bit vector with the following * fields specifying certain general properties of the filter: @@ -2324,7 +2416,7 @@ H5_DLL herr_t H5Pset_deflate(hid_t plist_id, unsigned level); * * #H5Z_FLAG_MANDATORY * If the filter is required, that is, set to mandatory, - * and the filter fails, the library’s behavior depends + * and the filter fails, the library's behavior depends * on whether the chunk cache is in use: * \li If the chunk cache is enabled, data chunks will * be flushed to the file during H5Dclose() and the @@ -2391,11 +2483,11 @@ H5_DLL herr_t H5Pset_deflate(hid_t plist_id, unsigned level); * property list, the group will be created with the new group file * format. The filters will come into play only when dense storage * is used (see H5Pset_link_phase_change()) and will be applied to - * the group’s fractal heap. The fractal heap will contain most of - * the the group’s link metadata, including link names. + * the group's fractal heap. The fractal heap will contain most of + * the group's link metadata, including link names. * * \note When working with group creation property lists, if you are - * adding a filter that is not in HDF5’s set of predefined filters, + * adding a filter that is not in HDF5's set of predefined filters, * i.e., a user-defined or third-party filter, you must first * determine that the filter will work for a group. See the * discussion of the set local and can apply callback functions @@ -3241,7 +3333,7 @@ H5_DLL herr_t H5Pget_cache(hid_t plist_id, int *mdc_nelmts, /* out */ * after the call to H5Pset_fapl_core(). It is an error to use this * function with any other VFD. * - * \note This function only applies to the backing store write operation + * \note 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(). @@ -3269,102 +3361,7 @@ H5_DLL herr_t H5Pget_core_write_tracking(hid_t fapl_id, hbool_t *is_enabled, siz * Valid driver identifiers distributed with HDF5 are listed and * described in the following table. * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - * - *
    Driver NameDriver IdentifierDescriptionRelated Function
    POSIX#H5FD_SEC2This 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.H5Pset_fapl_sec2()
    Direct#H5FD_DIRECTThis is the #H5FD_SEC2 driver except data is written to or - * read from the file synchronously without being cached by the - * system.H5Pset_fapl_direct()
    Log#H5FD_LOGThis is the #H5FD_SEC2 driver with logging capabilities.H5Pset_fapl_log()
    Windows#H5FD_WINDOWSThis driver was modified in HDF5-1.8.8 to be a wrapper of the - * POSIX driver, #H5FD_SEC2. This change should not affect user - * applications.H5Pset_fapl_windows()
    STDIO#H5FD_STDIOThis driver uses functions from the standard C stdio.h to - * perform I/O to a single, permanent file on local disk with - * additional system buffering.H5Pset_fapl_stdio()
    Memory#H5FD_COREWith 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. - * H5Pset_fapl_core()
    Family#H5FD_FAMILYWith 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. - * H5Pset_fapl_family()
    Multi#H5FD_MULTIWith this driver, data can be stored in multiple files - * according to the type of the data. I/O might work better if - * data is stored in separate files based on the type of data. - * The Split driver is a special case of this driver.H5Pset_fapl_multi()
    Parallel#H5FD_MPIOThis is the standard HDF5 file driver for parallel file - * systems. This driver uses the MPI standard for both - * communication and file I/O.H5Pset_fapl_mpio()
    Parallel POSIXH5FD_MPIPOSIXThis driver is no longer available.
    StreamH5FD_STREAMThis driver is no longer available.
    + * \snippet{doc} tables/fileDriverLists.dox supported_file_driver_table * * This list does not include custom drivers that might be * defined and registered by a user. @@ -3415,6 +3412,34 @@ H5_DLL hid_t H5Pget_driver(hid_t plist_id); * */ H5_DLL const void *H5Pget_driver_info(hid_t plist_id); +/** + * \ingroup FAPL + * + * \brief Retrieves a string representation of the configuration for + * the driver set on the given FAPL. The returned string can + * be used to configure the same driver in an identical way. + * + * \fapl_id + * \param[out] config_buf Driver configuration string output buffer + * \param[in] buf_size Size of driver configuration string output buffer + * + * \return Returns the length of the driver configuration string on + * success (not including the NUL terminator). Returns negative + * on failure. + * + * \details H5Pget_driver_config_str() retrieves a string representation + * of the configuration for the driver set on the given FAPL. The + * returned string can be used to configure the same driver in + * an identical way. + * + * If \p config_buf is NULL, the length of the driver configuration + * string is simply returned. The caller can then allocate a buffer + * of the appropriate size and call this routine again. + * + * \version 1.14.0 Function publicized in this release. + * + */ +H5_DLL ssize_t H5Pget_driver_config_str(hid_t fapl_id, char *config_buf, size_t buf_size); /** * \ingroup FAPL * @@ -3532,7 +3557,7 @@ H5_DLL herr_t H5Pget_fclose_degree(hid_t fapl_id, H5F_close_degree_t *degree); * 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 + * 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. * @@ -3854,13 +3879,13 @@ H5_DLL herr_t H5Pget_meta_block_size(hid_t fapl_id, hsize_t *size); * * 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. + * opened with SWMR access. * * \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. + * with non-SWMR access. * * \include H5Pget_metadata_read_attempts.3.c * @@ -3892,7 +3917,7 @@ H5_DLL herr_t H5Pget_metadata_read_attempts(hid_t plist_id, unsigned *attempts); * for more information. * * The type of data returned in \p type will be one of those - * listed in the discussion of the \p type parameter in the the + * listed in the discussion of the \p type parameter in the * description of the function H5Pset_multi_type(). * * Use of this function is only appropriate for an HDF5 file @@ -3965,7 +3990,7 @@ H5_DLL herr_t H5Pget_page_buffer_size(hid_t plist_id, size_t *buf_size, unsigned * \brief Returns maximum data sieve buffer size * * \fapl_id{fapl_id} - * \param[in] size Maximum size, in bytes, of data sieve buffer + * \param[out] size Maximum size, in bytes, of data sieve buffer * * \return \herr_t * @@ -4051,7 +4076,7 @@ H5_DLL herr_t H5Pget_vol_info(hid_t plist_id, void **vol_info); * \details H5Pset_alignment() sets the alignment properties of a * file access property list so that any file object greater * than or equal in size to \p threshold bytes will be aligned - * on an address which is a multiple of \p alignment. The + * on an address that is a multiple of \p alignment. The * addresses are relative to the end of the user block; the * alignment is calculated by subtracting the user block size * from the absolute file address and then adjusting the address @@ -4061,7 +4086,7 @@ H5_DLL herr_t H5Pget_vol_info(hid_t plist_id, void **vol_info); * implying no alignment. Generally the default values will * result in the best performance for single-process access to * the file. For MPI IO and other parallel systems, choose an - * alignment which is a multiple of the disk block size. + * alignment that is a multiple of the disk block size. * * If the file space handling strategy is set to * #H5F_FSPACE_STRATEGY_PAGE, then the alignment set via this @@ -4099,7 +4124,7 @@ H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignme * penalized when determining which chunks to flush * from cache. A value of 0 means fully read or * written chunks are treated no differently than - * other chunks (the preemption is strictly LRU) + * other chunks (the preemption is strictly LRU), * while a value of 1 means fully read or written * chunks are always preempted before other chunks. * If your application only reads or writes data once, @@ -4115,13 +4140,13 @@ H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignme * * \details H5Pset_cache() sets the number of elements, the total number of * bytes, and the preemption policy value for all datasets in a file - * on the file’s file access property list. + * on the file's file access property list. * * The raw data chunk cache inserts chunks into the cache by first * computing a hash value using the address of a chunk and then by - * using that hash value as the chunk’s index into the table of + * using that hash value as the chunk's index into the table of * cached chunks. In other words, the size of this hash table and the - * number of possible hash values is determined by the \p rdcc_nslots + * number of possible hash values are determined by the \p rdcc_nslots * parameter. If a different chunk in the cache has the same hash value, * a collision will occur, which will reduce efficiency. If inserting * the chunk into the cache would cause the cache to be too big, then @@ -4147,17 +4172,14 @@ H5_DLL herr_t H5Pset_alignment(hid_t fapl_id, hsize_t threshold, hsize_t alignme * * \note Note: Raw dataset chunk caching is not currently * supported when using the MPI I/O and MPI POSIX file drivers - * in read/write mode; see H5Pset_fapl_mpio() and - * H5Pset_fapl_mpiposix(), respectively. When using one of these - * file drivers, all calls to H5Dread() and H5Dwrite() will access + * in read/write mode; see H5Pset_fapl_mpio(). When using this + * file driver, all calls to H5Dread() and H5Dwrite() will access * the disk directly, and H5Pset_cache() will have no effect on * performance. * * \note Raw dataset chunk caching is supported when these drivers are * used in read-only mode. * - * \todo Check on H5Pset_fapl_mpio() and H5Pset_fapl_mpiposix(). - * * \version 1.8.0 The use of the \p mdc_nelmts parameter was discontinued. * Metadata cache configuration is managed with * H5Pset_mdc_config() and H5Pget_mdc_config(). @@ -4254,6 +4276,57 @@ 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 a file driver according to a given driver name + * + * \plist_id + * \param[in] driver_name The new driver name + * \param[in] driver_config Optional string containing driver properties + * + * \return \herr_t + * + * \details H5Pset_driver_by_name() sets the file driver, by the name + * driver_name, for a file access or data transfer property list, + * \p plist_id, and supplies an optional string containing the + * driver-specific properties, \p driver_config. The driver + * properties string will be copied into the property list. + * + * If the driver specified by \p driver_name is not currently + * registered, an attempt will be made to load the driver as a + * plugin. + * + * \version 1.14.0 Function publicized in this release. + * + */ +H5_DLL herr_t H5Pset_driver_by_name(hid_t plist_id, const char *driver_name, const char *driver_config); +/** + * \ingroup FAPL + * + * \brief Sets a file driver according to a given driver value (ID). + * + * \plist_id + * \param[in] driver_value The new driver value (ID) + * \param[in] driver_config Optional string containing driver properties + * + * \return \herr_t + * + * \details H5Pset_driver_by_value() sets the file driver, by the value + * driver_value, for a file access or data transfer property list, + * \p plist_id, and supplies an optional string containing the + * driver-specific properties, \p driver_config. The driver + * properties string will be copied into the property list. + * + * If the driver specified by \p driver_value is not currently + * registered, an attempt will be made to load the driver as a + * plugin. + * + * \version 1.14.0 Function publicized in this release. + * + */ +H5_DLL herr_t H5Pset_driver_by_value(hid_t plist_id, H5FD_class_value_t driver_value, + const char *driver_config); /** * \ingroup FAPL * @@ -4265,7 +4338,7 @@ H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id, const void *driver_ * The external link open file cache 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 + * accessed repeatedly and can significantly improves performance in * certain heavy-use situations and when low-level file opens or closes * are expensive. * @@ -4305,8 +4378,8 @@ H5_DLL herr_t H5Pset_driver(hid_t plist_id, hid_t driver_id, const void *driver_ * 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 + * 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 @@ -4548,7 +4621,7 @@ H5_DLL herr_t H5Pset_file_image(hid_t fapl_id, void *buf_ptr, size_t buf_len); * 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, + * 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. * @@ -4764,9 +4837,8 @@ H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); * enumerated value in #H5F_libver_t, indicating that this is * currently the latest format available. * - * The library supports the following five pairs of - * (\p low, \p high) combinations as derived from the values - * in #H5F_libver_t: + * The library supports the following pairs of (\p low, \p high) + * combinations as derived from the values in #H5F_libver_t: * * * @@ -4777,14 +4849,13 @@ H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); * * + * \li The library will create objects with the earliest + * possible format versions. + * \li The library will allow objects to be created 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. * * * + * \li API calls that create objects or features that are + * available to versions of the library greater than 1.10.x + * release will fail. + * + * + * + * + * + * + * + * * * * * + * + * + * + * + * + * + * + * + * + * + * + * * * * + * \p high=#H5F_LIBVER_V112 * + * + * + * + * + * + * + * + * + * objects created with this setting. + * + * + * + * + * + * + * + * * *
    \p low=#H5F_LIBVER_EARLIEST
    * \p high=#H5F_LIBVER_V18    		 - * \li The library will create objects with the earliest - * possible format versions. - * \li The library will allow objects to be created 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. - *
    \p low=#H5F_LIBVER_EARLIEST
    @@ -4794,13 +4865,33 @@ H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); * format versions. * \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. - * \li This is the library default setting and provides the greatest - * format compatibility. - *
    \p low=#H5F_LIBVER_EARLIEST
    + * \p high=#H5F_LIBVER_V112    		 + * \li The library will create objects with the earliest possible + * format versions. + * \li The library will allow objects to be created with the latest + * format versions available to library release 1.12.x. + * \li API calls that create objects or features that are + * available to versions of the library greater than 1.12.x + * release will fail.
    \p low=#H5F_LIBVER_EARLIEST
    + * \p high=#H5F_LIBVER_V114    		 + * \li The library will create objects with the earliest possible + * format versions. + * \li The library will allow objects to be created with the latest + * format versions available to library release 1.14.x. + * \li API calls that create objects or features that are + * available to versions of the library greater than 1.14.x + * release will fail.
    \p low=#H5F_LIBVER_V18
    @@ -4808,6 +4899,11 @@ H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); *     		* \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.8.x. + * \li The 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 API calls that create objects or features that are available * to versions of the library greater than 1.8.x release will * fail. @@ -4818,44 +4914,146 @@ H5_DLL herr_t H5Pset_gc_references(hid_t fapl_id, unsigned gc_ref); * \p low=#H5F_LIBVER_V18
    * \p high=#H5F_LIBVER_V110    		 + * \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. + * \li API calls that create objects or features that are + * available to versions of the library greater than 1.10.x + * release will fail. + * \li Earlier versions of the library may not be able to access + * objects created with this setting.
    \p low=#H5F_LIBVER_V18
    + * \p high=#H5F_LIBVER_V112    		 + * \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.12.x. + * \li API calls that create objects or features that are + * available to versions of the library greater than 1.12.x + * release will fail. + * \li Earlier versions of the library may not be able to access + * objects created with this setting.
    \p low=#H5F_LIBVER_V18
    + * \p high=#H5F_LIBVER_V114    		 + * \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.14.x. + * \li API calls that create objects or features that are + * available to versions of the library greater than 1.14.x + * release will fail. + * \li Earlier versions of the library may not be able to access + * objects created with this setting.
    \p low=#H5F_LIBVER_V110
    + * \p high=#H5F_LIBVER_V110    		 * \li The library will create objects with the latest format - * versions available to library release 1.8.x. + * 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. + * \li The 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 API calls that create objects or features that are available + * to versions of the library greater than 1.10.x release will + * fail. * \li Earlier versions of the library may not be able to access * objects created with this setting.
    \p low=#H5F_LIBVER_V110
    - * \p high=#H5F_LIBVER_V110 - *     		* \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. - * \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 + * format versions available to library release 1.12.x. + * \li API calls that create objects or features that are available + * to versions of the library greater than 1.12.x release will + * fail. + * \li Earlier versions of the library may not be able to access + * objects created with this setting.
    \p low=#H5F_LIBVER_V110
    + * \p high=#H5F_LIBVER_V114    		 + * \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.14.x. + * \li API calls that create objects or features that are available + * to versions of the library greater than 1.14.x release will + * fail. + * \li Earlier versions of the library may not be able to access + * objects created with this setting.
    \p low=#H5F_LIBVER_V112
    + * \p high=#H5F_LIBVER_V112    		 + * \li The library will create objects with the latest format + * versions available to library release 1.12.x. + * \li The library will allow objects to be created with the latest + * format versions available to library release 1.12.x. + * \li The 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 API calls that create objects or features that are available + * to versions of the library greater than 1.12.x release will + * fail. * \li Earlier versions of the library may not be able to access - * objects created with this - * setting. - *
    \p low=#H5F_LIBVER_V112
    + * \p high=#H5F_LIBVER_V114    		 + * \li The library will create objects with the latest format + * versions available to library release 1.12.x. + * \li The library will allow objects to be created with the latest + * format versions available to library release 1.14.x. + * \li API calls that create objects or features that are available + * to versions of the library greater than 1.14.x release will + * fail. + * \li Earlier versions of the library may not be able to access + * objects created with this setting.
    \p low=#H5F_LIBVER_V114
    + * \p high=#H5F_LIBVER_V114    		 + * \li The library will create objects with the latest format + * versions available to library release 1.14.x. + * \li The library will allow objects to be created with the latest + * format versions available to library release 1.14.x. + * \li The 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 API calls that create objects or features that are available + * to versions of the library greater than 1.14.x release will + * fail. + * \li Earlier versions of the library may not be able to access + * objects created with this setting.
    * + * \note *H5F_LIBVER_LATEST*:
    + * Since 1.14.x is also #H5F_LIBVER_LATEST, there is no upper + * limit on the format versions to use. That is, if a + * newer format version is required to support a feature + * in 1.14.x series, this setting will allow the object to be + * created. + * * \version 1.10.2 #H5F_LIBVER_V18 added to the enumerated defines in * #H5F_libver_t. * @@ -5206,11 +5404,39 @@ 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); +/** + * \ingroup FAPL + * + * \brief Query the capability flags for the VOL connector that will be used + * with this file access property list (FAPL). + * + * \fapl_id{plist_id} + * \param[out] cap_flags Flags that indicate the VOL connector capabilities + * + * \return \herr_t + * + * \details H5Pget_vol_cap_flags() queries the current VOL connector information + * for a FAPL to retrieve the capability flags for the VOL + * connector stack, as will be used by a file open or create + * operation that uses this FAPL. + * + * \note This routine supports the use of the HDF5_VOL_CONNECTOR environment + * variable to override the VOL connector set programmatically for the + * FAPL (with H5Pset_vol). + * + * \note The H5VL_CAP_FLAG_ASYNC flag can be checked to see if asynchronous + * operations are supported by the VOL connector stack. + * + * \since 1.14.0 + * + */ +H5_DLL herr_t H5Pget_vol_cap_flags(hid_t plist_id, uint64_t *cap_flags); + #ifdef H5_HAVE_PARALLEL /** - * \ingroup GACPL + * \ingroup GAPL * - * \brief Sets metadata I/O mode for read operations to collective or independent (default) + * \brief Sets metadata I/O mode for read operations to be collective or independent (default) * * \gacpl_id * \param[in] is_collective Boolean value indicating whether metadata reads are collective @@ -5241,7 +5467,7 @@ H5_DLL herr_t H5Pset_vol(hid_t plist_id, hid_t new_vol_id, const void *new_vol_i * 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. + * 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 @@ -5277,7 +5503,7 @@ H5_DLL herr_t H5Pset_vol(hid_t plist_id, hid_t new_vol_id, const void *new_vol_i */ H5_DLL herr_t H5Pset_all_coll_metadata_ops(hid_t plist_id, hbool_t is_collective); /** - * \ingroup GACPL + * \ingroup GAPL * * \brief Retrieves metadata read mode setting * @@ -5299,7 +5525,7 @@ H5_DLL herr_t H5Pget_all_coll_metadata_ops(hid_t plist_id, hbool_t *is_collectiv /** * \ingroup FAPL * - * \brief Sets metadata write mode to collective or independent (default) + * \brief Sets metadata write mode to be collective or independent (default) * * \fapl_id{plist_id} * \param[out] is_collective Boolean value indicating whether metadata @@ -5346,12 +5572,38 @@ H5_DLL herr_t H5Pset_coll_metadata_write(hid_t plist_id, hbool_t is_collective); H5_DLL herr_t H5Pget_coll_metadata_write(hid_t plist_id, hbool_t *is_collective); /** - * \todo Add missing documentation + * \ingroup FAPL + * + * \brief Get the MPI communicator and info + * + * \fapl_id + * \param[out] comm MPI communicator + * \param[out] info MPI info object + * \return \herr_t + * + * \details H5Pget_mpi_params() gets the MPI communicator and info stored in + * the file access property list \p fapl_id. + * + * \todo When was this introduced? + * */ H5_DLL herr_t H5Pget_mpi_params(hid_t fapl_id, MPI_Comm *comm, MPI_Info *info); /** - * \todo Add missing documentation + * \ingroup FAPL + * + * \brief Set the MPI communicator and info + * + * \fapl_id + * \param[in] comm MPI communicator + * \param[in] info MPI info object + * \return \herr_t + * + * \details H5Pset_mpi_params() sets the MPI communicator and info stored in + * the file access property list \p fapl_id. + * + * \todo When was this introduced? + * */ H5_DLL herr_t H5Pset_mpi_params(hid_t fapl_id, MPI_Comm comm, MPI_Info info); #endif /* H5_HAVE_PARALLEL */ @@ -5592,7 +5844,7 @@ H5_DLL herr_t H5Pget_chunk_opts(hid_t plist_id, unsigned *opts); * no dataset attributes hint setting for the dataset * creation property list \p dcpl_id. This setting is used to * inform the library to create minimized dataset object headers - * when TRUE. The setting value is returned in the boolean pointer + * when true. The setting value is returned in the boolean pointer * \p minimize. * * \since 1.10.5 @@ -5627,6 +5879,9 @@ H5_DLL herr_t H5Pget_dset_no_attrs_hint(hid_t dcpl_id, hbool_t *minimize); * are null pointers then the corresponding information is not * returned. * + * \note On Windows, off_t is typically a 32-bit signed long value, which + * limits the valid offset that can be returned to 2 GiB. + * * \version 1.6.4 \p idx parameter type changed to unsigned. * \since 1.0.0 * @@ -5688,7 +5943,7 @@ H5_DLL int H5Pget_external_count(hid_t plist_id); * \note H5Pget_fill_time() is designed to work in coordination with the * dataset fill value and dataset storage allocation time properties, * retrieved with the functions H5Pget_fill_value() and - * H5Pget_alloc_time(). + * H5Pget_alloc_time().type == H5FD_MEM_DRAW * * \since 1.6.0 * @@ -6049,12 +6304,12 @@ H5_DLL herr_t H5Pset_chunk(hid_t plist_id, int ndims, const hsize_t dim[/*ndims* * dataset creation property list \p dcpl_id. * * The available option is detailed in the parameters section. - * Only chunks that are not completely filled by the dataset’s + * Only chunks that are not completely filled by the dataset's * dataspace are affected by this option. Such chunks are * referred to as partial edge chunks. * * \b Motivation: H5Pset_chunk_opts() is used to specify storage - * options for chunks on the edge of a dataset’s dataspace. This + * options for chunks on the edge of a dataset's dataspace. This * capability allows the user to tune performance in cases where * the dataset size may not be a multiple of the chunk size and * the handling of partial edge chunks can impact performance. @@ -6078,13 +6333,13 @@ H5_DLL herr_t H5Pset_chunk_opts(hid_t plist_id, unsigned opts); * hint setting for the dataset creation property list \p dcpl_id. * Datasets created with the dataset creation property list * \p dcpl_id will have their object headers minimized if the - * boolean flag \p minimize is set to TRUE. By setting \p minimize - * to TRUE, the library expects that no attributes will be added + * boolean flag \p minimize is set to true. By setting \p minimize + * to true, the library expects that no attributes will be added * to the dataset. Attributes can be added, but they are appended * with a continuation message, which can reduce performance. * * This setting interacts with H5Fset_dset_no_attrs_hint(): if - * either is set to TRUE, then the created dataset's object header + * either is set to true, then the created dataset's object header * will be minimized. * * \since 1.10.5 @@ -6237,6 +6492,8 @@ H5_DLL herr_t H5Pset_fill_value(hid_t plist_id, hid_t type_id, const void *value * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_shuffle() sets the shuffle filter, #H5Z_FILTER_SHUFFLE, * in the dataset creation property list \p plist_id. The shuffle * filter de-interlaces a block of data by reordering the bytes. @@ -6308,6 +6565,8 @@ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_nbit() sets the N-Bit filter, #H5Z_FILTER_NBIT, in the * dataset creation property list \p plist_id. * @@ -6330,10 +6589,10 @@ H5_DLL herr_t H5Pset_layout(hid_t plist_id, H5D_layout_t layout); * byte 0 * * - * ???????? - * ????SPPP - * PPPPPPPP - * PPPP???? + * ???????? + * ????SPPP + * PPPPPPPP + * PPPP???? * * * Note: S - sign bit, P - significant bit, ? - padding bit; For @@ -6401,6 +6660,8 @@ H5_DLL herr_t H5Pset_nbit(hid_t plist_id); * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_scaleoffset() sets the scale-offset filter, * #H5Z_FILTER_SCALEOFFSET, for a dataset. * @@ -6510,6 +6771,8 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, * * \return \herr_t * + * \par_compr_note + * * \details H5Pset_szip() sets an SZIP compression filter, #H5Z_FILTER_SZIP, * for a dataset. SZIP is a compression method designed for use with * scientific data. @@ -6531,7 +6794,7 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, * Specifically, a dataset with a datatype that is 8-, 16-, 32-, or * 64-bit signed or unsigned integer; char; or 32- or 64-bit float * can be compressed with SZIP. See Note, below, for further - * discussion of the the SZIP \p bits_per_pixel setting. + * discussion of the SZIP \p bits_per_pixel setting. * * SZIP options are passed in an options mask, \p options_mask, * as follows. @@ -6593,7 +6856,7 @@ H5_DLL herr_t H5Pset_scaleoffset(hid_t plist_id, H5Z_SO_scale_type_t scale_type, * property list used to create a dataset containing a * non-allowed datatype, the call to H5Dcreate() will fail; the * conflict can be detected only when the property list is used. - * - Users should be aware that there are factors that affect one’s + * - Users should be aware that there are factors that affect one's * rights and ability to use SZIP compression by reviewing the * SZIP copyright notice. * @@ -6667,7 +6930,7 @@ H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels * \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 + * \param[in] src_space_id The source dataset's dataspace identifier with a * selection applied, possibly an unlimited selection * \return \herr_t * @@ -6702,7 +6965,7 @@ H5_DLL herr_t H5Pset_szip(hid_t plist_id, unsigned options_mask, unsigned pixels * * * 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. + * 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 @@ -6806,7 +7069,7 @@ H5_DLL herr_t H5Pset_virtual(hid_t dcpl_id, hid_t vspace_id, const char *src_fil * the corresponding value that is set in the property list. * * \p func is the user-defined callback function to invoke when - * a dataset’s appended dimension size reaches a boundary and + * a dataset's appended dimension size reaches a boundary and * \p udata is the user-defined input data for the callback * function. * @@ -6867,7 +7130,7 @@ H5_DLL herr_t H5Pget_chunk_cache(hid_t dapl_id, size_t *rdcc_nslots /*out*/, siz * \details H5Pget_efile_prefix() retrieves the file system path prefix * for locating external files associated with a dataset that * uses external storage. This will be the value set with - * H5Pset_efile_prefix() or the HDF5 library’s default. + * H5Pset_efile_prefix() or the HDF5 library's default. * * The value of \p size is the size in bytes of the prefix, * including the NULL terminator. If the size is unknown, a @@ -6955,9 +7218,6 @@ H5_DLL herr_t H5Pget_virtual_printf_gap(hid_t dapl_id, hsize_t *gap_size); * * \dapl_id * \param[out] view The flag specifying the view of the virtual dataset. - * Valid values are: - * \li #H5D_VDS_FIRST_MISSING - * \li #H5D_VDS_LAST_AVAILABLE * * \return \herr_t * @@ -6974,7 +7234,7 @@ H5_DLL herr_t H5Pget_virtual_view(hid_t dapl_id, H5D_vds_view_t *view); /** * \ingroup DAPL * - * \brief Sets two actions to perform when the size of a dataset’s + * \brief Sets two actions to perform when the size of a dataset's * dimension being appended reaches a specified boundary * * \dapl_id @@ -6995,7 +7255,7 @@ H5_DLL herr_t H5Pget_virtual_view(hid_t dapl_id, H5D_vds_view_t *view); * property list * * When a user is appending data to a dataset via H5DOappend() - * and the dataset’s newly extended dimension size hits a + * and the dataset's newly extended dimension size hits a * specified boundary, the library will perform the first action * listed above. Upon return from the callback function, the * library will then perform the second action listed above and @@ -7005,7 +7265,7 @@ H5_DLL herr_t H5Pget_virtual_view(hid_t dapl_id, H5D_vds_view_t *view); * The specified boundary is indicated by the parameter * \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 + * dataset's dataspace. While appending to a dataset along a * 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 @@ -7026,7 +7286,7 @@ H5_DLL herr_t H5Pget_virtual_view(hid_t dapl_id, H5D_vds_view_t *view); * create or open if the following conditions are true: * * \li \p ndims, the number of elements for boundary, is not the - * same as the rank of the dataset’s dataspace. + * same as the rank of the dataset's dataspace. * \li A non-zero boundary value is specified for a non-extendible * dimension. * @@ -7038,7 +7298,7 @@ H5_DLL herr_t H5Pget_virtual_view(hid_t dapl_id, H5D_vds_view_t *view); * prototype, are defined as follows: * * \li \p dataset_id is the dataset identifier. - * \li \p cur_dims is the dataset’s current dimension sizes when + * \li \p cur_dims is the dataset's current dimension sizes when * a boundary is hit. * \li \p user_data is the user-defined input data. * @@ -7190,19 +7450,19 @@ H5_DLL herr_t H5Pset_chunk_cache(hid_t dapl_id, size_t rdcc_nslots, size_t rdcc_ * that uses external storage: * * \li The default behavior of the library is to search for the - * dataset’s external storage raw data files in the same + * dataset's external storage raw data files in the same * directory as the HDF5 file which contains the dataset. * \li If the prefix is set to an absolute path, the target - * directory will be searched for the dataset’s external + * directory will be searched for the dataset's external * storage raw data files. * \li If the prefix is set to a relative path, the target * directory, relative to the current working directory, will - * be searched for the dataset’s external storage raw data + * be searched for the dataset's external storage raw data * files. * \li If the prefix is set to a relative path that begins with * the special token ${ORIGIN}, that directory, relative to * the HDF5 file containing the dataset, will be searched for - * the dataset’s external storage raw data files. + * the dataset's external storage raw data files. * * The HDF5_EXTFILE_PREFIX environment variable can be used to * override the above behavior (the environment variable @@ -7229,7 +7489,7 @@ H5_DLL herr_t H5Pset_chunk_cache(hid_t dapl_id, size_t rdcc_nslots, size_t rdcc_ * are unaware of the environment variable. * * \note On Windows, the prefix must be an ASCII string since the Windows - * standard C library’s I/O functions cannot handle UTF-8 file names. + * standard C library's I/O functions cannot handle UTF-8 file names. * * \since 1.10.0, 1.8.17 * @@ -7295,7 +7555,7 @@ H5_DLL herr_t H5Pset_virtual_prefix(hid_t dapl_id, const char *prefix); * then the virtual dataset will contain the data from * d-1, d-3, ..., d-N, ... . The blocks that are mapped to * d-2 and d-3 will be filled according to the virtual - * dataset’s fill value setting. + * dataset's fill value setting. * * \see_virtual * @@ -7311,11 +7571,7 @@ H5_DLL herr_t H5Pset_virtual_printf_gap(hid_t dapl_id, hsize_t gap_size); * * \dapl_id * \param[in] view Flag specifying the extent of the data to be included - * in the view. Valid values are: - * \li #H5D_VDS_FIRST_MISSING: View includes all data - * before the first missing mapped data - * \li #H5D_VDS_LAST_AVAILABLE View includes all - * available mapped data + * in the view. * * \return \herr_t * @@ -7326,7 +7582,7 @@ H5_DLL herr_t H5Pset_virtual_printf_gap(hid_t dapl_id, hsize_t gap_size); * If \p view is set to #H5D_VDS_FIRST_MISSING, the view includes * all data before the first missing mapped data. This setting * provides a view containing only the continuous data starting - * with the dataset’s first data element. Any break in + * with the dataset's first data element. Any break in * continuity terminates the view. * * If \p view is set to #H5D_VDS_LAST_AVAILABLE, the view @@ -7420,10 +7676,6 @@ H5_DLL size_t H5Pget_buffer(hid_t plist_id, void **tconv /*out*/, void **bkg /*o * If an error occurs, the buffer pointed to by \p expression is * 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 * */ @@ -7487,8 +7739,11 @@ H5_DLL herr_t H5Pget_hyper_vector_size(hid_t fapl_id, size_t *size /*out*/); * \details H5Pget_preserve() checks the status of the dataset transfer * property list. * + * \since 1.0.0 + * * \version 1.6.0 The flag parameter was changed from INTEGER to LOGICAL to * better match the C API. (Fortran 90) + * \version 1.8.2 Deprecated. * */ H5_DLL int H5Pget_preserve(hid_t plist_id); @@ -7516,6 +7771,8 @@ H5_DLL int H5Pget_preserve(hid_t plist_id); * * Please refer to the function H5Pset_type_conv_cb() for more details. * + * \since 1.8.0 + * */ H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, void **operate_data); /** @@ -7526,11 +7783,11 @@ H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, voi * * \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. + * \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 + * Extra parameter for user's free routine. Contents are ignored if preceding * parameter is NULL * * \return \herr_t @@ -7539,6 +7796,8 @@ H5_DLL herr_t H5Pget_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t *op, voi * H5Pset_vlen_mem_manager(), returning the parameters set by * that function. * + * \since 1.0.0 + * */ 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); @@ -7782,8 +8041,9 @@ H5_DLL herr_t H5Pset_hyper_vector_size(hid_t plist_id, size_t size); * 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? + * \since 1.0.0 + * + * \version 1.8.2 Deprecated. * */ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); @@ -7811,7 +8071,7 @@ H5_DLL herr_t H5Pset_preserve(hid_t plist_id, hbool_t status); * function prototype is as follows: * \snippet H5Tpublic.h H5T_conv_except_func_t_snip * - * \todo Add version information. + * \since 1.8.0 * */ H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void *operate_data); @@ -7861,7 +8121,8 @@ H5_DLL herr_t H5Pset_type_conv_cb(hid_t dxpl_id, H5T_conv_except_func_t op, void * set to \c NULL and the \p alloc_info and \p free_info parameters are * ignored. * - * \todo Add version information. + * \since 1.0.0 + * */ 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); @@ -7999,10 +8260,285 @@ H5_DLL herr_t H5Pget_mpio_actual_io_mode(hid_t plist_id, H5D_mpio_actual_io_mode 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 */ +/** + * + * \ingroup DXPL + * + * \brief Sets a hyperslab file selection for a dataset I/O operation + * + * \param[in] plist_id Property list identifier + * \param[in] rank Number of dimensions of selection + * \param[in] op Operation to perform on current selection + * \param[in] start Offset of start of hyperslab + * \param[in] stride Hyperslab stride + * \param[in] count Number of blocks included in hyperslab + * \param[in] block Size of block in hyperslab + * + * \return \herr_t + * + * \details H5Pset_dataset_io_hyperslab_selection() is designed to be used + * in conjunction with using #H5S_PLIST for the file dataspace + * ID when making a call to H5Dread() or H5Dwrite(). When used + * with #H5S_PLIST, the selection created by one or more calls to + * this routine is used for determining which dataset elements to + * access. + * + * \p rank is the dimensionality of the selection and determines + * the size of the \p start, \p stride, \p count, and \p block arrays. + * \p rank must be between 1 and #H5S_MAX_RANK, inclusive. + * + * The \p op, \p start, \p stride, \p count, and \p block parameters + * behave identically to their behavior for H5Sselect_hyperslab(), + * please see the documentation for that routine for details about + * their use. + * + * \since 1.14.0 + * + */ +H5_DLL herr_t H5Pset_dataset_io_hyperslab_selection(hid_t plist_id, unsigned rank, H5S_seloper_t op, + const hsize_t start[], const hsize_t stride[], + const hsize_t count[], const hsize_t block[]); -/* Link creation property list (LCPL) routines */ /** - * \ingroup ALCAPL + * + * \ingroup DXPL + * + * \brief Sets the selection I/O mode + * + * \dxpl_id{plist_id} + * \param[in] selection_io_mode The selection I/O mode to be set + * + * \return \herr_t + * + * \details H5Pset_selection_io() sets the selection I/O mode + * \p selection_io_mode in the dataset transfer property + * list \p plist_id. + * + * This can be used to enable collective I/O with type conversion, or + * with custom VFDs that support vector or selection I/O. + * + * Values that can be set in \p selection_io_mode: + * \snippet this H5D_selection_io_mode_t_snip + * \click4more + * + * \note The library may not perform selection I/O as it asks for if the + * layout callback determines that it is not feasible to do so. Please + * refer to H5Pget_no_selection_io_cause() for details. + * + * When used with type conversion, selection I/O requires the type + * conversion buffer (and the background buffer if applicable) be large + * enough to hold the entirety of the data involved in the I/O. For + * read operations, the library will use the application's read buffer + * as the type conversion buffer if the memory type is not smaller than + * the file type, eliminating the need for a separate type conversion + * buffer (a background buffer may still be required). For write + * operations, the library will similarly use the write buffer as a + * type conversion buffer, but only if H5Pset_modify_write_buf() is + * used to allow the library to modify the contents of the write + * buffer. + * + * \since 1.14.1 + * + */ +H5_DLL herr_t H5Pset_selection_io(hid_t plist_id, H5D_selection_io_mode_t selection_io_mode); + +/** + * + * \ingroup DXPL + * + * \brief Retrieves the selection I/O mode + * + * \dxpl_id{plist_id} + * \param[out] selection_io_mode The selection I/O mode + * + * \return \herr_t + * + * \details H5Pget_selection_io() queries the selection I/O mode set in + * in the dataset transfer property list \p plist_id. + * + * Values returned in \p selection_io_mode: + * \snippet this H5D_selection_io_mode_t_snip + * \click4more + * + * \note The library may not perform selection I/O as it asks for if the + * layout callback determines that it is not feasible to do so. Please + * refer to H5Pget_no_selection_io_cause() for details. + * + * \since 1.14.1 + * + */ +H5_DLL herr_t H5Pget_selection_io(hid_t plist_id, H5D_selection_io_mode_t *selection_io_mode); + +/** + * \ingroup DXPL + * + * \brief Retrieves the cause for not performing selection or vector I/O on the + * last parallel I/O call + * + * \dxpl_id{plist_id} + * \param[out] no_selection_io_cause A bitwise set value indicating the relevant + * causes that prevented selection I/O from + * being performed + * \return \herr_t + * + * \par Motivation: + * A user can request selection I/O to be performed via a data transfer + * property list (DXPL). This can be used to enable collective I/O with + * type conversion, or with custom VFDs that support vector or selection + * I/O. However, there are conditions that can cause HDF5 to forgo + * selection or vector I/O and perform legacy (scalar) I/O instead. + * + * \details H5Pget_no_selection_io_cause() can be used to determine whether + * selection or vector I/O was applied for the last preceding I/O call. + * If selection or vector I/O was not used, this function retrieves the + * cause(s) that prevent selection or vector I/O to be performed on + * that I/O call. The properties retrieved by this function are set + * before I/O takes place and are retained even when I/O fails. + * + * If a selection I/O request falls back to vector I/O, that is not + * considered "breaking" selection I/O by this function, since vector + * I/O still passes all information to the file driver in a single + * callback. + * + * Valid values returned in \p no_selection_io_cause are listed + * as follows. If there are multiple causes, it is a bitwise OR of + * the relevant causes. + * + * - #H5D_SEL_IO_DISABLE_BY_API + * Selection I/O was not performed because the feature was disabled by the API + * - #H5D_SEL_IO_NOT_CONTIGUOUS_OR_CHUNKED_DATASET + * Selection I/O was not performed because the dataset was neither contiguous nor chunked + * - #H5D_SEL_IO_CONTIGUOUS_SIEVE_BUFFER + * Selection I/O was not performed because of sieve buffer for contiguous dataset + * - #H5D_SEL_IO_NO_VECTOR_OR_SELECTION_IO_CB + * Selection I/O was not performed because the VFD does not have vector or selection I/O callback + * - #H5D_SEL_IO_PAGE_BUFFER + * Selection I/O was not performed because of page buffer + * - #H5D_SEL_IO_DATASET_FILTER + * Selection I/O was not performed because of dataset filters + * - #H5D_SEL_IO_CHUNK_CACHE + * Selection I/O was not performed because of chunk cache + * - #H5D_SEL_IO_TCONV_BUF_TOO_SMALL + * Selection I/O was not performed because the type conversion buffer is too small + * - #H5D_SEL_IO_BKG_BUF_TOO_SMALL + * Selection I/O was not performed because the type conversion background buffer is too small + * - #H5D_SEL_IO_DEFAULT_OFF + * Selection I/O was not performed because the selection I/O mode is DEFAULT and the library chose it + * to be off for this case + * + * \since 1.14.1 + * + */ +H5_DLL herr_t H5Pget_no_selection_io_cause(hid_t plist_id, uint32_t *no_selection_io_cause); + +/** + * \ingroup DXPL + * + * \brief Retrieves the type(s) of I/O that HDF5 actually performed on raw data + * during the last I/O call + * + * \dxpl_id{plist_id} + * \param[out] actual_selection_io_mode A bitwise set value indicating the + * type(s) of I/O performed + * \return \herr_t + * + * \par Motivation: + * A user can request selection I/O to be performed via a data transfer + * property list (DXPL). This can be used to enable collective I/O with + * type conversion, or with custom VFDs that support vector or selection + * I/O. However, there are conditions that can cause HDF5 to forgo + * selection or vector I/O and perform legacy (scalar) I/O instead. + * This function allows the user to determine which type or types of + * I/O were actually performed. + * + * \details H5Pget_actual_selection_io_mode() allows the user to determine which + * type(s) of I/O were actually performed on raw data during the last + * I/O operation which used \p plist_id. This property is set after + * all I/O is completed; if I/O fails, it will not be set. + * + * H5Pget_no_selection_io_cause() can be used to determine the reason + * why selection or vector I/O was not performed. + * + * Valid bitflags returned in \p actual_selection_io_mode are listed + * as follows. + * + * - #H5D_SCALAR_IO + * Scalar (or legacy MPIO) I/O was performed + * - #H5D_VECTOR_IO + * Vector I/O was performed + * - #H5D_SELECTION_IO + * Selection I/O was performed + * + * 0 or more of these can be present in \p actual_selection_io_mode in + * a bitwise fashion, since a single operation can trigger multiple + * instances of I/O, possibly with different types. A value of \p 0 + * indicates no raw data I/O was performed during the operation. + * + * Be aware that this function will only include raw data I/O performed + * to/from disk as part of the last I/O operation. Any metadata + * I/O, including attribute and compact dataset I/O, is disregarded. + * It is also possible that data was cached in the dataset chunk cache + * or sieve buffer, which may prevent I/O from hitting the disk, and + * thereby prevent it from being counted by this function. + * + * \since 1.14.3 + * + */ +H5_DLL herr_t H5Pget_actual_selection_io_mode(hid_t plist_id, uint32_t *actual_selection_io_mode); + +/** + * + * \ingroup DXPL + * + * \brief Allows the library to modify the contents of the write buffer + * + * \dxpl_id{plist_id} + * \param[in] modify_write_buf Whether the library can modify the contents of the write buffer + * + * \return \herr_t + * + * \details H5Pset_modify_write_buf() sets whether the library is allowed to + * modify the contents of write buffers passed to HDF5 API routines + * that are passed the dataset transfer property list \p plist_id. The + * default value for modify_write_buf is false. + * + * This function can be used to allow the library to perform in-place + * type conversion on write operations to save memory space. After making an + * API call with this parameter set to true, the contents of the write buffer + * are undefined. + * + * \note When modify_write_buf is set to true the library may violate the + * const qualifier on the API parameter for the write buffer. + * + * \since 1.14.1 + * + */ +H5_DLL herr_t H5Pset_modify_write_buf(hid_t plist_id, hbool_t modify_write_buf); + +/** + * + * \ingroup DXPL + * + * \brief Retrieves the "modify write buffer" property + * + * \dxpl_id{plist_id} + * \param[out] modify_write_buf Whether the library can modify the contents of the write buffer + * + * \return \herr_t + * + * \details H5Pget_modify_write_buf() gets the "modify write buffer" property + * from the dataset transfer property list \p plist_id. This property + * determines whether the library is allowed to modify the contents of + * write buffers passed to HDF5 API routines that are passed + * \p plist_id. The default value for modify_write_buf is false. + * + * \since 1.14.1 + * + */ +H5_DLL herr_t H5Pget_modify_write_buf(hid_t plist_id, hbool_t *modify_write_buf); + +/** + * \ingroup LCPL * * \brief Determines whether property is set to enable creating missing * intermediate groups @@ -8033,7 +8569,7 @@ H5_DLL herr_t H5Pget_mpio_no_collective_cause(hid_t plist_id, uint32_t *local_no */ H5_DLL herr_t H5Pget_create_intermediate_group(hid_t plist_id, unsigned *crt_intmd /*out*/); /** - * \ingroup ALCAPL + * \ingroup LCPL * * \brief Specifies in property list whether to create missing * intermediate groups @@ -8125,7 +8661,7 @@ H5_DLL herr_t H5Pget_link_creation_order(hid_t plist_id, unsigned *crt_order_fla * to require before converting a group to a dense form. * * In the compact format, links are stored as messages in the - * group’s header. In the dense format, links are stored in a + * group's header. In the dense format, links are stored in a * fractal heap and indexed with a version 2 B-tree. * * \p max_compact is the maximum number of links to store as @@ -8140,7 +8676,7 @@ H5_DLL herr_t H5Pget_link_creation_order(hid_t plist_id, unsigned *crt_order_fla * converted back to the compact format. * * In the compact format, links are stored as messages in the - * group’s header. In the dense format, links are stored in a + * group's header. In the dense format, links are stored in a * fractal heap and indexed with a version 2 B-tree. * * See H5Pset_link_phase_change() for a discussion of @@ -8336,7 +8872,7 @@ H5_DLL herr_t H5Pset_link_phase_change(hid_t plist_id, unsigned max_compact, uns * \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 + * 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 Group @@ -8358,7 +8894,7 @@ H5_DLL herr_t H5Pset_link_phase_change(hid_t plist_id, unsigned max_compact, uns * 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 + * 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. * @@ -8415,9 +8951,8 @@ H5_DLL herr_t H5Pget_map_iterate_hints(hid_t mapl_id, size_t *key_prefetch_size size_t *key_alloc_size /*out*/); #endif /* H5_HAVE_MAP_API */ -/* String creation property list (STRCPL) routines */ /** - * \ingroup ALCAPL + * \ingroup ACPL * * \brief Retrieves the character encoding used to create a link or * attribute name @@ -8446,7 +8981,7 @@ H5_DLL herr_t H5Pget_map_iterate_hints(hid_t mapl_id, size_t *key_prefetch_size */ H5_DLL herr_t H5Pget_char_encoding(hid_t plist_id, H5T_cset_t *encoding /*out*/); /** - * \ingroup ALCAPL + * \ingroup ACPL * * \brief Sets the character encoding used to encode link and attribute * names @@ -8487,7 +9022,6 @@ H5_DLL herr_t H5Pget_char_encoding(hid_t plist_id, H5T_cset_t *encoding /*out*/) */ H5_DLL herr_t H5Pset_char_encoding(hid_t plist_id, H5T_cset_t encoding); -/* Link access property list (LAPL) routines */ /** * \ingroup LAPL * @@ -8846,7 +9380,7 @@ H5_DLL herr_t H5Pset_nlinks(hid_t plist_id, size_t nlinks); /* Object copy property list (OCPYPL) routines */ /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Adds a path to the list of paths that will be searched in the * destination file for a matching committed datatype @@ -8884,7 +9418,7 @@ H5_DLL herr_t H5Pset_nlinks(hid_t plist_id, size_t nlinks); * must be identical. Two attributes are considered identical if * their datatype description, dataspace, and raw data values are * the same. However, if an attribute uses a committed datatype, - * that committed datatype’s attributes will not be compared. + * that committed datatype's attributes will not be compared. * * If a match is found, H5Ocopy() will perform the following in * the destination file: @@ -8894,7 +9428,7 @@ H5_DLL herr_t H5Pset_nlinks(hid_t plist_id, size_t nlinks); * will modify the copied dataset to use the found committed * datatype as its datatype. * \li For an object with an attribute of a committed datatype, - * the library will modify the copied object’s attribute to + * the library will modify the copied object's attribute to * use the found committed datatype as its datatype. * * If no match is found, H5Ocopy() will perform the following in @@ -8906,11 +9440,11 @@ H5_DLL herr_t H5Pset_nlinks(hid_t plist_id, size_t nlinks); * file by a unique path. * \li For a dataset that uses a committed datatype, the * library will copy the datatype as an anonymous - * committed datatype and use that as the dataset’s + * committed datatype and use that as the dataset's * datatype. * \li For an object with an attribute of a committed datatype, * the library will copy the datatype as an anonymous - * committed datatype and use that as the attribute’s + * committed datatype and use that as the attribute's * datatype. * * \b Motivation: H5Padd_merge_committed_dtype_path() provides a @@ -8961,7 +9495,7 @@ H5_DLL herr_t H5Pset_nlinks(hid_t plist_id, size_t nlinks); */ H5_DLL herr_t H5Padd_merge_committed_dtype_path(hid_t plist_id, const char *path); /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Clears the list of paths stored in the object copy property list * @@ -9012,7 +9546,7 @@ H5_DLL herr_t H5Padd_merge_committed_dtype_path(hid_t plist_id, const char *path */ H5_DLL herr_t H5Pfree_merge_committed_dtype_paths(hid_t plist_id); /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Retrieves the properties to be used when an object is copied * @@ -9037,7 +9571,7 @@ H5_DLL herr_t H5Pfree_merge_committed_dtype_paths(hid_t plist_id); */ H5_DLL herr_t H5Pget_copy_object(hid_t plist_id, unsigned *copy_options /*out*/); /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Retrieves the callback function from the specified object copy * property list @@ -9075,7 +9609,7 @@ H5_DLL herr_t H5Pget_copy_object(hid_t plist_id, unsigned *copy_options /*out*/) */ H5_DLL herr_t H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func, void **op_data); /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Sets properties to be used when an object is copied * @@ -9140,10 +9674,10 @@ H5_DLL herr_t H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func, * committed datatype. * If copied in a single H5Ocopy() operation, objects * that share a committed datatype in the source will - * share an anonymous committed dataype in the + * share an anonymous committed datatype in the * destination copy. Subsequent H5Ocopy() operations, * however, will be unaware of prior anonymous committed - * dataypes and will create new ones. + * datatypes and will create new ones. * * See the “See Also” section immediately below for * functions related to the use of this flag. @@ -9168,7 +9702,7 @@ H5_DLL herr_t H5Pget_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t *func, */ H5_DLL herr_t H5Pset_copy_object(hid_t plist_id, unsigned copy_options); /** - * \ingroup OCPPL + * \ingroup OCPYPL * * \brief Sets the callback function that H5Ocopy() will invoke before * searching the entire destination file for a matching committed @@ -9266,7 +9800,7 @@ H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, v /* Typedefs */ /** - * \ingroup GPLOA + * \ingroup PLCRA * * \brief Registers a permanent property with a property list class * @@ -9388,9 +9922,6 @@ H5_DLL herr_t H5Pset_mcdt_search_cb(hid_t plist_id, H5O_mcdt_search_cb_t func, v * The #H5P_prp_cb2_t is as follows: * \snippet this H5P_prp_cb2_t_snip * - * - * \cpp_c_api_note - * */ /* Function prototypes */ @@ -9399,7 +9930,7 @@ H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *de 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 + * \ingroup PLCRA * * \brief Registers a temporary property with a property list * @@ -9504,15 +10035,14 @@ H5_DLL herr_t H5Pregister1(hid_t cls_id, const char *name, size_t size, void *de * * 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 + * \ingroup PLCRA * * \brief Encodes the property values in a property list into a binary * buffer diff --git a/libs/windows/include/H5PredType.h b/libs/windows/include/H5PredType.h index b40d2b3..1e305fc 100644 --- a/libs/windows/include/H5PredType.h +++ b/libs/windows/include/H5PredType.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -29,7 +28,7 @@ class H5_DLLCPP PredType : public AtomType { public: ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("PredType"); } @@ -42,7 +41,7 @@ class H5_DLLCPP PredType : public AtomType { PredType(const PredType &original); // Noop destructor - virtual ~PredType(); + virtual ~PredType() override; /*! \brief This dummy function do not inherit from DataType - it will throw a DataTypeIException if invoked. @@ -176,63 +175,31 @@ class H5_DLLCPP PredType : public AtomType { static const PredType &NATIVE_INT64; static const PredType &NATIVE_UINT64; -// LEAST types -#if H5_SIZEOF_INT_LEAST8_T != 0 + // LEAST types static const PredType &NATIVE_INT_LEAST8; -#endif /* H5_SIZEOF_INT_LEAST8_T */ -#if H5_SIZEOF_UINT_LEAST8_T != 0 static const PredType &NATIVE_UINT_LEAST8; -#endif /* H5_SIZEOF_UINT_LEAST8_T */ -#if H5_SIZEOF_INT_LEAST16_T != 0 static const PredType &NATIVE_INT_LEAST16; -#endif /* H5_SIZEOF_INT_LEAST16_T */ -#if H5_SIZEOF_UINT_LEAST16_T != 0 static const PredType &NATIVE_UINT_LEAST16; -#endif /* H5_SIZEOF_UINT_LEAST16_T */ -#if H5_SIZEOF_INT_LEAST32_T != 0 static const PredType &NATIVE_INT_LEAST32; -#endif /* H5_SIZEOF_INT_LEAST32_T */ -#if H5_SIZEOF_UINT_LEAST32_T != 0 static const PredType &NATIVE_UINT_LEAST32; -#endif /* H5_SIZEOF_UINT_LEAST32_T */ -#if H5_SIZEOF_INT_LEAST64_T != 0 static const PredType &NATIVE_INT_LEAST64; -#endif /* H5_SIZEOF_INT_LEAST64_T */ -#if H5_SIZEOF_UINT_LEAST64_T != 0 static const PredType &NATIVE_UINT_LEAST64; -#endif /* H5_SIZEOF_UINT_LEAST64_T */ -// FAST types -#if H5_SIZEOF_INT_FAST8_T != 0 + // FAST types static const PredType &NATIVE_INT_FAST8; -#endif /* H5_SIZEOF_INT_FAST8_T */ -#if H5_SIZEOF_UINT_FAST8_T != 0 static const PredType &NATIVE_UINT_FAST8; -#endif /* H5_SIZEOF_UINT_FAST8_T */ -#if H5_SIZEOF_INT_FAST16_T != 0 static const PredType &NATIVE_INT_FAST16; -#endif /* H5_SIZEOF_INT_FAST16_T */ -#if H5_SIZEOF_UINT_FAST16_T != 0 static const PredType &NATIVE_UINT_FAST16; -#endif /* H5_SIZEOF_UINT_FAST16_T */ -#if H5_SIZEOF_INT_FAST32_T != 0 static const PredType &NATIVE_INT_FAST32; -#endif /* H5_SIZEOF_INT_FAST32_T */ -#if H5_SIZEOF_UINT_FAST32_T != 0 static const PredType &NATIVE_UINT_FAST32; -#endif /* H5_SIZEOF_UINT_FAST32_T */ -#if H5_SIZEOF_INT_FAST64_T != 0 static const PredType &NATIVE_INT_FAST64; -#endif /* H5_SIZEOF_INT_FAST64_T */ -#if H5_SIZEOF_UINT_FAST64_T != 0 static const PredType &NATIVE_UINT_FAST64; -#endif /* H5_SIZEOF_UINT_FAST64_T */ #ifndef DOXYGEN_SHOULD_SKIP_THIS @@ -378,64 +345,31 @@ class H5_DLLCPP PredType : public AtomType { static PredType *NATIVE_INT64_; static PredType *NATIVE_UINT64_; -// LEAST types -#if H5_SIZEOF_INT_LEAST8_T != 0 + // LEAST types static PredType *NATIVE_INT_LEAST8_; -#endif /* H5_SIZEOF_INT_LEAST8_T */ -#if H5_SIZEOF_UINT_LEAST8_T != 0 static PredType *NATIVE_UINT_LEAST8_; -#endif /* H5_SIZEOF_UINT_LEAST8_T */ -#if H5_SIZEOF_INT_LEAST16_T != 0 static PredType *NATIVE_INT_LEAST16_; -#endif /* H5_SIZEOF_INT_LEAST16_T */ -#if H5_SIZEOF_UINT_LEAST16_T != 0 static PredType *NATIVE_UINT_LEAST16_; -#endif /* H5_SIZEOF_UINT_LEAST16_T */ -#if H5_SIZEOF_INT_LEAST32_T != 0 static PredType *NATIVE_INT_LEAST32_; -#endif /* H5_SIZEOF_INT_LEAST32_T */ -#if H5_SIZEOF_UINT_LEAST32_T != 0 static PredType *NATIVE_UINT_LEAST32_; -#endif /* H5_SIZEOF_UINT_LEAST32_T */ -#if H5_SIZEOF_INT_LEAST64_T != 0 static PredType *NATIVE_INT_LEAST64_; -#endif /* H5_SIZEOF_INT_LEAST64_T */ -#if H5_SIZEOF_UINT_LEAST64_T != 0 static PredType *NATIVE_UINT_LEAST64_; -#endif /* H5_SIZEOF_UINT_LEAST64_T */ -// FAST types -#if H5_SIZEOF_INT_FAST8_T != 0 + // FAST types static PredType *NATIVE_INT_FAST8_; -#endif /* H5_SIZEOF_INT_FAST8_T */ -#if H5_SIZEOF_UINT_FAST8_T != 0 static PredType *NATIVE_UINT_FAST8_; -#endif /* H5_SIZEOF_UINT_FAST8_T */ -#if H5_SIZEOF_INT_FAST16_T != 0 static PredType *NATIVE_INT_FAST16_; -#endif /* H5_SIZEOF_INT_FAST16_T */ -#if H5_SIZEOF_UINT_FAST16_T != 0 static PredType *NATIVE_UINT_FAST16_; -#endif /* H5_SIZEOF_UINT_FAST16_T */ -#if H5_SIZEOF_INT_FAST32_T != 0 static PredType *NATIVE_INT_FAST32_; -#endif /* H5_SIZEOF_INT_FAST32_T */ -#if H5_SIZEOF_UINT_FAST32_T != 0 static PredType *NATIVE_UINT_FAST32_; -#endif /* H5_SIZEOF_UINT_FAST32_T */ -#if H5_SIZEOF_INT_FAST64_T != 0 static PredType *NATIVE_INT_FAST64_; -#endif /* H5_SIZEOF_INT_FAST64_T */ -#if H5_SIZEOF_UINT_FAST64_T != 0 static PredType *NATIVE_UINT_FAST64_; -#endif /* H5_SIZEOF_UINT_FAST64_T */ - // End of Declaration of pointers #endif // DOXYGEN_SHOULD_SKIP_THIS diff --git a/libs/windows/include/H5PropList.h b/libs/windows/include/H5PropList.h index 12c8b4b..beef474 100644 --- a/libs/windows/include/H5PropList.h +++ b/libs/windows/include/H5PropList.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -38,7 +37,7 @@ class H5_DLLCPP PropList : public IdComponent { bool operator==(const PropList &rhs) const; // Close this property list. - virtual void close(); + virtual void close() override; // Close a property list class. void closeClass() const; @@ -102,7 +101,7 @@ class H5_DLLCPP PropList : public IdComponent { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("PropList"); } @@ -114,10 +113,10 @@ class H5_DLLCPP PropList : public IdComponent { PropList(const PropList &original); // Gets the property list id. - virtual hid_t getId() const; + virtual hid_t getId() const override; // Destructor: properly terminates access to this property list. - virtual ~PropList(); + virtual ~PropList() override; #ifndef DOXYGEN_SHOULD_SKIP_THIS @@ -128,7 +127,7 @@ class H5_DLLCPP PropList : public IdComponent { hid_t id; // HDF5 property list id // Sets the property list id. - virtual void p_setId(const hid_t new_id); + virtual void p_setId(const hid_t new_id) override; private: static PropList *DEFAULT_; diff --git a/libs/windows/include/H5Rpublic.h b/libs/windows/include/H5Rpublic.h index e26a72c..3f63d59 100644 --- a/libs/windows/include/H5Rpublic.h +++ b/libs/windows/include/H5Rpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -17,10 +16,10 @@ #ifndef H5Rpublic_H #define H5Rpublic_H -/* Public headers needed by this file */ -#include "H5public.h" -#include "H5Gpublic.h" -#include "H5Ipublic.h" +#include "H5public.h" /* Generic Functions */ +#include "H5Gpublic.h" /* Groups */ +#include "H5Ipublic.h" /* Identifiers */ +#include "H5Opublic.h" /* Object Headers */ /*****************/ /* Public Macros */ @@ -30,9 +29,11 @@ #define H5R_OBJ_REF_BUF_SIZE sizeof(haddr_t) #define H5R_DSET_REG_REF_BUF_SIZE (sizeof(haddr_t) + 4) -/* Default reference buffer size. - * Note! Be careful with the sizes of the references because they should really - * depend on the run-time values in the file. +/** + * Default reference buffer size. + * + * \internal Note! Be careful with the sizes of the references because they + * should really depend on the run-time values in the file. */ #define H5R_REF_BUF_SIZE (64) @@ -258,7 +259,7 @@ H5_DLL herr_t H5Rdestroy(H5R_ref_t *ref_ptr); * \snippet this H5R_type_t_snip * * Note that #H5R_OBJECT1 and #H5R_DATASET_REGION1 can never be - * associated to an \ref H5R_ref_t reference and can therefore never be + * associated with an \ref H5R_ref_t reference and can, therefore, never be * returned through that function. * * \ref H5R_ref_t is defined in H5Rpublic.h as: @@ -301,7 +302,7 @@ H5_DLL htri_t H5Requal(const H5R_ref_t *ref1_ptr, const H5R_ref_t *ref2_ptr); * \return \herr_t * * \details H5Rcopy() creates a copy of an existing reference. - * \p src_ref_ptr points to the reference to copy and \p dst_ref_ptr is the + * \p src_ref_ptr points to the reference to copy, and \p dst_ref_ptr is the * pointer to the destination reference. * */ @@ -335,12 +336,25 @@ H5_DLL herr_t H5Rcopy(const H5R_ref_t *src_ref_ptr, H5R_ref_t *dst_ref_ptr); * * 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() + * the appropriate close function, such as H5Oclose() or H5Dclose() * for datasets. * */ H5_DLL hid_t H5Ropen_object(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Ropen_object} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Ropen_object_async(unsigned app_line, H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, + hid_t es_id); +#endif + /** * -------------------------------------------------------------------------- * \ingroup H5R @@ -374,6 +388,18 @@ H5_DLL hid_t H5Ropen_object(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); */ H5_DLL hid_t H5Ropen_region(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Ropen_region} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Ropen_region_async(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id, hid_t es_id); +#endif + /** * -------------------------------------------------------------------------- * \ingroup H5R @@ -404,6 +430,18 @@ H5_DLL hid_t H5Ropen_region(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t oapl_id); */ H5_DLL hid_t H5Ropen_attr(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id); +/** + * -------------------------------------------------------------------------- + * \ingroup ASYNC + * \async_variant_of{H5Ropen_attr} + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Ropen_attr_async(H5R_ref_t *ref_ptr, hid_t rapl_id, hid_t aapl_id, hid_t es_id); +#endif + /* Get type */ /** @@ -536,6 +574,23 @@ H5_DLL ssize_t H5Rget_obj_name(H5R_ref_t *ref_ptr, hid_t rapl_id, char *name, si */ H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t size); +/// \cond DEV +/* API Wrappers for async routines */ +/* (Must be defined _after_ the function prototype) */ +/* (And must only defined when included in application code, not the library) */ +#ifndef H5R_MODULE +#define H5Ropen_object_async(...) H5Ropen_object_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Ropen_region_async(...) H5Ropen_region_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Ropen_attr_async(...) H5Ropen_attr_async(__FILE__, __func__, __LINE__, __VA_ARGS__) + +/* Define "wrapper" versions of function calls, to allow compile-time values to + * be passed in by language wrapper or library layer on top of HDF5. */ +#define H5Ropen_object_async_wrap H5_NO_EXPAND(H5Ropen_object_async) +#define H5Ropen_region_async_wrap H5_NO_EXPAND(H5Ropen_region_async) +#define H5Ropen_attr_async_wrap H5_NO_EXPAND(H5Ropen_attr_async) +#endif /* H5R_MODULE */ +/// \endcond + /* Symbols defined for compatibility with previous versions of the HDF5 API. * * Use of these symbols is or will be deprecated. @@ -573,7 +628,7 @@ H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t siz * * 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 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 @@ -592,10 +647,10 @@ H5_DLL ssize_t H5Rget_attr_name(const H5R_ref_t *ref_ptr, char *name, size_t siz * 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. + * 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 + * 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. @@ -645,7 +700,7 @@ H5_DLL H5G_obj_t H5Rget_obj_type1(hid_t id, H5R_type_t ref_type, const void *ref * * 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 + * appropriate close function, such as H5Oclose() or H5Dclose() for * datasets. * * \version 1.10.0 Function H5Rdereference() renamed to H5Rdereference1() and @@ -729,10 +784,10 @@ H5_DLL herr_t H5Rcreate(void *ref, hid_t loc_id, const char *name, H5R_type_t re * 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. + * 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 + * 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. @@ -782,7 +837,7 @@ H5_DLL herr_t H5Rget_obj_type2(hid_t id, H5R_type_t ref_type, const void *ref, H * * 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 + * appropriate close function, such as H5Oclose() or H5Dclose() for * datasets. * * \since 1.10.0 @@ -850,7 +905,7 @@ H5_DLL hid_t H5Rget_region(hid_t dataset, H5R_type_t ref_type, const void *ref); * include the following: * \snippet this H5R_type_t_snip * - * \p ref is the reference for which the target object’s name is + * \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 diff --git a/libs/windows/include/H5Spublic.h b/libs/windows/include/H5Spublic.h index 331e5ee..2b6384f 100644 --- a/libs/windows/include/H5Spublic.h +++ b/libs/windows/include/H5Spublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -17,103 +16,130 @@ #ifndef H5Spublic_H #define H5Spublic_H -/* Public headers needed by this file */ -#include "H5public.h" -#include "H5Ipublic.h" +#include "H5public.h" /* Generic Functions */ +#include "H5Ipublic.h" /* Identifiers */ -/* Define atomic datatypes */ -#define H5S_ALL (hid_t)0 -#define H5S_UNLIMITED HSIZE_UNDEF +/* Define special dataspaces for dataset I/O operations */ -/* Define user-level maximum number of dimensions */ +/** + * Used with @ref H5Dread and @ref H5Dwrite to indicate that the entire + * dataspace will be selected. In the case of a file dataspace, this means + * that the entire file dataspace, as defined by the dataset's dimensions, + * will be selected. In the case of a memory dataspace, this means that + * the specified file dataspace will also be used for the memory dataspace. + * Used in place of a file or memory dataspace @ref hid_t value. + */ +#define H5S_ALL 0 + +/** + * Indicates that the buffer provided in a call to @ref H5Dread or @ref H5Dwrite + * is a single contiguous block of memory, with the same number of elements + * as the file dataspace. Used in place of a memory dataspace @ref hid_t value. + */ +#define H5S_BLOCK 1 + +/** + * Used with @ref H5Dread and @ref H5Dwrite to indicate that the file dataspace + * selection was set via @ref H5Pset_dataset_io_hyperslab_selection calls. + * Used in place of a file dataspace @ref hid_t value. + */ +#define H5S_PLIST 2 + +#define H5S_UNLIMITED HSIZE_UNDEF /**< Value for 'unlimited' dimensions */ + +/** + * The maximum dataspace rank or number of dimensions + */ #define H5S_MAX_RANK 32 /* Flags for selection iterators */ #define H5S_SEL_ITER_GET_SEQ_LIST_SORTED \ - 0x0001 /* Retrieve elements from iterator \ - * in increasing offset order, for \ - * each call to retrieve sequences. \ - * Currently, this only applies to \ - * point selections, as hyperslab \ - * selections are always returned \ - * in increasing offset order. \ - * \ - * Note that the order is only \ - * increasing for each call to \ - * get_seq_list, the next set of \ - * sequences could start with an \ - * earlier offset than the previous \ - * one. \ + 0x0001 /**< Retrieve elements from iterator in increasing offset order, for \ + * each call to retrieve sequences. Currently, this only applies to \ + * point selections, as hyperslab selections are always returned in \ + * increasing offset order. Note that the order is only increasing \ + * for each call to H5Sget_seq_list(), the next set of sequences \ + * could start with an earlier offset than the previous one. \ */ #define H5S_SEL_ITER_SHARE_WITH_DATASPACE \ - 0x0002 /* Don't copy the dataspace \ - * selection when creating the \ - * selection iterator. \ - * \ - * This can improve performance \ - * of creating the iterator, but \ - * the dataspace _MUST_NOT_ be \ - * modified or closed until the \ - * selection iterator is closed \ - * or the iterator's behavior \ - * will be undefined. \ + 0x0002 /**< Don't copy the dataspace selection when creating the selection \ + * iterator. This can improve performance of creating the iterator, \ + * but the dataspace \Bold{MUST NOT} be modified or closed until the \ + * selection iterator is closed or the iterator's behavior will be \ + * undefined. \ */ -/* Different types of dataspaces */ +/** + * Types of dataspaces + */ typedef enum H5S_class_t { - H5S_NO_CLASS = -1, /*error */ - H5S_SCALAR = 0, /*scalar variable */ - H5S_SIMPLE = 1, /*simple dataspace */ - H5S_NULL = 2 /*null dataspace */ + H5S_NO_CLASS = -1, /**< Error */ + H5S_SCALAR = 0, /**< Singleton (scalar) */ + H5S_SIMPLE = 1, /**< Regular grid */ + H5S_NULL = 2 /**< Empty set */ } H5S_class_t; -/* Different ways of combining selections */ +/** + * Different ways of combining selections + */ typedef enum H5S_seloper_t { - H5S_SELECT_NOOP = -1, /* error */ - H5S_SELECT_SET = 0, /* Select "set" operation */ - H5S_SELECT_OR, /* Binary "or" operation for hyperslabs + H5S_SELECT_NOOP = -1, /**< Error */ + H5S_SELECT_SET = 0, /**< Select "set" operation */ + H5S_SELECT_OR, /**< Binary "or" operation for hyperslabs * (add new selection to existing selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A or B: CCCCCCCCCCCCCCCC + * \endcode */ - H5S_SELECT_AND, /* Binary "and" operation for hyperslabs + H5S_SELECT_AND, /**< Binary "and" operation for hyperslabs * (only leave overlapped regions in selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A and B: CCCC + * \endcode */ - H5S_SELECT_XOR, /* Binary "xor" operation for hyperslabs + H5S_SELECT_XOR, /**< Binary "xor" operation for hyperslabs * (only leave non-overlapped regions in selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A xor B: CCCCCC CCCCCC + * \endcode */ - H5S_SELECT_NOTB, /* Binary "not" operation for hyperslabs + H5S_SELECT_NOTB, /**< Binary "not" operation for hyperslabs * (only leave non-overlapped regions in original selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * A not B: CCCCCC + * \endcode */ - H5S_SELECT_NOTA, /* Binary "not" operation for hyperslabs + H5S_SELECT_NOTA, /**< Binary "not" operation for hyperslabs * (only leave non-overlapped regions in new selection) + * \code * Original region: AAAAAAAAAA * New region: BBBBBBBBBB * B not A: CCCCCC + * \endcode */ - H5S_SELECT_APPEND, /* Append elements to end of point selection */ - H5S_SELECT_PREPEND, /* Prepend elements to beginning of point selection */ - H5S_SELECT_INVALID /* Invalid upper bound on selection operations */ + H5S_SELECT_APPEND, /**< Append elements to end of point selection */ + H5S_SELECT_PREPEND, /**< Prepend elements to beginning of point selection */ + H5S_SELECT_INVALID /**< Invalid upper bound on selection operations */ } H5S_seloper_t; -/* Enumerated type for the type of selection */ +/** + * Selection type + */ typedef enum { - H5S_SEL_ERROR = -1, /* Error */ - H5S_SEL_NONE = 0, /* Nothing selected */ - H5S_SEL_POINTS = 1, /* Points / elements selected */ - H5S_SEL_HYPERSLABS = 2, /* Hyperslab selected */ - H5S_SEL_ALL = 3, /* Entire extent selected */ - H5S_SEL_N /*THIS MUST BE LAST */ + H5S_SEL_ERROR = -1, /**< Error */ + H5S_SEL_NONE = 0, /**< Empty selection */ + H5S_SEL_POINTS = 1, /**< Set of points */ + H5S_SEL_HYPERSLABS = 2, /**< Hyperslab */ + H5S_SEL_ALL = 3, /**< Everything */ + H5S_SEL_N /**< Sentinel \internal THIS MUST BE LAST */ } H5S_sel_type; #ifdef __cplusplus @@ -858,9 +884,9 @@ H5_DLL hid_t H5Ssel_iter_create(hid_t spaceid, size_t elmt_size, unsigned flags) * * \space_id{sel_iter_id} * \param[in] maxseq Maximum number of sequences to retrieve - * \param[in] maxbytes Maximum number of bytes to retrieve in sequences + * \param[in] maxelmts Maximum number of elements to retrieve in sequences * \param[out] nseq Number of sequences retrieved - * \param[out] nbytes Number of bytes retrieved, in all sequences + * \param[out] nelmts Number of elements retrieved, in all sequences * \param[out] off Array of sequence offsets * \param[out] len Array of sequence lengths * @@ -877,9 +903,9 @@ H5_DLL hid_t H5Ssel_iter_create(hid_t spaceid, size_t elmt_size, unsigned flags) * #H5S_SEL_ITER_GET_SEQ_LIST_SORTED flag is passed to * H5Ssel_iter_create() for a point selection. * - * \p maxseq and \p maxbytes specify the most sequences or bytes + * \p maxseq and \p maxelmts specify the most sequences or elements * possible to place into the \p off and \p len arrays. \p nseq and - * \p nbytes return the actual number of sequences and bytes put + * \p nelmts return the actual number of sequences and elements put * into the arrays. * * Each call to H5Ssel_iter_get_seq_list() will retrieve the next @@ -891,13 +917,13 @@ H5_DLL hid_t H5Ssel_iter_create(hid_t spaceid, size_t elmt_size, unsigned flags) * the iterator was created from (which can be retrieved with * H5Sget_select_npoints(). When there are no further sequences of * elements to retrieve, calls to this routine will set \p nseq - * and \p nbytes to zero. + * and \p nelmts to zero. * * \since 1.12.0 * */ -H5_DLL herr_t H5Ssel_iter_get_seq_list(hid_t sel_iter_id, size_t maxseq, size_t maxbytes, size_t *nseq, - size_t *nbytes, hsize_t *off, size_t *len); +H5_DLL herr_t H5Ssel_iter_get_seq_list(hid_t sel_iter_id, size_t maxseq, size_t maxelmts, size_t *nseq, + size_t *nelmts, hsize_t *off, size_t *len); /** * \ingroup H5S * @@ -1000,7 +1026,7 @@ H5_DLL herr_t H5Sselect_copy(hid_t dst_id, hid_t src_id); * The \p coord parameter is a pointer to a buffer containing a * serialized 2-dimensional array of size \p num_elements by the * rank of the dataspace. The array lists dataset elements in the - * point selection; that is, it’s a list of of zero-based values + * point selection; that is, it's a list of zero-based values * specifying the coordinates in the dataset of the selected * elements. The order of the element coordinates in the \p coord * array specifies the order in which the array elements are @@ -1042,7 +1068,7 @@ H5_DLL herr_t H5Sselect_copy(hid_t dst_id, hid_t src_id); * * In the 1D case, we will be selecting five points and a 1D * dataspace has rank 1, so the selection will be described in a - * 5-by-1 array. To select the 1st, 14th, 17th, 23rd, 8th elements + * 5-by-1 array. To select the 1st, 14th, 17th, 23rd and 8th elements * of the dataset, the selection array would be as follows * (remembering that point coordinates are zero-based): * \n 0 @@ -1168,8 +1194,9 @@ H5_DLL herr_t H5Sselect_elements(hid_t space_id, H5S_seloper_t op, size_t num_el * 2x2 blocks of array elements starting with location (1,1) with the * selected blocks at locations (1,1), (5,1), (9,1), (1,5), (5,5), etc.; * in Fortran, they will specify a hyperslab consisting of 21 2x2 - * blocks of array elements starting with location (2,2) with the - * selected blocks at locations (2,2), (6,2), (10,2), (2,6), (6,6), etc. + * blocks of array elements starting with location (2,2), since \p start + * is 0-based indexed, with the selected blocks at + * locations (2,2), (6,2), (10,2), (2,6), (6,6), etc. * * Regions selected with this function call default to C order * iteration when I/O is performed. @@ -1314,21 +1341,14 @@ H5_DLL herr_t H5Sset_extent_none(hid_t space_id); * \details H5Sset_extent_simple() sets or resets the size of an existing * dataspace. * - * \p rank is the dimensionality, or number of dimensions, of the - * dataspace. - * - * \p dims is an array of size \p rank which contains the new size + * \p dims is an array of size \p rank that contains the new size * of each dimension in the dataspace. \p max is an array of size - * \p rank which contains the maximum size of each dimension in + * \p rank that contains the maximum size of each dimension in * the dataspace. * * Any previous extent is removed from the dataspace, the dataspace * type is set to #H5S_SIMPLE, and the extent is set as specified. * - * Note that a dataset must be chunked if \p dims does not equal - * \p max. - * - * * \version 1.4.0 Fortran subroutine was introduced. * \since 1.0.0 * diff --git a/libs/windows/include/H5StrType.h b/libs/windows/include/H5StrType.h index d272c53..ccae3e7 100644 --- a/libs/windows/include/H5StrType.h +++ b/libs/windows/include/H5StrType.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -42,7 +41,7 @@ class H5_DLLCPP StrType : public AtomType { // Returns an StrType object via DataType* by decoding the // binary object description of this type. - virtual DataType *decode() const; + virtual DataType *decode() const override; // Retrieves the character set type of this string datatype. H5T_cset_t getCset() const; @@ -58,7 +57,7 @@ class H5_DLLCPP StrType : public AtomType { ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("StrType"); } @@ -73,7 +72,7 @@ class H5_DLLCPP StrType : public AtomType { StrType(const StrType &original); // Noop destructor. - virtual ~StrType(); + virtual ~StrType() override; }; // end of StrType } // namespace H5 diff --git a/libs/windows/include/H5TBpublic.h b/libs/windows/include/H5TBpublic.h index 1750490..42585cf 100644 --- a/libs/windows/include/H5TBpublic.h +++ b/libs/windows/include/H5TBpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -18,6 +17,74 @@ extern "C" { #endif +/** \page H5TB_UG The HDF5 High Level Table + * @todo Under Construction + */ + +/**\defgroup H5TB HDF5 Table APIs (H5TB) + * + * Creating and manipulating HDF5 datasets intended to be + * interpreted as tables (H5TB) + * + * The HDF5 Table API defines a standard storage for HDF5 datasets + * that are intended to be interpreted as tables. A table is defined + * as a collection of records whose values are stored in fixed-length + * fields. All records have the same structure, and all values in + * each field have the same data type. + * + * \note \Bold{Programming hints:} + * \note To use any of these functions or subroutines, + * you must first include the relevant include file (C) or + * module (Fortran) in your application. + * \note The following line includes the HDF5 Table package, H5TB, + * in C applications: + * \code #include "hdf5_hl.h" \endcode + * \note To include the H5TB module in Fortran applications specify: + * \code use h5tb \endcode + * Fortran applications must also include \ref H5open before + * any HDF5 calls to initialize global variables and \ref H5close + * after all HDF5 calls to close the Fortran interface. + * + * + * + *
    + * + * - Creation + * - \ref H5TBmake_table + * - Storage + * - \ref H5TBappend_records (No Fortran) + * - \ref H5TBwrite_records (No Fortran) + * - \ref H5TBwrite_fields_name + * - \ref H5TBwrite_fields_index + * + * - Modification + * - \ref H5TBdelete_record (No Fortran) + * - \ref H5TBinsert_record (No Fortran) + * - \ref H5TBadd_records_from (No Fortran) + * - \ref H5TBcombine_tables (No Fortran) + * - \ref H5TBinsert_field + * - \ref H5TBdelete_field + * + * + * + * - Retrieval + * - \ref H5TBread_table + * - \ref H5TBread_records (No Fortran) + * - \ref H5TBread_fields_name + * - \ref H5TBread_fields_index + * + * - Query + * - \ref H5TBget_table_info + * - \ref H5TBget_field_info + * + * - Query Table Attributes + * - \ref H5TBAget_fill + * - \ref H5TBAget_title + * + *
    + * + */ + /*------------------------------------------------------------------------- * * Create functions @@ -25,6 +92,38 @@ extern "C" { *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Creates and writes a table + * + * \param[in] table_title The title of the table + * \fg_loc_id + * \param[in] dset_name The name of the dataset to create + * \param[in] nfields The number of fields + * \param[in] nrecords The number of records + * \param[in] type_size The size in bytes of the structure + * associated with the table; + * This value is obtained with \c sizeof(). + * \param[in] field_names An array containing the names of + * the fields + * \param[in] field_offset An array containing the offsets of + * the fields + * \param[in] field_types An array containing the type of + * the fields + * \param[in] chunk_size The chunk size + * \param[in] fill_data Fill values data + * \param[in] compress Flag that turns compression on or off + * \param[in] buf Buffer with data to be written to the table + * + * \return \herr_t + * + * \details H5TBmake_table() creates and writes a dataset named + * \p dset_name attached to the object specified by the + * identifier loc_id. + * + */ H5_HLDLL herr_t H5TBmake_table(const char *table_title, hid_t loc_id, const char *dset_name, hsize_t nfields, hsize_t nrecords, size_t type_size, const char *field_names[], const size_t *field_offset, const hid_t *field_types, hsize_t chunk_size, @@ -37,17 +136,128 @@ H5_HLDLL herr_t H5TBmake_table(const char *table_title, hid_t loc_id, const char *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Adds records to the end of the table + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to overwrite + * \param[in] nrecords The number of records to append + * \param[in] type_size The size of the structure type, + * as calculated by \c sizeof(). + * \param[in] field_offset An array containing the offsets of + * the fields. These offsets can be + * calculated with the #HOFFSET macro + * \param[in] dst_sizes An array containing the sizes of + * the fields + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBappend_records() adds records to the end of the table + * named \p dset_name attached to the object specified by the + * identifier \p loc_id. The dataset is extended to hold the + * new records. + * + */ H5_HLDLL herr_t H5TBappend_records(hid_t loc_id, const char *dset_name, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Overwrites records + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to overwrite + * \param[in] start The zero index record to start writing + * \param[in] nrecords The number of records to write + * \param[in] type_size The size of the structure type, as + * calculated by \c sizeof(). + * \param[in] field_offset An array containing the offsets of + * the fields. These offsets can be + * calculated with the #HOFFSET macro + * \param[in] dst_sizes An array containing the sizes of + * the fields + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBwrite_records() overwrites records starting at the zero + * index position start of the table named \p dset_name attached + * to the object specified by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBwrite_records(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Overwrites fields + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to overwrite + * \param[in] field_names The names of the fields to write + * \param[in] start The zero index record to start writing + * \param[in] nrecords The number of records to write + * \param[in] type_size The size of the structure type, as + * calculated by \c sizeof(). + * \param[in] field_offset An array containing the offsets of + * the fields. These offsets can be + * calculated with the #HOFFSET macro + * \param[in] dst_sizes An array containing the sizes of + * the fields + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBwrite_fields_name() overwrites one or several fields + * specified by \p field_names with data in \p buf from a + * dataset named \p dset_name attached to the object specified + * by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBwrite_fields_name(hid_t loc_id, const char *dset_name, const char *field_names, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, const void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Overwrites fields + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to overwrite + * \param[in] nfields The number of fields to overwrite. + * This parameter is also the size of the + * \p field_index array. + * \param[in] field_index The indexes of the fields to write + * \param[in] start The zero based index record to start writing + * \param[in] nrecords The number of records to write + * \param[in] type_size The size of the structure type, as + * calculated by \c sizeof(). + * \param[in] field_offset An array containing the offsets of + * the fields. These offsets can be + * calculated with the #HOFFSET macro + * \param[in] dst_sizes An array containing the sizes of + * the fields + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBwrite_fields_index() overwrites one or several fields + * specified by \p field_index with a buffer \p buf from a + * dataset named \p dset_name attached to the object + * specified by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBwrite_fields_index(hid_t loc_id, const char *dset_name, hsize_t nfields, const int *field_index, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, @@ -60,18 +270,128 @@ H5_HLDLL herr_t H5TBwrite_fields_index(hid_t loc_id, const char *dset_name, hsiz *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Reads a table + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[in] dst_size The size of the structure type, + * as calculated by \c sizeof() + * \param[in] dst_offset An array containing the offsets of + * the fields. These offsets can be + * calculated with the #HOFFSET macro + * \param[in] dst_sizes An array containing the sizes of + * the fields. These sizes can be + * calculated with the sizeof() macro. + * \param[in] dst_buf Buffer with data + * + * \return \herr_t + * + * \details H5TBread_table() reads a table named + * \p dset_name attached to the object specified by + * the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBread_table(hid_t loc_id, const char *dset_name, size_t dst_size, const size_t *dst_offset, const size_t *dst_sizes, void *dst_buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * \brief Reads one or several fields. The fields are identified by name. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[in] field_names An array containing the names of the + * fields to read + * \param[in] start The start record to read from + * \param[in] nrecords The number of records to read + * \param[in] type_size The size in bytes of the structure associated + * with the table + * (This value is obtained with \c sizeof().) + * \param[in] field_offset An array containing the offsets of the fields + * \param[in] dst_sizes An array containing the size in bytes of + * the fields + * \param[out] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBread_fields_name() reads the fields identified + * by \p field_names from a dataset named \p dset_name + * attached to the object specified by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBread_fields_name(hid_t loc_id, const char *dset_name, const char *field_names, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Reads one or several fields. The fields are identified by index. + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[in] nfields The number of fields to read + * (This parameter is also the size of the + * \p field_index array.) + * fields to read + * \param[in] field_index The indexes of the fields to read + * \param[in] start The start record to read from + * \param[in] nrecords The number of records to read + * \param[in] type_size The size in bytes of the structure associated + * with the table + * (This value is obtained with \c sizeof()) + * \param[in] field_offset An array containing the offsets of the fields + * \param[in] dst_sizes An array containing the size in bytes of + * the fields + * \param[out] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBread_fields_index() reads the fields identified + * by \p field_index from a dataset named \p dset_name attached + * to the object specified by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBread_fields_index(hid_t loc_id, const char *dset_name, hsize_t nfields, const int *field_index, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *field_offset, const size_t *dst_sizes, void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Reads records + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[in] start The start record to read from + * \param[in] nrecords The number of records to read + * \param[in] type_size The size of the structure type, + * as calculated by \c sizeof() + * \param[in] dst_offset An array containing the offsets of the + * fields. These offsets can be calculated + * with the #HOFFSET macro + * \param[in] dst_sizes An array containing the size in bytes of + * the fields + * \param[out] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBread_records() reads some records identified from a dataset + * named \p dset_name attached to the object specified by the + * identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBread_records(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t type_size, const size_t *dst_offset, const size_t *dst_sizes, void *buf); @@ -83,8 +403,52 @@ H5_HLDLL herr_t H5TBread_records(hid_t loc_id, const char *dset_name, hsize_t st *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Gets the table dimensions + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] nfields The number of fields + * \param[out] nrecords The number of records + * + * \return \herr_t + * + * \details H5TBget_table_info() retrieves the table dimensions from a + * dataset named \p dset_name attached to the object specified + * by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBget_table_info(hid_t loc_id, const char *dset_name, hsize_t *nfields, hsize_t *nrecords); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Gets information about a table + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset to read + * \param[out] field_names An array containing the names of the fields + * \param[out] field_sizes An array containing the size of the fields + * \param[out] field_offsets An array containing the offsets of the fields + * \param[out] type_size The size of the HDF5 datatype associated + * with the table. (More specifically, + * the size in bytes of the HDF5 compound + * datatype used to define a row, or record, + * in the table) + * + * \return \herr_t + * + * \details H5TBget_field_info() gets information about a dataset + * named \p dset_name attached to the object specified + * by the identifier \p loc_id. + * + */ H5_HLDLL herr_t H5TBget_field_info(hid_t loc_id, const char *dset_name, char *field_names[], size_t *field_sizes, size_t *field_offsets, size_t *type_size); @@ -95,21 +459,162 @@ H5_HLDLL herr_t H5TBget_field_info(hid_t loc_id, const char *dset_name, char *fi *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Delete records + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset + * \param[in] start The start record to delete from + * \param[in] nrecords The number of records to delete + * + * \return \herr_t + * + * \details H5TBdelete_record() deletes nrecords number of records starting + * from \p start from the middle of the table \p dset_name + * ("pulling up" all the records after it). + * + */ H5_HLDLL herr_t H5TBdelete_record(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Insert records + * + * \fg_loc_id + * \param[in] dset_name The name of the dataset + * \param[in] start The position to insert + * \param[in] nrecords The number of records to insert + * \param[in] dst_size The size in bytes of the structure + * associated with the table + * \param[in] dst_offset An array containing the offsets of the + * fields + * \param[in] dst_sizes An array containing the size in bytes of + * the fields + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBinsert_record() inserts records into the middle of the table + * ("pushing down" all the records after it) + * + */ H5_HLDLL herr_t H5TBinsert_record(hid_t loc_id, const char *dset_name, hsize_t start, hsize_t nrecords, size_t dst_size, const size_t *dst_offset, const size_t *dst_sizes, void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Add records from first table to second table + * + * \fg_loc_id + * \param[in] dset_name1 The name of the dataset to read the records + * \param[in] start1 The position to read the records from the + * first table + * \param[in] nrecords The number of records to read from the first + * table + * \param[in] dset_name2 The name of the dataset to write the records + * \param[in] start2 The position to write the records on the + * second table + * + * \return \herr_t + * + * \details H5TBadd_records_from() adds records from a dataset named + * \p dset_name1 to a dataset named \p dset_name2. Both tables + * are attached to the object specified by the identifier loc_id. + * + */ H5_HLDLL herr_t H5TBadd_records_from(hid_t loc_id, const char *dset_name1, hsize_t start1, hsize_t nrecords, const char *dset_name2, hsize_t start2); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Combines records from two tables into a third + * + * \param[in] loc_id1 Identifier of the file or group in which + * the first table is located + * \param[in] dset_name1 The name of the first table to combine + * \param[in] loc_id2 Identifier of the file or group in which + * the second table is located + * \param[in] dset_name2 The name of the second table to combine + * \param[in] dset_name3 The name of the new table + * + * \return \herr_t + * + * \details H5TBcombine_tables() combines records from two datasets named + * \p dset_name1 and \p dset_name2, to a new table named + * \p dset_name3. These tables can be located on different files, + * identified by \p loc_id1 and \p loc_id2 (identifiers obtained + * with H5Fcreate()). They can also be located on the same file. + * In this case one uses the same identifier for both parameters + * \p loc_id1 and \p loc_id2. If two files are used, the third + * table is written in the first file. + * + */ H5_HLDLL herr_t H5TBcombine_tables(hid_t loc_id1, const char *dset_name1, hid_t loc_id2, const char *dset_name2, const char *dset_name3); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Insert a new field into a table + * + * \fg_loc_id + * \param[in] dset_name The name of the table + * \param[in] field_name The name of the field to insert + * \param[in] field_type The data type of the field + * \param[in] position The zero based index position where to + * insert the field + * \param[in] fill_data Fill value data for the field. This parameter + * can be NULL + * \param[in] buf Buffer with data + * + * \return \herr_t + * + * \details H5TBinsert_field() inserts a new field named \p field_name into + * the table \p dset_name. Note: this function requires the table + * to be re-created and rewritten in its entirety, and this can result + * in some unused space in the file, and can also take a great deal of + * time if the table is large. + * + */ H5_HLDLL herr_t H5TBinsert_field(hid_t loc_id, const char *dset_name, const char *field_name, hid_t field_type, hsize_t position, const void *fill_data, const void *buf); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Deletes a field from a table + * + * \fg_loc_id + * \param[in] dset_name The name of the table + * \param[in] field_name The name of the field to delete + * + * \return \herr_t + * + * \details H5TBdelete_field() deletes a field named \p field_name from the + * table \p dset_name. Note: this function requires the table to be + * re-created and rewritten in its entirety, and this can result in + * some unused space in the file, and can also take a great deal of + * time if the table is large. + * + */ H5_HLDLL herr_t H5TBdelete_field(hid_t loc_id, const char *dset_name, const char *field_name); /*------------------------------------------------------------------------- @@ -119,8 +624,49 @@ H5_HLDLL herr_t H5TBdelete_field(hid_t loc_id, const char *dset_name, const char *------------------------------------------------------------------------- */ +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Reads a table's title + * + * \fg_loc_id + * \param[out] table_title Buffer for title name + * + * \return \herr_t + * + * \details H5TBget_title() returns the title of the table identified + * by \p loc_id in a buffer \p table_title. + * + */ H5_HLDLL herr_t H5TBAget_title(hid_t loc_id, char *table_title); +/** + * -------------------------------------------------------------------------- + * \ingroup H5TB + * + * + * \brief Reads the table attribute fill values + * + * \fg_loc_id + * \param[in] dset_name Name of table + * \param[in] dset_id Table identifier + * \param[out] dst_buf Buffer of fill values for table fields + * + * \return + * \return A return value of 1 indicates that a fill value is present. + * \return A return value of 0 indicates a fill value is not present. + * \return A return value <0 indicates an error. + * + * \details H5TBget_fill() reads the table attribute fill values into + * the buffer \p dst_buf for the table specified by \p dset_id + * and \p dset_name located in \p loc_id. + * + * \par Example + * \include H5TBAget_fill.c + * + */ H5_HLDLL htri_t H5TBAget_fill(hid_t loc_id, const char *dset_name, hid_t dset_id, unsigned char *dst_buf); #ifdef __cplusplus diff --git a/libs/windows/include/H5TSdevelop.h b/libs/windows/include/H5TSdevelop.h new file mode 100644 index 0000000..c3e1a6a --- /dev/null +++ b/libs/windows/include/H5TSdevelop.h @@ -0,0 +1,50 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * This file contains public declarations for the H5TS (threadsafety) developer + * support routines. + */ + +#ifndef H5TSdevelop_H +#define H5TSdevelop_H + +/*****************/ +/* Public Macros */ +/*****************/ + +/*******************/ +/* Public Typedefs */ +/*******************/ + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ + +#ifdef __cplusplus +extern "C" { +#endif + +/* HDF5 global library lock routines */ +H5_DLL herr_t H5TSmutex_acquire(unsigned int lock_count, bool *acquired); +H5_DLL herr_t H5TSmutex_release(unsigned int *lock_count); +H5_DLL herr_t H5TSmutex_get_attempt_count(unsigned int *count); + +#ifdef __cplusplus +} +#endif + +#endif /* H5TSdevelop_H */ diff --git a/libs/windows/include/H5Tdevelop.h b/libs/windows/include/H5Tdevelop.h new file mode 100644 index 0000000..e571741 --- /dev/null +++ b/libs/windows/include/H5Tdevelop.h @@ -0,0 +1,227 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * This file contains public declarations for the H5T (datatype) developer + * support routines. + */ + +#ifndef H5Tdevelop_H +#define H5Tdevelop_H + +/* Include package's public header */ +#include "H5Tpublic.h" + +/*****************/ +/* Public Macros */ +/*****************/ + +/*******************/ +/* Public Typedefs */ +/*******************/ + +/** + * Commands sent to conversion functions + */ +typedef enum H5T_cmd_t { + H5T_CONV_INIT = 0, /**< query and/or initialize private data */ + H5T_CONV_CONV = 1, /**< convert data from source to dest datatype */ + H5T_CONV_FREE = 2 /**< function is being removed from path */ +} H5T_cmd_t; + +/** + * How is the `bkg' buffer used by the conversion function? + */ +typedef enum H5T_bkg_t { + H5T_BKG_NO = 0, /**< background buffer is not needed, send NULL */ + H5T_BKG_TEMP = 1, /**< bkg buffer used as temp storage only */ + H5T_BKG_YES = 2 /**< init bkg buf with data before conversion */ +} H5T_bkg_t; + +/** + * Type conversion client data + */ +//! +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; +//! + +/** + * Conversion function persistence + */ +typedef enum H5T_pers_t { + H5T_PERS_DONTCARE = -1, /**< wild card */ + H5T_PERS_HARD = 0, /**< hard conversion function */ + H5T_PERS_SOFT = 1 /**< soft conversion function */ +} H5T_pers_t; + +/** + * All datatype conversion functions are... + */ +//! +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); +//! + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \ingroup CONV + * + * \brief Registers a datatype conversion function + * + * \param[in] pers Conversion function type + * \param[in] name Name displayed in diagnostic output + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * \param[in] func Function to convert between source and destination datatypes + * + * \return \herr_t + * + * \details H5Tregister() registers a hard or soft conversion function for a + * datatype conversion path. The parameter \p pers indicates whether a + * conversion function is hard (#H5T_PERS_HARD) or soft + * (#H5T_PERS_SOFT). User-defined functions employing compiler casting + * are designated as \Emph{hard}; other user-defined conversion + * functions registered with the HDF5 library (with H5Tregister() ) + * are designated as \Emph{soft}. The HDF5 library also has its own + * hard and soft conversion functions. + * + * A conversion path can have only one hard function. When type is + * #H5T_PERS_HARD, \p func replaces any previous hard function. + * + * When type is #H5T_PERS_SOFT, H5Tregister() adds the function to the + * end of the master soft list and replaces the soft function in all + * applicable existing conversion paths. Soft functions are used when + * determining which conversion function is appropriate for this path. + * + * The \p name is used only for debugging and should be a short + * identifier for the function. + * + * The path is specified by the source and destination datatypes \p + * src_id and \p dst_id. For soft conversion functions, only the class + * of these types is important. + * + * The type of the conversion function pointer is declared as: + * \snippet this H5T_conv_t_snip + * + * The \ref H5T_cdata_t \c struct is declared as: + * \snippet this H5T_cdata_t_snip + * + * \since 1.6.3 The following change occurred in the \ref H5T_conv_t function: + * the \c nelmts parameter type changed to size_t. + * + */ +H5_DLL herr_t H5Tregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func); +/** + * \ingroup CONV + * + * \brief Removes a conversion function + * + * \param[in] pers Conversion function type + * \param[in] name Name displayed in diagnostic output + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * \param[in] func Function to convert between source and destination datatypes + * + * \return \herr_t + * + * \details H5Tunregister() removes a conversion function matching criteria + * such as soft or hard conversion, source and destination types, and + * the conversion function. + * + * If a user is trying to remove a conversion function he registered, + * all parameters can be used. If he is trying to remove a library's + * default conversion function, there is no guarantee the \p name and + * \p func parameters will match the user's chosen values. Passing in + * some values may cause this function to fail. A good practice is to + * pass in NULL as their values. + * + * All parameters are optional. The missing parameters will be used to + * generalize the search criteria. + * + * The conversion function pointer type declaration is described in + * H5Tregister(). + * + * \version 1.6.3 The following change occurred in the \ref H5T_conv_t function: + * the \c nelmts parameter type changed to size_t. + * + */ +H5_DLL herr_t H5Tunregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func); +/** + * \ingroup CONV + * + * \brief Finds a conversion function + * + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * \param[out] pcdata Pointer to type conversion data + * + * \return Returns a pointer to a suitable conversion function if successful. + * Otherwise returns NULL. + * + * \details H5Tfind() finds a conversion function that can handle a conversion + * from type \p src_id to type \p dst_id. The \p pcdata argument is a + * pointer to a pointer to type conversion data which was created and + * initialized by the soft type conversion function of this path when + * the conversion function was installed on the path. + * + */ +H5_DLL H5T_conv_t H5Tfind(hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata); +/** + * \ingroup CONV + * + * \brief Check whether the library's default conversion is hard conversion + * + * \type_id{src_id} of source datatype + * \type_id{dst_id} of destination datatype + * + * \return \htri_t + * + * \details H5Tcompiler_conv() determines whether the library's conversion + * function from type \p src_id to type \p dst_id is a compiler (hard) + * conversion or not. A compiler conversion uses compiler's casting; a + * library (soft) conversion uses the library's own conversion + * function. + * + * \since 1.8.0 + * + */ +H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id); + +#ifdef __cplusplus +} +#endif + +/* Symbols defined for compatibility with previous versions of the HDF5 API. + * + * Use of these symbols is deprecated. + */ +#ifndef H5_NO_DEPRECATED_SYMBOLS + +#endif /* H5_NO_DEPRECATED_SYMBOLS */ + +#endif /* H5Tdevelop_H */ diff --git a/libs/windows/include/H5Tpublic.h b/libs/windows/include/H5Tpublic.h index b708506..1a16301 100644 --- a/libs/windows/include/H5Tpublic.h +++ b/libs/windows/include/H5Tpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -17,9 +16,8 @@ #ifndef H5Tpublic_H #define H5Tpublic_H -/* Public headers needed by this file */ -#include "H5public.h" -#include "H5Ipublic.h" +#include "H5public.h" /* Generic Functions */ +#include "H5Ipublic.h" /* Identifiers */ #define HOFFSET(S, M) (offsetof(S, M)) @@ -148,57 +146,18 @@ typedef enum H5T_pad_t { H5T_PAD_ONE = 1, /**< always set to one */ H5T_PAD_BACKGROUND = 2, /**< set to background value */ - H5T_NPAD = 3 /**< sentinal: THIS MUST BE LAST */ + H5T_NPAD = 3 /**< sentinel: THIS MUST BE LAST */ } H5T_pad_t; //! -/** - * Commands sent to conversion functions - */ -typedef enum H5T_cmd_t { - H5T_CONV_INIT = 0, /**< query and/or initialize private data */ - H5T_CONV_CONV = 1, /**< convert data from source to dest datatype */ - H5T_CONV_FREE = 2 /**< function is being removed from path */ -} H5T_cmd_t; - -/** - * How is the `bkg' buffer used by the conversion function? - */ -typedef enum H5T_bkg_t { - H5T_BKG_NO = 0, /**< background buffer is not needed, send NULL */ - H5T_BKG_TEMP = 1, /**< bkg buffer used as temp storage only */ - H5T_BKG_YES = 2 /**< init bkg buf with data before conversion */ -} H5T_bkg_t; - -/** - * Type conversion client data - */ -//! -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; -//! - -/** - * Conversion function persistence - */ -typedef enum H5T_pers_t { - H5T_PERS_DONTCARE = -1, /**< wild card */ - H5T_PERS_HARD = 0, /**< hard conversion function */ - H5T_PERS_SOFT = 1 /**< soft conversion function */ -} H5T_pers_t; - /** * The order to retrieve atomic native datatype */ //! 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_DIR_DEFAULT = 0, /**< default direction is ascending */ + H5T_DIR_ASCEND = 1, /**< in ascending order */ + H5T_DIR_DESCEND = 2 /**< in descending order */ } H5T_direction_t; //! @@ -237,7 +196,7 @@ typedef enum H5T_conv_ret_t { */ typedef struct { size_t len; /**< Length of VL data (in base type units) */ - void * p; /**< Pointer to VL data */ + void *p; /**< Pointer to VL data */ } hvl_t; /* Variable Length String information */ @@ -245,7 +204,7 @@ typedef struct { * Indicate that a string is variable length (null-terminated in C, instead of * fixed length) */ -#define H5T_VARIABLE ((size_t)(-1)) +#define H5T_VARIABLE SIZE_MAX /* Opaque information */ /** @@ -258,14 +217,6 @@ typedef struct { extern "C" { #endif -/** - * All datatype conversion functions are... - */ -//! -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); -//! - //! /** * \brief Exception handler. @@ -279,7 +230,7 @@ typedef herr_t (*H5T_conv_t)(hid_t src_id, hid_t dst_id, H5T_cdata_t *cdata, siz * \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 + * \details If an exception like overflow happens during conversion, this * function is called if it's registered through H5Pset_type_conv_cb(). * */ @@ -777,8 +728,7 @@ H5_DLLVAR hid_t H5T_VAX_F32_g; H5_DLLVAR hid_t H5T_VAX_F64_g; /* - * The predefined native types. These are the types detected by H5detect and - * they violate the naming scheme a little. Instead of a class name, + * The predefined native types for this platform. Instead of a class name, * precision and byte order as the last component, they have a C-like type * name. If the type begins with `U' then it is the unsigned version of the * integer type; other integer types are signed. The type LLONG corresponds @@ -850,13 +800,11 @@ H5_DLLVAR hid_t H5T_VAX_F64_g; * C-style \Code{double} */ #define H5T_NATIVE_DOUBLE (H5OPEN H5T_NATIVE_DOUBLE_g) -#if H5_SIZEOF_LONG_DOUBLE != 0 /** * \ingroup PDTNAT * C-style \Code{long double} */ #define H5T_NATIVE_LDOUBLE (H5OPEN H5T_NATIVE_LDOUBLE_g) -#endif /** * \ingroup PDTNAT * HDF5 8-bit bitfield based on native types @@ -919,9 +867,7 @@ H5_DLLVAR hid_t H5T_NATIVE_LLONG_g; H5_DLLVAR hid_t H5T_NATIVE_ULLONG_g; H5_DLLVAR hid_t H5T_NATIVE_FLOAT_g; H5_DLLVAR hid_t H5T_NATIVE_DOUBLE_g; -#if H5_SIZEOF_LONG_DOUBLE != 0 H5_DLLVAR hid_t H5T_NATIVE_LDOUBLE_g; -#endif H5_DLLVAR hid_t H5T_NATIVE_B8_g; H5_DLLVAR hid_t H5T_NATIVE_B16_g; H5_DLLVAR hid_t H5T_NATIVE_B32_g; @@ -1087,7 +1033,7 @@ H5_DLLVAR hid_t H5T_NATIVE_UINT_FAST64_g; * When creating a fixed-length string datatype, \p size will * be the length of the string in bytes. The length of the * string in characters will depend on i the encoding used; see - * H5Pset_char_encoding(). + * #H5Pset_char_encoding. * * ENUMs created with this function have a signed native integer * base datatype. Use H5Tenum_create() if a different integer base @@ -1121,7 +1067,7 @@ H5_DLL hid_t H5Tcreate(H5T_class_t type, size_t size); * dataset's datatype. * * The returned datatype identifier should be released with H5Tclose() - * to prevent resource leak. + * to prevent resource leaks. * */ H5_DLL hid_t H5Tcopy(hid_t type_id); @@ -1140,6 +1086,18 @@ H5_DLL hid_t H5Tcopy(hid_t type_id); * */ H5_DLL herr_t H5Tclose(hid_t type_id); +/** + * \ingroup H5T + * + * \brief Asynchronous version of H5Tclose(). + * + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL herr_t H5Tclose_async(hid_t type_id, hid_t es_id); +#endif /** * \ingroup H5T * @@ -1182,7 +1140,7 @@ H5_DLL herr_t H5Tlock(hid_t type_id); * * \fg_loc_id * \param[in] name Name given to committed datatype - * \type_id Identifier of datatype to be committed and, upon function’s + * \type_id Identifier of datatype to be committed and, upon function's * return, identifier for the committed datatype * \lcpl_id * \tcpl_id @@ -1198,13 +1156,13 @@ H5_DLL herr_t H5Tlock(hid_t type_id); * * \p loc_id may be a file identifier, or a group identifier within * that file. \p name may be either an absolute path in the file or - * a relative path from \p loc_id naming the newly-commited datatype. + * a relative path from \p loc_id naming the newly-committed datatype. * * The link creation property list, \p lcpl_id, governs creation of * the link(s) by which the new committed datatype is accessed and * the creation of any intermediate groups that may be missing. * - * Once commited, this datatype may be used to define the datatype + * Once committed, this datatype may be used to define the datatype * of any other dataset or attribute in the file. * * This function will not accept a datatype that cannot actually hold @@ -1214,7 +1172,7 @@ H5_DLL herr_t H5Tlock(hid_t type_id); * Committed datatypes are sometimes referred to as named datatypes. * * \version 1.8.7 Function modified in this release to reject datatypes that - * will not accomodate actual data, such as a compound datatype + * will not accommodate actual data, such as a compound datatype * with no fields or an enumerated datatype with no members. * * \since 1.8.0 @@ -1222,6 +1180,20 @@ H5_DLL herr_t H5Tlock(hid_t type_id); */ H5_DLL herr_t H5Tcommit2(hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id); +/** + * \ingroup H5T + * + * \brief Asynchronous version of H5Tcommit2(). + * + */ +#ifndef H5_DOXYGEN +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, + hid_t es_id); +#else +H5_DLL herr_t H5Tcommit_async(hid_t loc_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, + hid_t tapl_id, hid_t es_id); +#endif /** * -------------------------------------------------------------------------- * \ingroup H5T @@ -1249,7 +1221,19 @@ H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id); /** * \ingroup H5T * - * \brief Commits a transient datatype to a file, creating a new named + * \brief Asynchronous version of H5Topen2(). + * + */ +#ifndef H5_DOXYGEN +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); +#else +H5_DLL hid_t H5Topen_async(hid_t loc_id, const char *name, hid_t tapl_id, hid_t es_id); +#endif +/** + * \ingroup H5T + * + * \brief Commits a transient datatype to a file, creating a newly named * datatype, but does not link it into the file structure * * \fg_loc_id @@ -1282,7 +1266,7 @@ H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id); * which provides for greater control of the creation process * and of the properties of the new named datatype. H5Tcommit() * always uses default properties. - * \li H5Tcommit_anon() neither provides the new named datatype’s + * \li H5Tcommit_anon() neither provides the new named datatype's * name nor links it into the HDF5 file structure; those actions * must be performed separately through a call to H5Olink(), * which offers greater control over linking. @@ -1292,7 +1276,7 @@ H5_DLL hid_t H5Topen2(hid_t loc_id, const char *name, hid_t tapl_id); * fields and enumerated datatypes with no members. * * \version 1.8.7 Function modified in this release to reject datatypes that - * will not accomodate actual data, such as a compound datatype + * will not accommodate actual data, such as a compound datatype * with no fields or an enumerated datatype with no members. * * \since 1.2.0 @@ -1379,7 +1363,7 @@ H5_DLL herr_t H5Tencode(hid_t obj_id, void *buf, size_t *nalloc); /** * \ingroup H5T * - * \brief Decodes a binary object description of datatype and return a new + * \brief Decodes a binary object description of datatype and returns a new * object handle * * \param[in] buf Buffer for the datatype object to be decoded @@ -1451,7 +1435,7 @@ H5_DLL herr_t H5Tflush(hid_t type_id); * contents from disk. * * This function essentially closes the datatype, evicts all - * metadata associated with it from the cache, and then re-opens the + * metadata associated with it from the cache, and then reopens the * datatype. The reopened datatype is automatically re-registered * with the same identifier. * @@ -1601,7 +1585,7 @@ H5_DLL herr_t H5Tenum_nameof(hid_t type, const void *value, char *name /*out*/, * \details H5Tenum_valueof() finds the value that corresponds to the * specified name of the enumeration datatype \p dtype_id. * - * Values returned in \p value will be of the enumerated type’s + * Values returned in \p value will be of the enumerated type's * base type, that is, the datatype used by H5Tenum_create() when * the enumerated type was created. * @@ -2065,7 +2049,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 ENUM + * \ingroup COMPENUM * * \brief Retrieves the number of elements in a compound or enumeration datatype * @@ -2082,7 +2066,7 @@ H5_DLL H5T_str_t H5Tget_strpad(hid_t type_id); */ H5_DLL int H5Tget_nmembers(hid_t type_id); /** - * \ingroup COMPOUND ENUM + * \ingroup COMPENUM * * \brief Retrieves the name of a compound or enumeration datatype member * @@ -2109,7 +2093,7 @@ H5_DLL int H5Tget_nmembers(hid_t type_id); */ H5_DLL char *H5Tget_member_name(hid_t type_id, unsigned membno); /** - * \ingroup COMPOUND ENUM + * \ingroup COMPENUM * * \brief Retrieves the index of a compound or enumeration datatype member * @@ -2212,7 +2196,7 @@ H5_DLL hid_t H5Tget_member_type(hid_t type_id, unsigned membno); * * The member value is returned in a user-supplied buffer pointed to * by \p value. Values returned in \p value will be of the enumerated - * type’s base type, that is, the datatype used by H5Tenum_create() + * type's base type, that is, the datatype used by H5Tenum_create() * when the enumerated type was created. * * The value buffer must be at least large enough to hold a value @@ -2277,7 +2261,7 @@ H5_DLL htri_t H5Tis_variable_str(hid_t type_id); * \details H5Tget_native_type() returns the equivalent native datatype * identifier for the datatype specified by \p type_id. * - * H5Tget_native_type() is designed primarily to facilitate use of + * H5Tget_native_type() is designed primarily to facilitate the use of * the H5Dread() function, for which users otherwise must undertake a * multi-step process to determine the native datatype of a dataset * prior to reading it into memory. This function can be used for @@ -2335,7 +2319,7 @@ H5_DLL htri_t H5Tis_variable_str(hid_t type_id); * * \note Please note that a datatype is actually an object * identifier or handle returned from opening the datatype. It - * is not persistent and its value can be different from one HDF5 + * is not persistent, and its value can be different from one HDF5 * session to the next. * * \note H5Tequal() can be used to compare datatypes. @@ -2356,14 +2340,14 @@ H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction); * \brief Sets size for a datatype. * * \type_id - * \param[in] size New datatype size is bytes or #H5T_VARIABLE + * \param[in] size New datatype size in bytes or #H5T_VARIABLE * * \return \herr_t * * \details H5Tset_size() sets the total size, \p size, in bytes, for a * datatype. * - * \p size must have a positive value, unless it is passed in as + * \p size must have a positive value unless it is passed in as * #H5T_VARIABLE and the datatype is a string datatype. * * \li Numeric datatypes: If the datatype is atomic and the size @@ -2375,7 +2359,7 @@ H5_DLL hid_t H5Tget_native_type(hid_t type_id, H5T_direction_t direction); * * \li String or character datatypes: The size set for a string * datatype should include space for the null-terminator character, - * otherwise it will not be stored on (or retrieved from) + * otherwise it will not be stored on (or retrieved from) the * disk. Adjusting the size of a string automatically sets the * precision to \p 8*size. * @@ -2685,130 +2669,6 @@ H5_DLL herr_t H5Tset_cset(hid_t type_id, H5T_cset_t cset); */ H5_DLL herr_t H5Tset_strpad(hid_t type_id, H5T_str_t strpad); -/* Type conversion database */ -/** - * \ingroup CONV - * - * \brief Registers a datatype conversion function - * - * \param[in] pers Conversion function type - * \param[in] name Name displayed in diagnostic output - * \type_id{src_id} of source datatype - * \type_id{dst_id} of destination datatype - * \param[in] func Function to convert between source and destination datatypes - * - * \return \herr_t - * - * \details H5Tregister() registers a hard or soft conversion function for a - * datatype conversion path. The parameter \p pers indicates whether a - * conversion function is hard (#H5T_PERS_HARD) or soft - * (#H5T_PERS_SOFT). User-defined functions employing compiler casting - * are designated as \Emph{hard}; other user-defined conversion - * functions registered with the HDF5 library (with H5Tregister() ) - * are designated as \Emph{soft}. The HDF5 library also has its own - * hard and soft conversion functions. - * - * A conversion path can have only one hard function. When type is - * #H5T_PERS_HARD, \p func replaces any previous hard function. - * - * When type is #H5T_PERS_SOFT, H5Tregister() adds the function to the - * end of the master soft list and replaces the soft function in all - * applicable existing conversion paths. Soft functions are used when - * determining which conversion function is appropriate for this path. - * - * The \p name is used only for debugging and should be a short - * identifier for the function. - * - * The path is specified by the source and destination datatypes \p - * src_id and \p dst_id. For soft conversion functions, only the class - * of these types is important. - * - * The type of the conversion function pointer is declared as: - * \snippet this H5T_conv_t_snip - * - * The \ref H5T_cdata_t \c struct is declared as: - * \snippet this H5T_cdata_t_snip - * - * \since 1.6.3 The following change occurred in the \ref H5T_conv_t function: - * the \c nelmts parameter type changed to size_t. - * - */ -H5_DLL herr_t H5Tregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func); -/** - * \ingroup CONV - * - * \brief Removes a conversion function - * - * \param[in] pers Conversion function type - * \param[in] name Name displayed in diagnostic output - * \type_id{src_id} of source datatype - * \type_id{dst_id} of destination datatype - * \param[in] func Function to convert between source and destination datatypes - * - * \return \herr_t - * - * \details H5Tunregister() removes a conversion function matching criteria - * such as soft or hard conversion, source and destination types, and - * the conversion function. - * - * If a user is trying to remove a conversion function he registered, - * all parameters can be used. If he is trying to remove a library’s - * default conversion function, there is no guarantee the \p name and - * \p func parameters will match the user’s chosen values. Passing in - * some values may cause this function to fail. A good practice is to - * pass in NULL as their values. - * - * All parameters are optional. The missing parameters will be used to - * generalize the search criteria. - * - * The conversion function pointer type declaration is described in - * H5Tregister(). - * - * \version 1.6.3 The following change occurred in the \ref H5T_conv_t function: - * the \c nelmts parameter type changed to size_t. - * - */ -H5_DLL herr_t H5Tunregister(H5T_pers_t pers, const char *name, hid_t src_id, hid_t dst_id, H5T_conv_t func); -/** - * \ingroup CONV - * - * \brief Finds a conversion function - * - * \type_id{src_id} of source datatype - * \type_id{dst_id} of destination datatype - * \param[out] pcdata Pointer to type conversion data - * - * \return Returns a pointer to a suitable conversion function if successful. - * Otherwise returns NULL. - * - * \details H5Tfind() finds a conversion function that can handle a conversion - * from type \p src_id to type \p dst_id. The \p pcdata argument is a - * pointer to a pointer to type conversion data which was created and - * initialized by the soft type conversion function of this path when - * the conversion function was installed on the path. - * - */ -H5_DLL H5T_conv_t H5Tfind(hid_t src_id, hid_t dst_id, H5T_cdata_t **pcdata); -/** - * \ingroup CONV - * - * \brief Check whether the library’s default conversion is hard conversion - * - * \type_id{src_id} of source datatype - * \type_id{dst_id} of destination datatype - * - * \return \htri_t - * - * \details H5Tcompiler_conv() determines whether the library’s conversion - * function from type \p src_id to type \p dst_id is a compiler (hard) - * conversion or not. A compiler conversion uses compiler’s casting; a - * library (soft) conversion uses the library’s own conversion - * function. - * - * \since 1.8.0 - * - */ -H5_DLL htri_t H5Tcompiler_conv(hid_t src_id, hid_t dst_id); /** * -------------------------------------------------------------------------- * \ingroup CONV @@ -2880,6 +2740,21 @@ H5_DLL herr_t H5Treclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void *bu * Use of these symbols is deprecated. */ +/* API Wrappers for async routines */ +/* (Must be defined _after_ the function prototype) */ +/* (And must only defined when included in application code, not the library) */ +#ifndef H5T_MODULE +#define H5Tcommit_async(...) H5Tcommit_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Topen_async(...) H5Topen_async(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5Tclose_async(...) H5Tclose_async(__FILE__, __func__, __LINE__, __VA_ARGS__) + +/* Define "wrapper" versions of function calls, to allow compile-time values to + * be passed in by language wrapper or library layer on top of HDF5. */ +#define H5Tcommit_async_wrap H5_NO_EXPAND(H5Tcommit_async) +#define H5Topen_async_wrap H5_NO_EXPAND(H5Topen_async) +#define H5Tclose_async_wrap H5_NO_EXPAND(H5Tclose_async) +#endif /* H5T_MODULE */ + #ifndef H5_NO_DEPRECATED_SYMBOLS /* Macros */ @@ -2890,7 +2765,7 @@ H5_DLL herr_t H5Treclaim(hid_t type_id, hid_t space_id, hid_t plist_id, void *bu /** * \ingroup H5T * - * \brief Commits a transient datatype to a file, creating a new named datatype + * \brief Commits a transient datatype to a file, creating a newly named datatype * * \fg_loc_id * \param[in] name Name given to committed datatype diff --git a/libs/windows/include/H5VLconnector.h b/libs/windows/include/H5VLconnector.h index de3f6b3..02d2231 100644 --- a/libs/windows/include/H5VLconnector.h +++ b/libs/windows/include/H5VLconnector.h @@ -20,6 +20,7 @@ /* Public headers needed by this file */ #include "H5public.h" /* Generic Functions */ #include "H5Apublic.h" /* Attributes */ +#include "H5Dpublic.h" /* Datasets */ #include "H5ESpublic.h" /* Event Stack */ #include "H5Fpublic.h" /* Files */ #include "H5Ipublic.h" /* IDs */ @@ -32,21 +33,70 @@ /* Public Macros */ /*****************/ -/* Capability flags for connector */ -#define H5VL_CAP_FLAG_NONE 0 /* No special connector capabilities */ -#define H5VL_CAP_FLAG_THREADSAFE 0x01 /* Connector is threadsafe */ - /* Container info version */ #define H5VL_CONTAINER_INFO_VERSION 0x01 /* Container info struct version */ /* The maximum size allowed for blobs */ #define H5VL_MAX_BLOB_ID_SIZE (16) /* Allow for 128-bits blob IDs */ +/* # of optional operations reserved for the native VOL connector */ +#define H5VL_RESERVED_NATIVE_OPTIONAL 1024 + /*******************/ /* Public Typedefs */ /*******************/ -/* types for attribute GET callback */ +/* Types for different ways that objects are located in an HDF5 container */ +typedef enum H5VL_loc_type_t { + H5VL_OBJECT_BY_SELF, + H5VL_OBJECT_BY_NAME, + H5VL_OBJECT_BY_IDX, + H5VL_OBJECT_BY_TOKEN +} H5VL_loc_type_t; + +typedef struct H5VL_loc_by_name { + const char *name; + hid_t lapl_id; +} H5VL_loc_by_name_t; + +typedef struct H5VL_loc_by_idx { + const char *name; + H5_index_t idx_type; + H5_iter_order_t order; + hsize_t n; + hid_t lapl_id; +} H5VL_loc_by_idx_t; + +typedef struct H5VL_loc_by_token { + H5O_token_t *token; +} H5VL_loc_by_token_t; + +/* Structure to hold parameters for object locations. + * Either: BY_SELF, BY_NAME, BY_IDX, BY_TOKEN + * + * Note: Leave loc_by_token as the first union member so we + * can perform the simplest initialization of the struct + * without raising warnings. + * + * Note: BY_SELF requires no union members. + */ +typedef struct H5VL_loc_params_t { + H5I_type_t obj_type; + H5VL_loc_type_t type; + union { + H5VL_loc_by_token_t loc_by_token; + H5VL_loc_by_name_t loc_by_name; + H5VL_loc_by_idx_t loc_by_idx; + } loc_data; +} H5VL_loc_params_t; + +/* Struct for all 'optional' callbacks */ +typedef struct H5VL_optional_args_t { + int op_type; /* Operation to perform */ + void *args; /* Pointer to operation's argument struct */ +} H5VL_optional_args_t; + +/* Values for attribute 'get' operations */ typedef enum H5VL_attr_get_t { H5VL_ATTR_GET_ACPL, /* creation property list */ H5VL_ATTR_GET_INFO, /* info */ @@ -56,18 +106,115 @@ typedef enum H5VL_attr_get_t { H5VL_ATTR_GET_TYPE /* datatype */ } H5VL_attr_get_t; -/* types for attribute SPECFIC callback */ +/* Parameters for attribute 'get_name' operation */ +typedef struct H5VL_attr_get_name_args_t { + H5VL_loc_params_t loc_params; /* Location parameters for object access */ + size_t buf_size; /* Size of attribute name buffer */ + char *buf; /* Buffer for attribute name (OUT) */ + size_t *attr_name_len; /* Actual length of attribute name (OUT) */ +} H5VL_attr_get_name_args_t; + +/* Parameters for attribute 'get_info' operation */ +typedef struct H5VL_attr_get_info_args_t { + H5VL_loc_params_t loc_params; /* Location parameters for object access */ + const char *attr_name; /* Attribute name (for get_info_by_name) */ + H5A_info_t *ainfo; /* Attribute info (OUT) */ +} H5VL_attr_get_info_args_t; + +/* Parameters for attribute 'get' operations */ +typedef struct H5VL_attr_get_args_t { + H5VL_attr_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_ATTR_GET_ACPL */ + struct { + hid_t acpl_id; /* Attribute creation property list ID (OUT) */ + } get_acpl; + + /* H5VL_ATTR_GET_INFO */ + H5VL_attr_get_info_args_t get_info; /* Attribute info */ + + /* H5VL_ATTR_GET_NAME */ + H5VL_attr_get_name_args_t get_name; /* Attribute name */ + + /* H5VL_ATTR_GET_SPACE */ + struct { + hid_t space_id; /* Dataspace ID (OUT) */ + } get_space; + + /* H5VL_ATTR_GET_STORAGE_SIZE */ + struct { + hsize_t *data_size; /* Size of attribute in file (OUT) */ + } get_storage_size; + + /* H5VL_ATTR_GET_TYPE */ + struct { + hid_t type_id; /* Datatype ID (OUT) */ + } get_type; + } args; +} H5VL_attr_get_args_t; + +/* Values for attribute 'specific' operation */ typedef enum H5VL_attr_specific_t { - H5VL_ATTR_DELETE, /* H5Adelete(_by_name/idx) */ - H5VL_ATTR_EXISTS, /* H5Aexists(_by_name) */ - H5VL_ATTR_ITER, /* H5Aiterate(_by_name) */ - H5VL_ATTR_RENAME /* H5Arename(_by_name) */ + H5VL_ATTR_DELETE, /* H5Adelete(_by_name) */ + H5VL_ATTR_DELETE_BY_IDX, /* H5Adelete_by_idx */ + H5VL_ATTR_EXISTS, /* H5Aexists(_by_name) */ + H5VL_ATTR_ITER, /* H5Aiterate(_by_name) */ + H5VL_ATTR_RENAME /* H5Arename(_by_name) */ } H5VL_attr_specific_t; +/* Parameters for attribute 'iterate' operation */ +typedef struct H5VL_attr_iterate_args_t { + H5_index_t idx_type; /* Type of index to iterate over */ + H5_iter_order_t order; /* Order of index iteration */ + hsize_t *idx; /* Start/stop iteration index (IN/OUT) */ + H5A_operator2_t op; /* Iteration callback function */ + void *op_data; /* Iteration callback context */ +} H5VL_attr_iterate_args_t; + +/* Parameters for attribute 'delete_by_idx' operation */ +typedef struct H5VL_attr_delete_by_idx_args_t { + H5_index_t idx_type; /* Type of index to iterate over */ + H5_iter_order_t order; /* Order of index iteration */ + hsize_t n; /* Iteration index */ +} H5VL_attr_delete_by_idx_args_t; + +/* Parameters for attribute 'specific' operations */ +typedef struct H5VL_attr_specific_args_t { + H5VL_attr_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_ATTR_DELETE */ + struct { + const char *name; /* Name of attribute to delete */ + } del; + + /* H5VL_ATTR_DELETE_BY_IDX */ + H5VL_attr_delete_by_idx_args_t delete_by_idx; + + /* H5VL_ATTR_EXISTS */ + struct { + const char *name; /* Name of attribute to check */ + hbool_t *exists; /* Whether attribute exists (OUT) */ + } exists; + + /* H5VL_ATTR_ITER */ + H5VL_attr_iterate_args_t iterate; + + /* H5VL_ATTR_RENAME */ + struct { + const char *old_name; /* Name of attribute to rename */ + const char *new_name; /* New attribute name */ + } rename; + } args; +} H5VL_attr_specific_args_t; + /* Typedef for VOL connector attribute optional VOL operations */ typedef int H5VL_attr_optional_t; -/* types for dataset GET callback */ +/* Values for dataset 'get' operation */ typedef enum H5VL_dataset_get_t { H5VL_DATASET_GET_DAPL, /* access property list */ H5VL_DATASET_GET_DCPL, /* creation property list */ @@ -77,30 +224,146 @@ typedef enum H5VL_dataset_get_t { H5VL_DATASET_GET_TYPE /* datatype */ } H5VL_dataset_get_t; -/* types for dataset SPECFIC callback */ +/* Parameters for dataset 'get' operations */ +typedef struct H5VL_dataset_get_args_t { + H5VL_dataset_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_DATASET_GET_DAPL */ + struct { + hid_t dapl_id; /* Dataset access property list ID (OUT) */ + } get_dapl; + + /* H5VL_DATASET_GET_DCPL */ + struct { + hid_t dcpl_id; /* Dataset creation property list ID (OUT) */ + } get_dcpl; + + /* H5VL_DATASET_GET_SPACE */ + struct { + hid_t space_id; /* Dataspace ID (OUT) */ + } get_space; + + /* H5VL_DATASET_GET_SPACE_STATUS */ + struct { + H5D_space_status_t *status; /* Storage space allocation status (OUT) */ + } get_space_status; + + /* H5VL_DATASET_GET_STORAGE_SIZE */ + struct { + hsize_t *storage_size; /* Size of dataset's storage (OUT) */ + } get_storage_size; + + /* H5VL_DATASET_GET_TYPE */ + struct { + hid_t type_id; /* Datatype ID (OUT) */ + } get_type; + } args; +} H5VL_dataset_get_args_t; + +/* Values for dataset 'specific' operation */ typedef enum H5VL_dataset_specific_t { H5VL_DATASET_SET_EXTENT, /* H5Dset_extent */ H5VL_DATASET_FLUSH, /* H5Dflush */ H5VL_DATASET_REFRESH /* H5Drefresh */ } H5VL_dataset_specific_t; +/* Parameters for dataset 'specific' operations */ +typedef struct H5VL_dataset_specific_args_t { + H5VL_dataset_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_DATASET_SET_EXTENT */ + struct { + const hsize_t *size; /* New dataspace extent */ + } set_extent; + + /* H5VL_DATASET_FLUSH */ + struct { + hid_t dset_id; /* Dataset ID (IN) */ + } flush; + + /* H5VL_DATASET_REFRESH */ + struct { + hid_t dset_id; /* Dataset ID (IN) */ + } refresh; + } args; +} H5VL_dataset_specific_args_t; + /* Typedef for VOL connector dataset optional VOL operations */ typedef int H5VL_dataset_optional_t; -/* types for datatype GET callback */ +/* Values for datatype 'get' operation */ typedef enum H5VL_datatype_get_t { - H5VL_DATATYPE_GET_BINARY, /* get serialized form of transient type */ - H5VL_DATATYPE_GET_TCPL /* datatype creation property list */ + H5VL_DATATYPE_GET_BINARY_SIZE, /* Get size of serialized form of transient type */ + H5VL_DATATYPE_GET_BINARY, /* Get serialized form of transient type */ + H5VL_DATATYPE_GET_TCPL /* Datatype creation property list */ } H5VL_datatype_get_t; -/* types for datatype SPECFIC callback */ -typedef enum H5VL_datatype_specific_t { H5VL_DATATYPE_FLUSH, H5VL_DATATYPE_REFRESH } H5VL_datatype_specific_t; +/* Parameters for datatype 'get' operations */ +typedef struct H5VL_datatype_get_args_t { + H5VL_datatype_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_DATATYPE_GET_BINARY_SIZE */ + struct { + size_t *size; /* Size of serialized form of datatype (OUT) */ + } get_binary_size; + + /* H5VL_DATATYPE_GET_BINARY */ + struct { + void *buf; /* Buffer to store serialized form of datatype (OUT) */ + size_t buf_size; /* Size of serialized datatype buffer */ + } get_binary; + + /* H5VL_DATATYPE_GET_TCPL */ + struct { + hid_t tcpl_id; /* Named datatype creation property list ID (OUT) */ + } get_tcpl; + } args; +} H5VL_datatype_get_args_t; + +/* Values for datatype 'specific' operation */ +typedef enum H5VL_datatype_specific_t { + H5VL_DATATYPE_FLUSH, /* H5Tflush */ + H5VL_DATATYPE_REFRESH /* H5Trefresh */ +} H5VL_datatype_specific_t; + +/* Parameters for datatype 'specific' operations */ +typedef struct H5VL_datatype_specific_args_t { + H5VL_datatype_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_DATATYPE_FLUSH */ + struct { + hid_t type_id; /* Named datatype ID (IN) */ + } flush; + + /* H5VL_DATATYPE_REFRESH */ + struct { + hid_t type_id; /* Named datatype ID (IN) */ + } refresh; + } args; +} H5VL_datatype_specific_args_t; /* Typedef and values for native VOL connector named datatype optional VOL operations */ typedef int H5VL_datatype_optional_t; /* (No optional named datatype VOL operations currently) */ -/* types for file GET callback */ +/* Info for H5VL_FILE_GET_CONT_INFO */ +typedef struct H5VL_file_cont_info_t { + unsigned version; /* version information (keep first) */ + uint64_t feature_flags; /* Container feature flags */ + /* (none currently defined) */ + size_t token_size; /* Size of tokens */ + size_t blob_id_size; /* Size of blob IDs */ +} H5VL_file_cont_info_t; + +/* Values for file 'get' operation */ typedef enum H5VL_file_get_t { H5VL_FILE_GET_CONT_INFO, /* file get container info */ H5VL_FILE_GET_FAPL, /* file access property list */ @@ -112,58 +375,296 @@ typedef enum H5VL_file_get_t { H5VL_FILE_GET_OBJ_IDS /* object ids in file */ } H5VL_file_get_t; -/* types for file SPECIFIC callback */ +/* Parameters for file 'get_name' operation */ +typedef struct H5VL_file_get_name_args_t { + H5I_type_t type; /* ID type of object pointer */ + size_t buf_size; /* Size of file name buffer (IN) */ + char *buf; /* Buffer for file name (OUT) */ + size_t *file_name_len; /* Actual length of file name (OUT) */ +} H5VL_file_get_name_args_t; + +/* Parameters for file 'get_obj_ids' operation */ +typedef struct H5VL_file_get_obj_ids_args_t { + unsigned types; /* Type of objects to count */ + size_t max_objs; /* Size of array of object IDs */ + hid_t *oid_list; /* Array of object IDs (OUT) */ + size_t *count; /* # of objects (OUT) */ +} H5VL_file_get_obj_ids_args_t; + +/* Parameters for file 'get' operations */ +typedef struct H5VL_file_get_args_t { + H5VL_file_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_FILE_GET_CONT_INFO */ + struct { + H5VL_file_cont_info_t *info; /* Container info (OUT) */ + } get_cont_info; + + /* H5VL_FILE_GET_FAPL */ + struct { + hid_t fapl_id; /* File access property list (OUT) */ + } get_fapl; + + /* H5VL_FILE_GET_FCPL */ + struct { + hid_t fcpl_id; /* File creation property list (OUT) */ + } get_fcpl; + + /* H5VL_FILE_GET_FILENO */ + struct { + unsigned long *fileno; /* File "number" (OUT) */ + } get_fileno; + + /* H5VL_FILE_GET_INTENT */ + struct { + unsigned *flags; /* File open/create intent flags (OUT) */ + } get_intent; + + /* H5VL_FILE_GET_NAME */ + H5VL_file_get_name_args_t get_name; + + /* H5VL_FILE_GET_OBJ_COUNT */ + struct { + unsigned types; /* Type of objects to count */ + size_t *count; /* # of objects (OUT) */ + } get_obj_count; + + /* H5VL_FILE_GET_OBJ_IDS */ + H5VL_file_get_obj_ids_args_t get_obj_ids; + } args; +} H5VL_file_get_args_t; + +/* Values for file 'specific' operation */ typedef enum H5VL_file_specific_t { H5VL_FILE_FLUSH, /* Flush file */ H5VL_FILE_REOPEN, /* Reopen the file */ - H5VL_FILE_MOUNT, /* Mount a file */ - H5VL_FILE_UNMOUNT, /* Unmount a file */ H5VL_FILE_IS_ACCESSIBLE, /* Check if a file is accessible */ H5VL_FILE_DELETE, /* Delete a file */ H5VL_FILE_IS_EQUAL /* Check if two files are the same */ } H5VL_file_specific_t; +/* Parameters for file 'specific' operations */ +typedef struct H5VL_file_specific_args_t { + H5VL_file_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_FILE_FLUSH */ + struct { + H5I_type_t obj_type; /* Type of object to use */ + H5F_scope_t scope; /* Scope of flush operation */ + } flush; + + /* H5VL_FILE_REOPEN */ + struct { + void **file; /* File object for new file (OUT) */ + } reopen; + + /* H5VL_FILE_IS_ACCESSIBLE */ + struct { + const char *filename; /* Name of file to check */ + hid_t fapl_id; /* File access property list to use */ + hbool_t *accessible; /* Whether file is accessible with FAPL settings (OUT) */ + } is_accessible; + + /* H5VL_FILE_DELETE */ + struct { + const char *filename; /* Name of file to delete */ + hid_t fapl_id; /* File access property list to use */ + } del; + + /* H5VL_FILE_IS_EQUAL */ + struct { + void *obj2; /* Second file object to compare against */ + hbool_t *same_file; /* Whether files are the same (OUT) */ + } is_equal; + } args; +} H5VL_file_specific_args_t; + /* Typedef for VOL connector file optional VOL operations */ typedef int H5VL_file_optional_t; -/* types for group GET callback */ +/* Values for group 'get' operation */ typedef enum H5VL_group_get_t { H5VL_GROUP_GET_GCPL, /* group creation property list */ H5VL_GROUP_GET_INFO /* group info */ } H5VL_group_get_t; -/* types for group SPECFIC callback */ -typedef enum H5VL_group_specific_t { H5VL_GROUP_FLUSH, H5VL_GROUP_REFRESH } H5VL_group_specific_t; +/* Parameters for group 'get_info' operation */ +typedef struct H5VL_group_get_info_args_t { + H5VL_loc_params_t loc_params; /* Location parameters for object access */ + H5G_info_t *ginfo; /* Group info (OUT) */ +} H5VL_group_get_info_args_t; + +/* Parameters for group 'get' operations */ +typedef struct H5VL_group_get_args_t { + H5VL_group_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_GROUP_GET_GCPL */ + struct { + hid_t gcpl_id; /* Group creation property list (OUT) */ + } get_gcpl; + + /* H5VL_GROUP_GET_INFO */ + H5VL_group_get_info_args_t get_info; /* Group info */ + } args; +} H5VL_group_get_args_t; + +/* Values for group 'specific' operation */ +typedef enum H5VL_group_specific_t { + H5VL_GROUP_MOUNT, /* Mount a file on a group */ + H5VL_GROUP_UNMOUNT, /* Unmount a file on a group */ + H5VL_GROUP_FLUSH, /* H5Gflush */ + H5VL_GROUP_REFRESH /* H5Grefresh */ +} H5VL_group_specific_t; + +/* Parameters for group 'mount' operation */ +typedef struct H5VL_group_spec_mount_args_t { + const char *name; /* Name of location to mount child file */ + void *child_file; /* Pointer to child file object */ + hid_t fmpl_id; /* File mount property list to use */ +} H5VL_group_spec_mount_args_t; + +/* Parameters for group 'specific' operations */ +typedef struct H5VL_group_specific_args_t { + H5VL_group_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_GROUP_MOUNT */ + H5VL_group_spec_mount_args_t mount; + + /* H5VL_GROUP_UNMOUNT */ + struct { + const char *name; /* Name of location to unmount child file */ + } unmount; + + /* H5VL_GROUP_FLUSH */ + struct { + hid_t grp_id; /* Group ID (IN) */ + } flush; + + /* H5VL_GROUP_REFRESH */ + struct { + hid_t grp_id; /* Group ID (IN) */ + } refresh; + } args; +} H5VL_group_specific_args_t; /* Typedef for VOL connector group optional VOL operations */ typedef int H5VL_group_optional_t; -/* link create types for VOL */ -typedef enum H5VL_link_create_type_t { +/* Link create types for VOL */ +typedef enum H5VL_link_create_t { H5VL_LINK_CREATE_HARD, H5VL_LINK_CREATE_SOFT, H5VL_LINK_CREATE_UD -} H5VL_link_create_type_t; +} H5VL_link_create_t; + +/* Parameters for link 'create' operations */ +typedef struct H5VL_link_create_args_t { + H5VL_link_create_t op_type; /* Operation to perform */ -/* types for link GET callback */ + /* Parameters for each operation */ + union { + /* H5VL_LINK_CREATE_HARD */ + struct { + void *curr_obj; /* Current object */ + H5VL_loc_params_t curr_loc_params; /* Location parameters for current object */ + } hard; + + /* H5VL_LINK_CREATE_SOFT */ + struct { + const char *target; /* Target of soft link */ + } soft; + + /* H5VL_LINK_CREATE_UD */ + struct { + H5L_type_t type; /* Type of link to create */ + const void *buf; /* Buffer that contains link info */ + size_t buf_size; /* Size of link info buffer */ + } ud; + } args; +} H5VL_link_create_args_t; + +/* Values for link 'get' operation */ typedef enum H5VL_link_get_t { H5VL_LINK_GET_INFO, /* link info */ H5VL_LINK_GET_NAME, /* link name */ H5VL_LINK_GET_VAL /* link value */ } H5VL_link_get_t; -/* types for link SPECIFIC callback */ +/* Parameters for link 'get' operations */ +typedef struct H5VL_link_get_args_t { + H5VL_link_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_LINK_GET_INFO */ + struct { + H5L_info2_t *linfo; /* Pointer to link's info (OUT) */ + } get_info; + + /* H5VL_LINK_GET_NAME */ + struct { + size_t name_size; /* Size of link name buffer (IN) */ + char *name; /* Buffer for link name (OUT) */ + size_t *name_len; /* Actual length of link name (OUT) */ + } get_name; + + /* H5VL_LINK_GET_VAL */ + struct { + size_t buf_size; /* Size of link value buffer (IN) */ + void *buf; /* Buffer for link value (OUT) */ + } get_val; + } args; +} H5VL_link_get_args_t; + +/* Values for link 'specific' operation */ typedef enum H5VL_link_specific_t { H5VL_LINK_DELETE, /* H5Ldelete(_by_idx) */ H5VL_LINK_EXISTS, /* link existence */ H5VL_LINK_ITER /* H5Literate/visit(_by_name) */ } H5VL_link_specific_t; +/* Parameters for link 'iterate' operation */ +typedef struct H5VL_link_iterate_args_t { + hbool_t recursive; /* Whether iteration is recursive */ + H5_index_t idx_type; /* Type of index to iterate over */ + H5_iter_order_t order; /* Order of index iteration */ + hsize_t *idx_p; /* Start/stop iteration index (OUT) */ + H5L_iterate2_t op; /* Iteration callback function */ + void *op_data; /* Iteration callback context */ +} H5VL_link_iterate_args_t; + +/* Parameters for link 'specific' operations */ +typedef struct H5VL_link_specific_args_t { + H5VL_link_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_LINK_DELETE */ + /* No args */ + + /* H5VL_LINK_EXISTS */ + struct { + hbool_t *exists; /* Whether link exists (OUT) */ + } exists; + + /* H5VL_LINK_ITER */ + H5VL_link_iterate_args_t iterate; + } args; +} H5VL_link_specific_args_t; + /* Typedef and values for native VOL connector link optional VOL operations */ typedef int H5VL_link_optional_t; /* (No optional link VOL operations currently) */ -/* types for object GET callback */ +/* Values for object 'get' operation */ typedef enum H5VL_object_get_t { H5VL_OBJECT_GET_FILE, /* object file */ H5VL_OBJECT_GET_NAME, /* object name */ @@ -171,7 +672,38 @@ typedef enum H5VL_object_get_t { H5VL_OBJECT_GET_INFO /* H5Oget_info(_by_idx|name) */ } H5VL_object_get_t; -/* types for object SPECIFIC callback */ +/* Parameters for object 'get' operations */ +typedef struct H5VL_object_get_args_t { + H5VL_object_get_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_OBJECT_GET_FILE */ + struct { + void **file; /* File object (OUT) */ + } get_file; + + /* H5VL_OBJECT_GET_NAME */ + struct { + size_t buf_size; /* Size of name buffer (IN) */ + char *buf; /* Buffer for name (OUT) */ + size_t *name_len; /* Actual length of name (OUT) */ + } get_name; + + /* H5VL_OBJECT_GET_TYPE */ + struct { + H5O_type_t *obj_type; /* Type of object (OUT) */ + } get_type; + + /* H5VL_OBJECT_GET_INFO */ + struct { + unsigned fields; /* Flags for fields to retrieve */ + H5O_info2_t *oinfo; /* Pointer to object info (OUT) */ + } get_info; + } args; +} H5VL_object_get_args_t; + +/* Values for object 'specific' operation */ typedef enum H5VL_object_specific_t { H5VL_OBJECT_CHANGE_REF_COUNT, /* H5Oincr/decr_refcount */ H5VL_OBJECT_EXISTS, /* H5Oexists_by_name */ @@ -181,84 +713,125 @@ typedef enum H5VL_object_specific_t { H5VL_OBJECT_REFRESH /* H5{D|G|O|T}refresh */ } H5VL_object_specific_t; +/* Parameters for object 'visit' operation */ +typedef struct H5VL_object_visit_args_t { + H5_index_t idx_type; /* Type of index to iterate over */ + H5_iter_order_t order; /* Order of index iteration */ + unsigned fields; /* Flags for fields to provide in 'info' object for 'op' callback */ + H5O_iterate2_t op; /* Iteration callback function */ + void *op_data; /* Iteration callback context */ +} H5VL_object_visit_args_t; + +/* Parameters for object 'specific' operations */ +typedef struct H5VL_object_specific_args_t { + H5VL_object_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_OBJECT_CHANGE_REF_COUNT */ + struct { + int delta; /* Amount to modify object's refcount */ + } change_rc; + + /* H5VL_OBJECT_EXISTS */ + struct { + hbool_t *exists; /* Whether object exists (OUT) */ + } exists; + + /* H5VL_OBJECT_LOOKUP */ + struct { + H5O_token_t *token_ptr; /* Pointer to token for lookup (OUT) */ + } lookup; + + /* H5VL_OBJECT_VISIT */ + H5VL_object_visit_args_t visit; + + /* H5VL_OBJECT_FLUSH */ + struct { + hid_t obj_id; /* Object ID (IN) */ + } flush; + + /* H5VL_OBJECT_REFRESH */ + struct { + hid_t obj_id; /* Object ID (IN) */ + } refresh; + } args; +} H5VL_object_specific_args_t; + /* Typedef for VOL connector object optional VOL operations */ typedef int H5VL_object_optional_t; -/* types for async request SPECIFIC callback */ +/* Status values for async request operations */ +typedef enum H5VL_request_status_t { + H5VL_REQUEST_STATUS_IN_PROGRESS, /* Operation has not yet completed */ + H5VL_REQUEST_STATUS_SUCCEED, /* Operation has completed, successfully */ + H5VL_REQUEST_STATUS_FAIL, /* Operation has completed, but failed */ + H5VL_REQUEST_STATUS_CANT_CANCEL, /* An attempt to cancel this operation was made, but it */ + /* can't be canceled immediately. The operation has */ + /* not completed successfully or failed, and is not yet */ + /* in progress. Another attempt to cancel it may be */ + /* attempted and may (or may not) succeed. */ + H5VL_REQUEST_STATUS_CANCELED /* Operation has not completed and was canceled */ +} H5VL_request_status_t; + +/* Values for async request 'specific' operation */ typedef enum H5VL_request_specific_t { - H5VL_REQUEST_WAITANY, /* Wait until any request completes */ - H5VL_REQUEST_WAITSOME, /* Wait until at least one requesst completes */ - H5VL_REQUEST_WAITALL /* Wait until all requests complete */ + H5VL_REQUEST_GET_ERR_STACK, /* Retrieve error stack for failed operation */ + H5VL_REQUEST_GET_EXEC_TIME /* Retrieve execution time for operation */ } H5VL_request_specific_t; +/* Parameters for request 'specific' operations */ +typedef struct H5VL_request_specific_args_t { + H5VL_request_specific_t op_type; /* Operation to perform */ + + /* Parameters for each operation */ + union { + /* H5VL_REQUEST_GET_ERR_STACK */ + struct { + hid_t err_stack_id; /* Error stack ID for operation (OUT) */ + } get_err_stack; + + /* H5VL_REQUEST_GET_EXEC_TIME */ + struct { + uint64_t *exec_ts; /* Timestamp for start of task execution (OUT) */ + uint64_t *exec_time; /* Duration of task execution (in ns) (OUT) */ + } get_exec_time; + } args; +} H5VL_request_specific_args_t; + /* Typedef and values for native VOL connector request optional VOL operations */ typedef int H5VL_request_optional_t; /* (No optional request VOL operations currently) */ -/* types for 'blob' SPECIFIC callback */ +/* Values for 'blob' 'specific' operation */ typedef enum H5VL_blob_specific_t { - H5VL_BLOB_DELETE, /* Delete a blob (by ID) */ - H5VL_BLOB_GETSIZE, /* Get size of blob */ - H5VL_BLOB_ISNULL, /* Check if a blob ID is "null" */ - H5VL_BLOB_SETNULL /* Set a blob ID to the connector's "null" blob ID value */ + H5VL_BLOB_DELETE, /* Delete a blob (by ID) */ + H5VL_BLOB_ISNULL, /* Check if a blob ID is "null" */ + H5VL_BLOB_SETNULL /* Set a blob ID to the connector's "null" blob ID value */ } H5VL_blob_specific_t; -/* Typedef and values for native VOL connector blob optional VOL operations */ -typedef int H5VL_blob_optional_t; -/* (No optional blob VOL operations currently) */ - -/* Types for different ways that objects are located in an HDF5 container */ -typedef enum H5VL_loc_type_t { - H5VL_OBJECT_BY_SELF, - H5VL_OBJECT_BY_NAME, - H5VL_OBJECT_BY_IDX, - H5VL_OBJECT_BY_TOKEN -} H5VL_loc_type_t; +/* Parameters for blob 'specific' operations */ +typedef struct H5VL_blob_specific_args_t { + H5VL_blob_specific_t op_type; /* Operation to perform */ -typedef struct H5VL_loc_by_name { - const char *name; - hid_t lapl_id; -} H5VL_loc_by_name_t; - -typedef struct H5VL_loc_by_idx { - const char * name; - H5_index_t idx_type; - H5_iter_order_t order; - hsize_t n; - hid_t lapl_id; -} H5VL_loc_by_idx_t; + /* Parameters for each operation */ + union { + /* H5VL_BLOB_DELETE */ + /* No args */ -typedef struct H5VL_loc_by_token { - H5O_token_t *token; -} H5VL_loc_by_token_t; + /* H5VL_BLOB_ISNULL */ + struct { + hbool_t *isnull; /* Whether blob ID is "null" (OUT) */ + } is_null; -/* Structure to hold parameters for object locations. - * Either: BY_SELF, BY_NAME, BY_IDX, BY_TOKEN - * - * Note: Leave loc_by_token as the first union member so we - * can perform the simplest initialization of the struct - * without raising warnings. - * - * Note: BY_SELF requires no union members. - */ -typedef struct H5VL_loc_params_t { - H5I_type_t obj_type; - H5VL_loc_type_t type; - union { - H5VL_loc_by_token_t loc_by_token; - H5VL_loc_by_name_t loc_by_name; - H5VL_loc_by_idx_t loc_by_idx; - } loc_data; -} H5VL_loc_params_t; + /* H5VL_BLOB_SETNULL */ + /* No args */ + } args; +} H5VL_blob_specific_args_t; -/* Info for H5VL_FILE_GET_CONT_INFO */ -typedef struct H5VL_file_cont_info_t { - unsigned version; /* version information (keep first) */ - uint64_t feature_flags; /* Container feature flags */ - /* (none currently defined) */ - size_t token_size; /* Size of tokens */ - size_t blob_id_size; /* Size of blob IDs */ -} H5VL_file_cont_info_t; +/* Typedef and values for native VOL connector blob optional VOL operations */ +typedef int H5VL_blob_optional_t; +/* (No optional blob VOL operations currently) */ /* VOL connector info fields & callbacks */ typedef struct H5VL_info_class_t { @@ -268,7 +841,7 @@ typedef struct H5VL_info_class_t { herr_t (*free)(void *info); /* Callback to release a VOL info */ herr_t (*to_str)(const void *info, char **str); /* Callback to serialize connector's info into a string */ herr_t (*from_str)(const char *str, - void ** info); /* Callback to deserialize a string into connector's info */ + void **info); /* Callback to deserialize a string into connector's info */ } H5VL_info_class_t; /* VOL object wrap / retrieval callbacks */ @@ -277,7 +850,7 @@ typedef struct H5VL_wrap_class_t { void *(*get_object)(const void *obj); /* Callback to retrieve underlying object */ herr_t (*get_wrap_ctx)( const void *obj, - void ** wrap_ctx); /* Callback to retrieve the object wrapping context for the connector */ + void **wrap_ctx); /* Callback to retrieve the object wrapping context for the connector */ void *(*wrap_object)(void *obj, H5I_type_t obj_type, void *wrap_ctx); /* Callback to wrap a library object */ void *(*unwrap_object)(void *obj); /* Callback to unwrap a library object */ @@ -293,11 +866,10 @@ typedef struct H5VL_attr_class_t { hid_t dxpl_id, void **req); herr_t (*read)(void *attr, hid_t mem_type_id, void *buf, hid_t dxpl_id, void **req); herr_t (*write)(void *attr, hid_t mem_type_id, const void *buf, hid_t dxpl_id, void **req); - herr_t (*get)(void *obj, H5VL_attr_get_t get_type, hid_t dxpl_id, void **req, va_list arguments); - herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_attr_specific_t specific_type, - hid_t dxpl_id, void **req, va_list arguments); - herr_t (*optional)(void *obj, H5VL_attr_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments); + herr_t (*get)(void *obj, H5VL_attr_get_args_t *args, hid_t dxpl_id, void **req); + herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_attr_specific_args_t *args, + hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); herr_t (*close)(void *attr, hid_t dxpl_id, void **req); } H5VL_attr_class_t; @@ -307,15 +879,13 @@ typedef struct H5VL_dataset_class_t { hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id, hid_t dxpl_id, void **req); void *(*open)(void *obj, const H5VL_loc_params_t *loc_params, const char *name, hid_t dapl_id, hid_t dxpl_id, void **req); - herr_t (*read)(void *dset, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, - void *buf, void **req); - herr_t (*write)(void *dset, hid_t mem_type_id, hid_t mem_space_id, hid_t file_space_id, hid_t dxpl_id, - const void *buf, void **req); - herr_t (*get)(void *obj, H5VL_dataset_get_t get_type, hid_t dxpl_id, void **req, va_list arguments); - herr_t (*specific)(void *obj, H5VL_dataset_specific_t specific_type, hid_t dxpl_id, void **req, - va_list arguments); - herr_t (*optional)(void *obj, H5VL_dataset_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments); + herr_t (*read)(size_t count, void *dset[], hid_t mem_type_id[], hid_t mem_space_id[], + hid_t file_space_id[], hid_t dxpl_id, void *buf[], void **req); + herr_t (*write)(size_t count, void *dset[], hid_t mem_type_id[], hid_t mem_space_id[], + hid_t file_space_id[], hid_t dxpl_id, const void *buf[], void **req); + herr_t (*get)(void *obj, H5VL_dataset_get_args_t *args, hid_t dxpl_id, void **req); + herr_t (*specific)(void *obj, H5VL_dataset_specific_args_t *args, hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); herr_t (*close)(void *dset, hid_t dxpl_id, void **req); } H5VL_dataset_class_t; @@ -325,11 +895,9 @@ typedef struct H5VL_datatype_class_t { hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id, hid_t dxpl_id, void **req); void *(*open)(void *obj, const H5VL_loc_params_t *loc_params, const char *name, hid_t tapl_id, hid_t dxpl_id, void **req); - herr_t (*get)(void *obj, H5VL_datatype_get_t get_type, hid_t dxpl_id, void **req, va_list arguments); - herr_t (*specific)(void *obj, H5VL_datatype_specific_t specific_type, hid_t dxpl_id, void **req, - va_list arguments); - herr_t (*optional)(void *obj, H5VL_datatype_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments); + herr_t (*get)(void *obj, H5VL_datatype_get_args_t *args, hid_t dxpl_id, void **req); + herr_t (*specific)(void *obj, H5VL_datatype_specific_args_t *args, hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); herr_t (*close)(void *dt, hid_t dxpl_id, void **req); } H5VL_datatype_class_t; @@ -338,11 +906,9 @@ typedef struct H5VL_file_class_t { void *(*create)(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t dxpl_id, void **req); void *(*open)(const char *name, unsigned flags, hid_t fapl_id, hid_t dxpl_id, void **req); - herr_t (*get)(void *obj, H5VL_file_get_t get_type, hid_t dxpl_id, void **req, va_list arguments); - herr_t (*specific)(void *obj, H5VL_file_specific_t specific_type, hid_t dxpl_id, void **req, - va_list arguments); - herr_t (*optional)(void *obj, H5VL_file_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments); + herr_t (*get)(void *obj, H5VL_file_get_args_t *args, hid_t dxpl_id, void **req); + herr_t (*specific)(void *obj, H5VL_file_specific_args_t *args, hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); herr_t (*close)(void *file, hid_t dxpl_id, void **req); } H5VL_file_class_t; @@ -352,30 +918,28 @@ typedef struct H5VL_group_class_t { hid_t gcpl_id, hid_t gapl_id, hid_t dxpl_id, void **req); void *(*open)(void *obj, const H5VL_loc_params_t *loc_params, const char *name, hid_t gapl_id, hid_t dxpl_id, void **req); - herr_t (*get)(void *obj, H5VL_group_get_t get_type, hid_t dxpl_id, void **req, va_list arguments); - herr_t (*specific)(void *obj, H5VL_group_specific_t specific_type, hid_t dxpl_id, void **req, - va_list arguments); - herr_t (*optional)(void *obj, H5VL_group_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments); + herr_t (*get)(void *obj, H5VL_group_get_args_t *args, hid_t dxpl_id, void **req); + herr_t (*specific)(void *obj, H5VL_group_specific_args_t *args, hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, void **req); herr_t (*close)(void *grp, hid_t dxpl_id, void **req); } H5VL_group_class_t; /* H5L routines */ typedef struct H5VL_link_class_t { - herr_t (*create)(H5VL_link_create_type_t create_type, void *obj, const H5VL_loc_params_t *loc_params, - hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req, va_list arguments); + herr_t (*create)(H5VL_link_create_args_t *args, void *obj, const H5VL_loc_params_t *loc_params, + hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req); herr_t (*copy)(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj, const H5VL_loc_params_t *loc_params2, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req); herr_t (*move)(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj, const H5VL_loc_params_t *loc_params2, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req); - herr_t (*get)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_link_get_t get_type, hid_t dxpl_id, - void **req, va_list arguments); - herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_link_specific_t specific_type, - hid_t dxpl_id, void **req, va_list arguments); - herr_t (*optional)(void *obj, H5VL_link_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments); + herr_t (*get)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_link_get_args_t *args, hid_t dxpl_id, + void **req); + herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_link_specific_args_t *args, + hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_optional_args_t *args, + hid_t dxpl_id, void **req); } H5VL_link_class_t; /* H5O routines */ @@ -385,16 +949,16 @@ typedef struct H5VL_object_class_t { herr_t (*copy)(void *src_obj, const H5VL_loc_params_t *loc_params1, const char *src_name, void *dst_obj, const H5VL_loc_params_t *loc_params2, const char *dst_name, hid_t ocpypl_id, hid_t lcpl_id, hid_t dxpl_id, void **req); - herr_t (*get)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_object_get_t get_type, hid_t dxpl_id, - void **req, va_list arguments); - herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_object_specific_t specific_type, - hid_t dxpl_id, void **req, va_list arguments); - herr_t (*optional)(void *obj, H5VL_object_optional_t opt_type, hid_t dxpl_id, void **req, - va_list arguments); + herr_t (*get)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_object_get_args_t *args, hid_t dxpl_id, + void **req); + herr_t (*specific)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_object_specific_args_t *args, + hid_t dxpl_id, void **req); + herr_t (*optional)(void *obj, const H5VL_loc_params_t *loc_params, H5VL_optional_args_t *args, + hid_t dxpl_id, void **req); } H5VL_object_class_t; /* Asynchronous request 'notify' callback */ -typedef herr_t (*H5VL_request_notify_t)(void *ctx, H5ES_status_t status); +typedef herr_t (*H5VL_request_notify_t)(void *ctx, H5VL_request_status_t status); /* "Levels" for 'get connector class' introspection callback */ typedef enum H5VL_get_conn_lvl_t { @@ -410,16 +974,17 @@ struct H5VL_class_t; /* Container/connector introspection routines */ typedef struct H5VL_introspect_class_t { herr_t (*get_conn_cls)(void *obj, H5VL_get_conn_lvl_t lvl, const struct H5VL_class_t **conn_cls); - herr_t (*opt_query)(void *obj, H5VL_subclass_t cls, int opt_type, hbool_t *supported); + herr_t (*get_cap_flags)(const void *info, uint64_t *cap_flags); + herr_t (*opt_query)(void *obj, H5VL_subclass_t cls, int opt_type, uint64_t *flags); } H5VL_introspect_class_t; /* Async request operation routines */ typedef struct H5VL_request_class_t { - herr_t (*wait)(void *req, uint64_t timeout, H5ES_status_t *status); + herr_t (*wait)(void *req, uint64_t timeout, H5VL_request_status_t *status); herr_t (*notify)(void *req, H5VL_request_notify_t cb, void *ctx); - herr_t (*cancel)(void *req); - herr_t (*specific)(void *req, H5VL_request_specific_t specific_type, va_list arguments); - herr_t (*optional)(void *req, H5VL_request_optional_t opt_type, va_list arguments); + herr_t (*cancel)(void *req, H5VL_request_status_t *status); + herr_t (*specific)(void *req, H5VL_request_specific_args_t *args); + herr_t (*optional)(void *req, H5VL_optional_args_t *args); herr_t (*free)(void *req); } H5VL_request_class_t; @@ -427,8 +992,8 @@ typedef struct H5VL_request_class_t { typedef struct H5VL_blob_class_t { herr_t (*put)(void *obj, const void *buf, size_t size, void *blob_id, void *ctx); herr_t (*get)(void *obj, const void *blob_id, void *buf, size_t size, void *ctx); - herr_t (*specific)(void *obj, void *blob_id, H5VL_blob_specific_t specific_type, va_list arguments); - herr_t (*optional)(void *obj, void *blob_id, H5VL_blob_optional_t opt_type, va_list arguments); + herr_t (*specific)(void *obj, void *blob_id, H5VL_blob_specific_args_t *args); + herr_t (*optional)(void *obj, void *blob_id, H5VL_optional_args_t *args); } H5VL_blob_class_t; /* Object token routines */ @@ -445,12 +1010,13 @@ typedef struct H5VL_token_class_t { //! typedef struct H5VL_class_t { /* Overall connector fields & callbacks */ - unsigned version; /**< VOL connector class struct version # */ - H5VL_class_value_t value; /**< Value to identify connector */ - const char * name; /**< Connector name (MUST be unique!) */ - unsigned cap_flags; /**< Capability flags for connector */ - herr_t (*initialize)(hid_t vipl_id); /**< Connector initialization callback */ - herr_t (*terminate)(void); /**< Connector termination callback */ + unsigned version; /**< VOL connector class struct version number */ + H5VL_class_value_t value; /**< Value to identify connector */ + const char *name; /**< Connector name (MUST be unique!) */ + unsigned conn_version; /**< Version number of connector */ + uint64_t cap_flags; /**< Capability flags for connector */ + herr_t (*initialize)(hid_t vipl_id); /**< Connector initialization callback */ + herr_t (*terminate)(void); /**< Connector termination callback */ /* VOL framework */ H5VL_info_class_t info_cls; /**< VOL info fields & callbacks */ @@ -472,8 +1038,8 @@ typedef struct H5VL_class_t { H5VL_token_class_t token_cls; /**< VOL connector object token class callbacks */ /* Catch-all */ - herr_t (*optional)(void *obj, int op_type, hid_t dxpl_id, void **req, - va_list arguments); /**< Optional callback */ + herr_t (*optional)(void *obj, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); /**< Optional callback */ } H5VL_class_t; //! @@ -539,6 +1105,53 @@ H5_DLL hid_t H5VLpeek_connector_id_by_name(const char *name); */ H5_DLL hid_t H5VLpeek_connector_id_by_value(H5VL_class_value_t value); +/* User-defined optional operations */ +H5_DLL herr_t H5VLregister_opt_operation(H5VL_subclass_t subcls, const char *op_name, int *op_val); +H5_DLL herr_t H5VLfind_opt_operation(H5VL_subclass_t subcls, const char *op_name, int *op_val); +H5_DLL herr_t H5VLunregister_opt_operation(H5VL_subclass_t subcls, const char *op_name); +H5_DLL herr_t H5VLattr_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t attr_id, H5VL_optional_args_t *args, hid_t dxpl_id, hid_t es_id); +H5_DLL herr_t H5VLdataset_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t dset_id, H5VL_optional_args_t *args, hid_t dxpl_id, hid_t es_id); +H5_DLL herr_t H5VLdatatype_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t type_id, H5VL_optional_args_t *args, hid_t dxpl_id, hid_t es_id); +H5_DLL herr_t H5VLfile_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t file_id, H5VL_optional_args_t *args, hid_t dxpl_id, hid_t es_id); +H5_DLL herr_t H5VLgroup_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t group_id, H5VL_optional_args_t *args, hid_t dxpl_id, hid_t es_id); +H5_DLL herr_t H5VLlink_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t loc_id, const char *name, hid_t lapl_id, H5VL_optional_args_t *args, + hid_t dxpl_id, hid_t es_id); +H5_DLL herr_t H5VLobject_optional_op(const char *app_file, const char *app_func, unsigned app_line, + hid_t loc_id, const char *name, hid_t lapl_id, + H5VL_optional_args_t *args, hid_t dxpl_id, hid_t es_id); +H5_DLL herr_t H5VLrequest_optional_op(void *req, hid_t connector_id, H5VL_optional_args_t *args); + +/* API Wrappers for "optional_op" routines */ +/* (Must be defined _after_ the function prototype) */ +/* (And must only defined when included in application code, not the library) */ +#ifndef H5VL_MODULE +/* Inject application compile-time macros into function calls */ +#define H5VLattr_optional_op(...) H5VLattr_optional_op(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5VLdataset_optional_op(...) H5VLdataset_optional_op(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5VLdatatype_optional_op(...) H5VLdatatype_optional_op(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5VLfile_optional_op(...) H5VLfile_optional_op(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5VLgroup_optional_op(...) H5VLgroup_optional_op(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5VLlink_optional_op(...) H5VLlink_optional_op(__FILE__, __func__, __LINE__, __VA_ARGS__) +#define H5VLobject_optional_op(...) H5VLobject_optional_op(__FILE__, __func__, __LINE__, __VA_ARGS__) + +/* Define "wrapper" versions of function calls, to allow compile-time values to + * be passed in by language wrapper or library layer on top of HDF5. + */ +#define H5VLattr_optional_op_wrap H5_NO_EXPAND(H5VLattr_optional_op) +#define H5VLdataset_optional_op_wrap H5_NO_EXPAND(H5VLdataset_optional_op) +#define H5VLdatatype_optional_op_wrap H5_NO_EXPAND(H5VLdatatype_optional_op) +#define H5VLfile_optional_op_wrap H5_NO_EXPAND(H5VLfile_optional_op) +#define H5VLgroup_optional_op_wrap H5_NO_EXPAND(H5VLgroup_optional_op) +#define H5VLlink_optional_op_wrap H5_NO_EXPAND(H5VLlink_optional_op) +#define H5VLobject_optional_op_wrap H5_NO_EXPAND(H5VLobject_optional_op) +#endif /* H5VL_MODULE */ + #ifdef __cplusplus } #endif diff --git a/libs/windows/include/H5VLconnector_passthru.h b/libs/windows/include/H5VLconnector_passthru.h index 1b6715b..d10bac4 100644 --- a/libs/windows/include/H5VLconnector_passthru.h +++ b/libs/windows/include/H5VLconnector_passthru.h @@ -56,23 +56,48 @@ extern "C" { /* Helper routines for VOL connector authors */ H5_DLL herr_t H5VLcmp_connector_cls(int *cmp, hid_t connector_id1, hid_t connector_id2); +/** + * \ingroup H5VL + * + * \brief Wrap an internal object with a "wrap context" and register an + * hid_t for the resulting object. + * + * \param[in] obj VOL object. + * \param[in] type VOL-managed object class. Allowable values are: + * - #H5I_FILE + * - #H5I_GROUP + * - #H5I_DATATYPE + * - #H5I_DATASET + * - #H5I_MAP + * - #H5I_ATTR + * + * \return \hid_t{VOL connector} + * + * \note This routine is mainly targeted toward wrapping objects for + * iteration routine callbacks (i.e. the callbacks from H5Aiterate*, + * H5Literate* / H5Lvisit*, and H5Ovisit* ). Using it in an application + * will return an error indicating the API context isn't available or + * can't be retrieved. + * + */ H5_DLL hid_t H5VLwrap_register(void *obj, H5I_type_t type); H5_DLL herr_t H5VLretrieve_lib_state(void **state); +H5_DLL herr_t H5VLstart_lib_state(void); H5_DLL herr_t H5VLrestore_lib_state(const void *state); -H5_DLL herr_t H5VLreset_lib_state(void); +H5_DLL herr_t H5VLfinish_lib_state(void); H5_DLL herr_t H5VLfree_lib_state(void *state); /* Pass-through callbacks */ -H5_DLL void * H5VLget_object(void *obj, hid_t connector_id); +H5_DLL void *H5VLget_object(void *obj, hid_t connector_id); H5_DLL herr_t H5VLget_wrap_ctx(void *obj, hid_t connector_id, void **wrap_ctx); -H5_DLL void * H5VLwrap_object(void *obj, H5I_type_t obj_type, hid_t connector_id, void *wrap_ctx); -H5_DLL void * H5VLunwrap_object(void *obj, hid_t connector_id); +H5_DLL void *H5VLwrap_object(void *obj, H5I_type_t obj_type, hid_t connector_id, void *wrap_ctx); +H5_DLL void *H5VLunwrap_object(void *obj, hid_t connector_id); H5_DLL herr_t H5VLfree_wrap_ctx(void *wrap_ctx, hid_t connector_id); /* Public wrappers for generic callbacks */ H5_DLL herr_t H5VLinitialize(hid_t connector_id, hid_t vipl_id); H5_DLL herr_t H5VLterminate(hid_t connector_id); -H5_DLL herr_t H5VLget_cap_flags(hid_t connector_id, unsigned *cap_flags); +H5_DLL herr_t H5VLget_cap_flags(hid_t connector_id, uint64_t *cap_flags); H5_DLL herr_t H5VLget_value(hid_t connector_id, H5VL_class_value_t *conn_value); /* Public wrappers for info fields and callbacks */ @@ -83,86 +108,86 @@ H5_DLL herr_t H5VLconnector_info_to_str(const void *info, hid_t connector_id, ch H5_DLL herr_t H5VLconnector_str_to_info(const char *str, hid_t connector_id, void **info); /* Public wrappers for attribute callbacks */ -H5_DLL void * H5VLattr_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, +H5_DLL void *H5VLattr_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *attr_name, hid_t type_id, hid_t space_id, hid_t acpl_id, hid_t aapl_id, hid_t dxpl_id, void **req); -H5_DLL void * H5VLattr_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, +H5_DLL void *H5VLattr_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, hid_t aapl_id, hid_t dxpl_id, void **req); H5_DLL herr_t H5VLattr_read(void *attr, hid_t connector_id, hid_t dtype_id, void *buf, hid_t dxpl_id, void **req); H5_DLL herr_t H5VLattr_write(void *attr, hid_t connector_id, hid_t dtype_id, const void *buf, hid_t dxpl_id, void **req); -H5_DLL herr_t H5VLattr_get(void *obj, hid_t connector_id, H5VL_attr_get_t get_type, hid_t dxpl_id, void **req, - va_list arguments); +H5_DLL herr_t H5VLattr_get(void *obj, hid_t connector_id, H5VL_attr_get_args_t *args, hid_t dxpl_id, + void **req); H5_DLL herr_t H5VLattr_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, - H5VL_attr_specific_t specific_type, hid_t dxpl_id, void **req, - va_list arguments); -H5_DLL herr_t H5VLattr_optional(void *obj, hid_t connector_id, H5VL_attr_optional_t opt_type, hid_t dxpl_id, - void **req, va_list arguments); + H5VL_attr_specific_args_t *args, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLattr_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); H5_DLL herr_t H5VLattr_close(void *attr, hid_t connector_id, hid_t dxpl_id, void **req); /* Public wrappers for dataset callbacks */ -H5_DLL void * H5VLdataset_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, +H5_DLL void *H5VLdataset_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, hid_t lcpl_id, hid_t type_id, hid_t space_id, hid_t dcpl_id, hid_t dapl_id, hid_t dxpl_id, void **req); -H5_DLL void * H5VLdataset_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, +H5_DLL void *H5VLdataset_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, hid_t dapl_id, hid_t dxpl_id, void **req); -H5_DLL herr_t H5VLdataset_read(void *dset, hid_t connector_id, hid_t mem_type_id, hid_t mem_space_id, - hid_t file_space_id, hid_t plist_id, void *buf, void **req); -H5_DLL herr_t H5VLdataset_write(void *dset, hid_t connector_id, hid_t mem_type_id, hid_t mem_space_id, - hid_t file_space_id, hid_t plist_id, const void *buf, void **req); -H5_DLL herr_t H5VLdataset_get(void *dset, hid_t connector_id, H5VL_dataset_get_t get_type, hid_t dxpl_id, - void **req, va_list arguments); -H5_DLL herr_t H5VLdataset_specific(void *obj, hid_t connector_id, H5VL_dataset_specific_t specific_type, - hid_t dxpl_id, void **req, va_list arguments); -H5_DLL herr_t H5VLdataset_optional(void *obj, hid_t connector_id, H5VL_dataset_optional_t opt_type, - hid_t dxpl_id, void **req, va_list arguments); +H5_DLL herr_t H5VLdataset_read(size_t count, void *dset[], hid_t connector_id, hid_t mem_type_id[], + hid_t mem_space_id[], hid_t file_space_id[], hid_t plist_id, void *buf[], + void **req); +H5_DLL herr_t H5VLdataset_write(size_t count, void *dset[], hid_t connector_id, hid_t mem_type_id[], + hid_t mem_space_id[], hid_t file_space_id[], hid_t plist_id, + const void *buf[], void **req); +H5_DLL herr_t H5VLdataset_get(void *dset, hid_t connector_id, H5VL_dataset_get_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLdataset_specific(void *obj, hid_t connector_id, H5VL_dataset_specific_args_t *args, + hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLdataset_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); H5_DLL herr_t H5VLdataset_close(void *dset, hid_t connector_id, hid_t dxpl_id, void **req); /* Public wrappers for named datatype callbacks */ -H5_DLL void * H5VLdatatype_commit(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, +H5_DLL void *H5VLdatatype_commit(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, hid_t type_id, hid_t lcpl_id, hid_t tcpl_id, hid_t tapl_id, hid_t dxpl_id, void **req); -H5_DLL void * H5VLdatatype_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, +H5_DLL void *H5VLdatatype_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, hid_t tapl_id, hid_t dxpl_id, void **req); -H5_DLL herr_t H5VLdatatype_get(void *dt, hid_t connector_id, H5VL_datatype_get_t get_type, hid_t dxpl_id, - void **req, va_list arguments); -H5_DLL herr_t H5VLdatatype_specific(void *obj, hid_t connector_id, H5VL_datatype_specific_t specific_type, - hid_t dxpl_id, void **req, va_list arguments); -H5_DLL herr_t H5VLdatatype_optional(void *obj, hid_t connector_id, H5VL_datatype_optional_t opt_type, - hid_t dxpl_id, void **req, va_list arguments); +H5_DLL herr_t H5VLdatatype_get(void *dt, hid_t connector_id, H5VL_datatype_get_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLdatatype_specific(void *obj, hid_t connector_id, H5VL_datatype_specific_args_t *args, + hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLdatatype_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); H5_DLL herr_t H5VLdatatype_close(void *dt, hid_t connector_id, hid_t dxpl_id, void **req); /* Public wrappers for file callbacks */ -H5_DLL void * H5VLfile_create(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t dxpl_id, +H5_DLL void *H5VLfile_create(const char *name, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t dxpl_id, void **req); -H5_DLL void * H5VLfile_open(const char *name, unsigned flags, hid_t fapl_id, hid_t dxpl_id, void **req); -H5_DLL herr_t H5VLfile_get(void *file, hid_t connector_id, H5VL_file_get_t get_type, hid_t dxpl_id, - void **req, va_list arguments); -H5_DLL herr_t H5VLfile_specific(void *obj, hid_t connector_id, H5VL_file_specific_t specific_type, - hid_t dxpl_id, void **req, va_list arguments); -H5_DLL herr_t H5VLfile_optional(void *obj, hid_t connector_id, H5VL_file_optional_t opt_type, hid_t dxpl_id, - void **req, va_list arguments); +H5_DLL void *H5VLfile_open(const char *name, unsigned flags, hid_t fapl_id, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLfile_get(void *file, hid_t connector_id, H5VL_file_get_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLfile_specific(void *obj, hid_t connector_id, H5VL_file_specific_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLfile_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); H5_DLL herr_t H5VLfile_close(void *file, hid_t connector_id, hid_t dxpl_id, void **req); /* Public wrappers for group callbacks */ -H5_DLL void * H5VLgroup_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, +H5_DLL void *H5VLgroup_create(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, hid_t lcpl_id, hid_t gcpl_id, hid_t gapl_id, hid_t dxpl_id, void **req); -H5_DLL void * H5VLgroup_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, +H5_DLL void *H5VLgroup_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, const char *name, hid_t gapl_id, hid_t dxpl_id, void **req); -H5_DLL herr_t H5VLgroup_get(void *obj, hid_t connector_id, H5VL_group_get_t get_type, hid_t dxpl_id, - void **req, va_list arguments); -H5_DLL herr_t H5VLgroup_specific(void *obj, hid_t connector_id, H5VL_group_specific_t specific_type, - hid_t dxpl_id, void **req, va_list arguments); -H5_DLL herr_t H5VLgroup_optional(void *obj, hid_t connector_id, H5VL_group_optional_t opt_type, hid_t dxpl_id, - void **req, va_list arguments); +H5_DLL herr_t H5VLgroup_get(void *obj, hid_t connector_id, H5VL_group_get_args_t *args, hid_t dxpl_id, + void **req); +H5_DLL herr_t H5VLgroup_specific(void *obj, hid_t connector_id, H5VL_group_specific_args_t *args, + hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLgroup_optional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); H5_DLL herr_t H5VLgroup_close(void *grp, hid_t connector_id, hid_t dxpl_id, void **req); /* Public wrappers for link callbacks */ -H5_DLL herr_t H5VLlink_create(H5VL_link_create_type_t create_type, void *obj, - const H5VL_loc_params_t *loc_params, hid_t connector_id, hid_t lcpl_id, - hid_t lapl_id, hid_t dxpl_id, void **req, va_list arguments); +H5_DLL herr_t H5VLlink_create(H5VL_link_create_args_t *args, void *obj, const H5VL_loc_params_t *loc_params, + hid_t connector_id, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req); H5_DLL herr_t H5VLlink_copy(void *src_obj, const H5VL_loc_params_t *loc_params1, void *dst_obj, const H5VL_loc_params_t *loc_params2, hid_t connector_id, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req); @@ -170,41 +195,39 @@ H5_DLL herr_t H5VLlink_move(void *src_obj, const H5VL_loc_params_t *loc_params1, const H5VL_loc_params_t *loc_params2, hid_t connector_id, hid_t lcpl_id, hid_t lapl_id, hid_t dxpl_id, void **req); H5_DLL herr_t H5VLlink_get(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, - H5VL_link_get_t get_type, hid_t dxpl_id, void **req, va_list arguments); + H5VL_link_get_args_t *args, hid_t dxpl_id, void **req); H5_DLL herr_t H5VLlink_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, - H5VL_link_specific_t specific_type, hid_t dxpl_id, void **req, - va_list arguments); -H5_DLL herr_t H5VLlink_optional(void *obj, hid_t connector_id, H5VL_link_optional_t opt_type, hid_t dxpl_id, - void **req, va_list arguments); + H5VL_link_specific_args_t *args, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLlink_optional(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + H5VL_optional_args_t *args, hid_t dxpl_id, void **req); /* Public wrappers for object callbacks */ -H5_DLL void * H5VLobject_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, +H5_DLL void *H5VLobject_open(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, H5I_type_t *opened_type, hid_t dxpl_id, void **req); H5_DLL herr_t H5VLobject_copy(void *src_obj, const H5VL_loc_params_t *loc_params1, const char *src_name, void *dst_obj, const H5VL_loc_params_t *loc_params2, const char *dst_name, hid_t connector_id, hid_t ocpypl_id, hid_t lcpl_id, hid_t dxpl_id, void **req); H5_DLL herr_t H5VLobject_get(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, - H5VL_object_get_t get_type, hid_t dxpl_id, void **req, va_list arguments); + H5VL_object_get_args_t *args, hid_t dxpl_id, void **req); H5_DLL herr_t H5VLobject_specific(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, - H5VL_object_specific_t specific_type, hid_t dxpl_id, void **req, - va_list arguments); -H5_DLL herr_t H5VLobject_optional(void *obj, hid_t connector_id, H5VL_object_optional_t opt_type, - hid_t dxpl_id, void **req, va_list arguments); + H5VL_object_specific_args_t *args, hid_t dxpl_id, void **req); +H5_DLL herr_t H5VLobject_optional(void *obj, const H5VL_loc_params_t *loc_params, hid_t connector_id, + H5VL_optional_args_t *args, hid_t dxpl_id, void **req); /* Public wrappers for connector/container introspection callbacks */ H5_DLL herr_t H5VLintrospect_get_conn_cls(void *obj, hid_t connector_id, H5VL_get_conn_lvl_t lvl, const H5VL_class_t **conn_cls); +H5_DLL herr_t H5VLintrospect_get_cap_flags(const void *info, hid_t connector_id, uint64_t *cap_flags); H5_DLL herr_t H5VLintrospect_opt_query(void *obj, hid_t connector_id, H5VL_subclass_t subcls, int opt_type, - hbool_t *supported); + uint64_t *flags); /* Public wrappers for asynchronous request callbacks */ -H5_DLL herr_t H5VLrequest_wait(void *req, hid_t connector_id, uint64_t timeout, H5ES_status_t *status); +H5_DLL herr_t H5VLrequest_wait(void *req, hid_t connector_id, uint64_t timeout, + H5VL_request_status_t *status); H5_DLL herr_t H5VLrequest_notify(void *req, hid_t connector_id, H5VL_request_notify_t cb, void *ctx); -H5_DLL herr_t H5VLrequest_cancel(void *req, hid_t connector_id); -H5_DLL herr_t H5VLrequest_specific(void *req, hid_t connector_id, H5VL_request_specific_t specific_type, - va_list arguments); -H5_DLL herr_t H5VLrequest_optional(void *req, hid_t connector_id, H5VL_request_optional_t opt_type, - va_list arguments); +H5_DLL herr_t H5VLrequest_cancel(void *req, hid_t connector_id, H5VL_request_status_t *status); +H5_DLL herr_t H5VLrequest_specific(void *req, hid_t connector_id, H5VL_request_specific_args_t *args); +H5_DLL herr_t H5VLrequest_optional(void *req, hid_t connector_id, H5VL_optional_args_t *args); H5_DLL herr_t H5VLrequest_free(void *req, hid_t connector_id); /* Public wrappers for blob callbacks */ @@ -213,9 +236,8 @@ H5_DLL herr_t H5VLblob_put(void *obj, hid_t connector_id, const void *buf, size_ H5_DLL herr_t H5VLblob_get(void *obj, hid_t connector_id, const void *blob_id, void *buf, size_t size, void *ctx); H5_DLL herr_t H5VLblob_specific(void *obj, hid_t connector_id, void *blob_id, - H5VL_blob_specific_t specific_type, va_list arguments); -H5_DLL herr_t H5VLblob_optional(void *obj, hid_t connector_id, void *blob_id, H5VL_blob_optional_t opt_type, - va_list arguments); + H5VL_blob_specific_args_t *args); +H5_DLL herr_t H5VLblob_optional(void *obj, hid_t connector_id, void *blob_id, H5VL_optional_args_t *args); /* Public wrappers for token callbacks */ H5_DLL herr_t H5VLtoken_cmp(void *obj, hid_t connector_id, const H5O_token_t *token1, @@ -226,8 +248,8 @@ H5_DLL herr_t H5VLtoken_from_str(void *obj, H5I_type_t obj_type, hid_t connector H5O_token_t *token); /* Public wrappers for generic 'optional' callback */ -H5_DLL herr_t H5VLoptional(void *obj, hid_t connector_id, int op_type, hid_t dxpl_id, void **req, - va_list arguments); +H5_DLL herr_t H5VLoptional(void *obj, hid_t connector_id, H5VL_optional_args_t *args, hid_t dxpl_id, + void **req); #ifdef __cplusplus } diff --git a/libs/windows/include/H5VLnative.h b/libs/windows/include/H5VLnative.h index cb7f0e0..6eaefb6 100644 --- a/libs/windows/include/H5VLnative.h +++ b/libs/windows/include/H5VLnative.h @@ -18,6 +18,7 @@ #define H5VLnative_H /* Public headers needed by this file */ +#include "H5Apublic.h" /* Attributes */ #include "H5VLpublic.h" /* Virtual Object Layer */ /*****************/ @@ -33,23 +34,151 @@ #define H5VL_NATIVE_VERSION 0 /* Values for VOL connector attribute optional VOL operations */ +/* NOTE: If new values are added here, the H5VL__native_introspect_opt_query + * routine must be updated. + */ #ifndef H5_NO_DEPRECATED_SYMBOLS #define H5VL_NATIVE_ATTR_ITERATE_OLD 0 /* H5Aiterate (deprecated routine) */ #endif /* H5_NO_DEPRECATED_SYMBOLS */ +/* NOTE: If values over 1023 are added, the H5VL_RESERVED_NATIVE_OPTIONAL macro + * must be updated. + */ + +#ifndef H5_NO_DEPRECATED_SYMBOLS +/* Parameters for attribute 'iterate old' operation */ +typedef struct H5VL_native_attr_iterate_old_t { + hid_t loc_id; + unsigned *attr_num; + H5A_operator1_t op; + void *op_data; +} H5VL_native_attr_iterate_old_t; + +/* Parameters for native connector's attribute 'optional' operations */ +typedef union H5VL_native_attr_optional_args_t { + /* H5VL_NATIVE_ATTR_ITERATE_OLD */ + H5VL_native_attr_iterate_old_t iterate_old; +} H5VL_native_attr_optional_args_t; +#endif /* H5_NO_DEPRECATED_SYMBOLS */ /* Values for native VOL connector dataset optional VOL operations */ -#define H5VL_NATIVE_DATASET_FORMAT_CONVERT 0 /* H5Dformat_convert (internal) */ -#define H5VL_NATIVE_DATASET_GET_CHUNK_INDEX_TYPE 1 /* H5Dget_chunk_index_type */ -#define H5VL_NATIVE_DATASET_GET_CHUNK_STORAGE_SIZE 2 /* H5Dget_chunk_storage_size */ -#define H5VL_NATIVE_DATASET_GET_NUM_CHUNKS 3 /* H5Dget_num_chunks */ -#define H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_IDX 4 /* H5Dget_chunk_info */ -#define H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_COORD 5 /* H5Dget_chunk_info_by_coord */ -#define H5VL_NATIVE_DATASET_CHUNK_READ 6 /* H5Dchunk_read */ -#define H5VL_NATIVE_DATASET_CHUNK_WRITE 7 /* H5Dchunk_write */ -#define H5VL_NATIVE_DATASET_GET_VLEN_BUF_SIZE 8 /* H5Dvlen_get_buf_size */ -#define H5VL_NATIVE_DATASET_GET_OFFSET 9 /* H5Dget_offset */ +/* NOTE: If new values are added here, the H5VL__native_introspect_opt_query + * routine must be updated. + */ +#define H5VL_NATIVE_DATASET_FORMAT_CONVERT 0 /* H5Dformat_convert (internal) */ +#define H5VL_NATIVE_DATASET_GET_CHUNK_INDEX_TYPE 1 /* H5Dget_chunk_index_type */ +#define H5VL_NATIVE_DATASET_GET_CHUNK_STORAGE_SIZE 2 /* H5Dget_chunk_storage_size */ +#define H5VL_NATIVE_DATASET_GET_NUM_CHUNKS 3 /* H5Dget_num_chunks */ +#define H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_IDX 4 /* H5Dget_chunk_info */ +#define H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_COORD 5 /* H5Dget_chunk_info_by_coord */ +#define H5VL_NATIVE_DATASET_CHUNK_READ 6 /* H5Dchunk_read */ +#define H5VL_NATIVE_DATASET_CHUNK_WRITE 7 /* H5Dchunk_write */ +#define H5VL_NATIVE_DATASET_GET_VLEN_BUF_SIZE 8 /* H5Dvlen_get_buf_size */ +#define H5VL_NATIVE_DATASET_GET_OFFSET 9 /* H5Dget_offset */ +#define H5VL_NATIVE_DATASET_CHUNK_ITER 10 /* H5Dchunk_iter */ +/* NOTE: If values over 1023 are added, the H5VL_RESERVED_NATIVE_OPTIONAL macro + * must be updated. + */ + +/* Parameters for native connector's dataset 'chunk read' operation */ +typedef struct H5VL_native_dataset_chunk_read_t { + const hsize_t *offset; + uint32_t filters; + void *buf; +} H5VL_native_dataset_chunk_read_t; + +/* Parameters for native connector's dataset 'chunk write' operation */ +typedef struct H5VL_native_dataset_chunk_write_t { + const hsize_t *offset; + uint32_t filters; + uint32_t size; + const void *buf; +} H5VL_native_dataset_chunk_write_t; + +/* Parameters for native connector's dataset 'get vlen buf size' operation */ +typedef struct H5VL_native_dataset_get_vlen_buf_size_t { + hid_t type_id; + hid_t space_id; + hsize_t *size; /* Size of variable-length data buffer (OUT) */ +} H5VL_native_dataset_get_vlen_buf_size_t; + +/* Parameters for native connector's dataset 'get chunk storage size' operation */ +typedef struct H5VL_native_dataset_get_chunk_storage_size_t { + const hsize_t *offset; /* Offset of chunk */ + hsize_t *size; /* Size of chunk (OUT) */ +} H5VL_native_dataset_get_chunk_storage_size_t; + +/* Parameters for native connector's dataset 'get num chunks' operation */ +typedef struct H5VL_native_dataset_get_num_chunks_t { + hid_t space_id; /* Space selection */ + hsize_t *nchunks; /* # of chunk for space selection (OUT) */ +} H5VL_native_dataset_get_num_chunks_t; + +/* Parameters for native connector's dataset 'get chunk info by idx' operation */ +typedef struct H5VL_native_dataset_get_chunk_info_by_idx_t { + hid_t space_id; /* Space selection */ + hsize_t chk_index; /* Chunk index within space */ + hsize_t *offset; /* Chunk coordinates (OUT) */ + unsigned *filter_mask; /* Filter mask for chunk (OUT) */ + haddr_t *addr; /* Address of chunk in file (OUT) */ + hsize_t *size; /* Size of chunk in file (OUT) */ +} H5VL_native_dataset_get_chunk_info_by_idx_t; + +/* Parameters for native connector's dataset 'get chunk info by coord' operation */ +typedef struct H5VL_native_dataset_get_chunk_info_by_coord_t { + const hsize_t *offset; /* Chunk coordinates */ + unsigned *filter_mask; /* Filter mask for chunk (OUT) */ + haddr_t *addr; /* Address of chunk in file (OUT) */ + hsize_t *size; /* Size of chunk in file (OUT) */ +} H5VL_native_dataset_get_chunk_info_by_coord_t; + +/* Parameters for native connector's dataset 'optional' operations */ +typedef union H5VL_native_dataset_optional_args_t { + /* H5VL_NATIVE_DATASET_FORMAT_CONVERT */ + /* No args */ + + /* H5VL_NATIVE_DATASET_GET_CHUNK_INDEX_TYPE */ + struct { + H5D_chunk_index_t *idx_type; /* Type of chunk index (OUT) */ + } get_chunk_idx_type; + + /* H5VL_NATIVE_DATASET_GET_CHUNK_STORAGE_SIZE */ + H5VL_native_dataset_get_chunk_storage_size_t get_chunk_storage_size; + + /* H5VL_NATIVE_DATASET_GET_NUM_CHUNKS */ + H5VL_native_dataset_get_num_chunks_t get_num_chunks; + + /* H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_IDX */ + H5VL_native_dataset_get_chunk_info_by_idx_t get_chunk_info_by_idx; + + /* H5VL_NATIVE_DATASET_GET_CHUNK_INFO_BY_COORD */ + H5VL_native_dataset_get_chunk_info_by_coord_t get_chunk_info_by_coord; + + /* H5VL_NATIVE_DATASET_CHUNK_READ */ + H5VL_native_dataset_chunk_read_t chunk_read; + + /* H5VL_NATIVE_DATASET_CHUNK_WRITE */ + H5VL_native_dataset_chunk_write_t chunk_write; + + /* H5VL_NATIVE_DATASET_GET_VLEN_BUF_SIZE */ + H5VL_native_dataset_get_vlen_buf_size_t get_vlen_buf_size; + + /* H5VL_NATIVE_DATASET_GET_OFFSET */ + struct { + haddr_t *offset; /* Contiguous dataset's offset in the file (OUT) */ + } get_offset; + + /* H5VL_NATIVE_DATASET_CHUNK_ITER */ + struct { + H5D_chunk_iter_op_t op; /* Chunk iteration callback */ + void *op_data; /* Context to pass to iteration callback */ + } chunk_iter; + +} H5VL_native_dataset_optional_args_t; /* Values for native VOL connector file optional VOL operations */ +/* NOTE: If new values are added here, the H5VL__native_introspect_opt_query + * routine must be updated. + */ #define H5VL_NATIVE_FILE_CLEAR_ELINK_CACHE 0 /* H5Fclear_elink_file_cache */ #define H5VL_NATIVE_FILE_GET_FILE_IMAGE 1 /* H5Fget_file_image */ #define H5VL_NATIVE_FILE_GET_FREE_SECTIONS 2 /* H5Fget_free_sections */ @@ -76,23 +205,286 @@ #define H5VL_NATIVE_FILE_SET_LIBVER_BOUNDS 23 /* H5Fset_latest_format/libver_bounds */ #define H5VL_NATIVE_FILE_GET_MIN_DSET_OHDR_FLAG 24 /* H5Fget_dset_no_attrs_hint */ #define H5VL_NATIVE_FILE_SET_MIN_DSET_OHDR_FLAG 25 /* H5Fset_dset_no_attrs_hint */ -#define H5VL_NATIVE_FILE_GET_MPI_ATOMICITY 26 /* H5Fget_mpi_atomicity */ -#define H5VL_NATIVE_FILE_SET_MPI_ATOMICITY 27 /* H5Fset_mpi_atomicity */ -#define H5VL_NATIVE_FILE_POST_OPEN 28 /* Adjust file after open, with wrapping context */ +#ifdef H5_HAVE_PARALLEL +#define H5VL_NATIVE_FILE_GET_MPI_ATOMICITY 26 /* H5Fget_mpi_atomicity */ +#define H5VL_NATIVE_FILE_SET_MPI_ATOMICITY 27 /* H5Fset_mpi_atomicity */ +#endif +#define H5VL_NATIVE_FILE_POST_OPEN 28 /* Adjust file after open, with wrapping context */ +/* NOTE: If values over 1023 are added, the H5VL_RESERVED_NATIVE_OPTIONAL macro + * must be updated. + */ + +/* Parameters for native connector's file 'get file image' operation */ +typedef struct H5VL_native_file_get_file_image_t { + size_t buf_size; /* Size of file image buffer */ + void *buf; /* Buffer for file image (OUT) */ + size_t *image_len; /* Size of file image (OUT) */ +} H5VL_native_file_get_file_image_t; + +/* Parameters for native connector's file 'get free sections' operation */ +typedef struct H5VL_native_file_get_free_sections_t { + H5F_mem_t type; /* Type of file memory to query */ + H5F_sect_info_t *sect_info; /* Array of sections (OUT) */ + size_t nsects; /* Size of section array */ + size_t *sect_count; /* Actual # of sections of type (OUT) */ +} H5VL_native_file_get_free_sections_t; + +/* Parameters for native connector's file 'get freespace' operation */ +typedef struct H5VL_native_file_get_freespace_t { + hsize_t *size; /* Size of free space (OUT) */ +} H5VL_native_file_get_freespace_t; + +/* Parameters for native connector's file 'get info' operation */ +typedef struct H5VL_native_file_get_info_t { + H5I_type_t type; /* Type of object */ + H5F_info2_t *finfo; /* Pointer to file info (OUT) */ +} H5VL_native_file_get_info_t; + +/* Parameters for native connector's file 'get metadata cache size' operation */ +typedef struct H5VL_native_file_get_mdc_size_t { + size_t *max_size; /* Maximum amount of cached data (OUT) */ + size_t *min_clean_size; /* Minimum amount of cached data to keep clean (OUT) */ + size_t *cur_size; /* Current amount of cached data (OUT) */ + uint32_t *cur_num_entries; /* Current # of cached entries (OUT) */ +} H5VL_native_file_get_mdc_size_t; + +/* Parameters for native connector's file 'get VFD handle' operation */ +typedef struct H5VL_native_file_get_vfd_handle_t { + hid_t fapl_id; + void **file_handle; /* File handle from VFD (OUT) */ +} H5VL_native_file_get_vfd_handle_t; + +/* Parameters for native connector's file 'get MDC logging status' operation */ +typedef struct H5VL_native_file_get_mdc_logging_status_t { + hbool_t *is_enabled; /* Whether logging is enabled (OUT) */ + hbool_t *is_currently_logging; /* Whether currently logging (OUT) */ +} H5VL_native_file_get_mdc_logging_status_t; + +/* Parameters for native connector's file 'get page buffering stats' operation */ +typedef struct H5VL_native_file_get_page_buffering_stats_t { + unsigned *accesses; /* Metadata/raw data page access counts (OUT) */ + unsigned *hits; /* Metadata/raw data page hit counts (OUT) */ + unsigned *misses; /* Metadata/raw data page miss counts (OUT) */ + unsigned *evictions; /* Metadata/raw data page eviction counts (OUT) */ + unsigned *bypasses; /* Metadata/raw data page bypass counts (OUT) */ +} H5VL_native_file_get_page_buffering_stats_t; + +/* Parameters for native connector's file 'get MDC image info' operation */ +typedef struct H5VL_native_file_get_mdc_image_info_t { + haddr_t *addr; /* Address of image (OUT) */ + hsize_t *len; /* Length of image (OUT) */ +} H5VL_native_file_get_mdc_image_info_t; + +/* Parameters for native connector's file 'set libver bounds' operation */ +typedef struct H5VL_native_file_set_libver_bounds_t { + H5F_libver_t low; /* Lowest version possible */ + H5F_libver_t high; /* Highest version possible */ +} H5VL_native_file_set_libver_bounds_t; + +/* Parameters for native connector's file 'optional' operations */ +typedef union H5VL_native_file_optional_args_t { + /* H5VL_NATIVE_FILE_CLEAR_ELINK_CACHE */ + /* No args */ + + /* H5VL_NATIVE_FILE_GET_FILE_IMAGE */ + H5VL_native_file_get_file_image_t get_file_image; + + /* H5VL_NATIVE_FILE_GET_FREE_SECTIONS */ + H5VL_native_file_get_free_sections_t get_free_sections; + + /* H5VL_NATIVE_FILE_GET_FREE_SPACE */ + H5VL_native_file_get_freespace_t get_freespace; + + /* H5VL_NATIVE_FILE_GET_INFO */ + H5VL_native_file_get_info_t get_info; + + /* H5VL_NATIVE_FILE_GET_MDC_CONF */ + struct { + H5AC_cache_config_t *config; /* Pointer to MDC config (OUT) */ + } get_mdc_config; + + /* H5VL_NATIVE_FILE_GET_MDC_HR */ + struct { + double *hit_rate; /* Metadata cache hit rate (OUT) */ + } get_mdc_hit_rate; + + /* H5VL_NATIVE_FILE_GET_MDC_SIZE */ + H5VL_native_file_get_mdc_size_t get_mdc_size; + + /* H5VL_NATIVE_FILE_GET_SIZE */ + struct { + hsize_t *size; /* Size of file (OUT) */ + } get_size; + + /* H5VL_NATIVE_FILE_GET_VFD_HANDLE */ + H5VL_native_file_get_vfd_handle_t get_vfd_handle; + + /* H5VL_NATIVE_FILE_RESET_MDC_HIT_RATE */ + /* No args */ + + /* H5VL_NATIVE_FILE_SET_MDC_CONFIG */ + struct { + const H5AC_cache_config_t *config; /* Pointer to new MDC config */ + } set_mdc_config; + + /* H5VL_NATIVE_FILE_GET_METADATA_READ_RETRY_INFO */ + struct { + H5F_retry_info_t *info; /* Pointer to metadata read retry info (OUT) */ + } get_metadata_read_retry_info; + + /* H5VL_NATIVE_FILE_START_SWMR_WRITE */ + /* No args */ + + /* H5VL_NATIVE_FILE_START_MDC_LOGGING */ + /* No args */ + + /* H5VL_NATIVE_FILE_STOP_MDC_LOGGING */ + /* No args */ + + /* H5VL_NATIVE_FILE_GET_MDC_LOGGING_STATUS */ + H5VL_native_file_get_mdc_logging_status_t get_mdc_logging_status; + + /* H5VL_NATIVE_FILE_FORMAT_CONVERT */ + /* No args */ + + /* H5VL_NATIVE_FILE_RESET_PAGE_BUFFERING_STATS */ + /* No args */ + + /* H5VL_NATIVE_FILE_GET_PAGE_BUFFERING_STATS */ + H5VL_native_file_get_page_buffering_stats_t get_page_buffering_stats; + + /* H5VL_NATIVE_FILE_GET_MDC_IMAGE_INFO */ + H5VL_native_file_get_mdc_image_info_t get_mdc_image_info; + + /* H5VL_NATIVE_FILE_GET_EOA */ + struct { + haddr_t *eoa; /* End of allocated file address space (OUT) */ + } get_eoa; + + /* H5VL_NATIVE_FILE_INCR_FILESIZE */ + struct { + hsize_t increment; /* Amount to increment file size */ + } increment_filesize; + + /* H5VL_NATIVE_FILE_SET_LIBVER_BOUNDS */ + H5VL_native_file_set_libver_bounds_t set_libver_bounds; + + /* H5VL_NATIVE_FILE_GET_MIN_DSET_OHDR_FLAG */ + struct { + hbool_t *minimize; /* Flag whether dataset object headers are minimal (OUT) */ + } get_min_dset_ohdr_flag; + + /* H5VL_NATIVE_FILE_SET_MIN_DSET_OHDR_FLAG */ + struct { + hbool_t minimize; /* Flag whether dataset object headers should be minimal */ + } set_min_dset_ohdr_flag; + +#ifdef H5_HAVE_PARALLEL + /* H5VL_NATIVE_FILE_GET_MPI_ATOMICITY */ + struct { + hbool_t *flag; /* Flag whether MPI atomicity is set for files (OUT) */ + } get_mpi_atomicity; + + /* H5VL_NATIVE_FILE_SET_MPI_ATOMICITY */ + struct { + hbool_t flag; /* Flag whether to set MPI atomicity for files */ + } set_mpi_atomicity; +#endif /* H5_HAVE_PARALLEL */ + + /* H5VL_NATIVE_FILE_POST_OPEN */ + /* No args */ +} H5VL_native_file_optional_args_t; /* Values for native VOL connector group optional VOL operations */ +/* NOTE: If new values are added here, the H5VL__native_introspect_opt_query + * routine must be updated. + */ #ifndef H5_NO_DEPRECATED_SYMBOLS #define H5VL_NATIVE_GROUP_ITERATE_OLD 0 /* HG5Giterate (deprecated routine) */ #define H5VL_NATIVE_GROUP_GET_OBJINFO 1 /* HG5Gget_objinfo (deprecated routine) */ #endif /* H5_NO_DEPRECATED_SYMBOLS */ +/* NOTE: If values over 1023 are added, the H5VL_RESERVED_NATIVE_OPTIONAL macro + * must be updated. + */ + +#ifndef H5_NO_DEPRECATED_SYMBOLS +/* Parameters for group 'iterate old' operation */ +typedef struct H5VL_native_group_iterate_old_t { + H5VL_loc_params_t loc_params; /* Location parameters for iteration */ + hsize_t idx; /* Index of link to begin iteration at */ + hsize_t *last_obj; /* Index of last link looked at (OUT) */ + H5G_iterate_t op; /* Group (link) operator callback */ + void *op_data; /* Context to pass to iterator callback */ +} H5VL_native_group_iterate_old_t; + +/* Parameters for group 'get objinfo' operation */ +typedef struct H5VL_native_group_get_objinfo_t { + H5VL_loc_params_t loc_params; /* Location parameters for iteration */ + hbool_t follow_link; /* Whether to follow links for query */ + H5G_stat_t *statbuf; /* Pointer to object info struct (OUT) */ +} H5VL_native_group_get_objinfo_t; + +/* Parameters for native connector's group 'optional' operations */ +typedef union H5VL_native_group_optional_args_t { + /* H5VL_NATIVE_GROUP_ITERATE_OLD */ + H5VL_native_group_iterate_old_t iterate_old; + + /* H5VL_NATIVE_GROUP_GET_OBJINFO */ + H5VL_native_group_get_objinfo_t get_objinfo; +} H5VL_native_group_optional_args_t; +#endif /* H5_NO_DEPRECATED_SYMBOLS */ /* Values for native VOL connector object optional VOL operations */ +/* NOTE: If new values are added here, the H5VL__native_introspect_opt_query + * routine must be updated. + */ #define H5VL_NATIVE_OBJECT_GET_COMMENT 0 /* H5G|H5Oget_comment, H5Oget_comment_by_name */ #define H5VL_NATIVE_OBJECT_SET_COMMENT 1 /* H5G|H5Oset_comment, H5Oset_comment_by_name */ #define H5VL_NATIVE_OBJECT_DISABLE_MDC_FLUSHES 2 /* H5Odisable_mdc_flushes */ #define H5VL_NATIVE_OBJECT_ENABLE_MDC_FLUSHES 3 /* H5Oenable_mdc_flushes */ #define H5VL_NATIVE_OBJECT_ARE_MDC_FLUSHES_DISABLED 4 /* H5Oare_mdc_flushes_disabled */ #define H5VL_NATIVE_OBJECT_GET_NATIVE_INFO 5 /* H5Oget_native_info(_by_idx, _by_name) */ +/* NOTE: If values over 1023 are added, the H5VL_RESERVED_NATIVE_OPTIONAL macro + * must be updated. + */ + +/* Parameters for native connector's object 'get comment' operation */ +typedef struct H5VL_native_object_get_comment_t { + size_t buf_size; /* Size of comment buffer */ + void *buf; /* Buffer for comment (OUT) */ + size_t *comment_len; /* Actual size of comment (OUT) */ +} H5VL_native_object_get_comment_t; + +/* Parameters for object 'get native info' operation */ +typedef struct H5VL_native_object_get_native_info_t { + unsigned fields; /* Fields to retrieve */ + H5O_native_info_t *ninfo; /* Native info (OUT) */ +} H5VL_native_object_get_native_info_t; + +/* Parameters for native connector's object 'optional' operations */ +typedef union H5VL_native_object_optional_args_t { + /* H5VL_NATIVE_OBJECT_GET_COMMENT */ + H5VL_native_object_get_comment_t get_comment; + + /* H5VL_NATIVE_OBJECT_SET_COMMENT */ + struct { + const char *comment; /* Comment string to set for the object (IN) */ + } set_comment; + + /* H5VL_NATIVE_OBJECT_DISABLE_MDC_FLUSHES */ + /* No args */ + + /* H5VL_NATIVE_OBJECT_ENABLE_MDC_FLUSHES */ + /* No args */ + + /* H5VL_NATIVE_OBJECT_ARE_MDC_FLUSHES_DISABLED */ + struct { + hbool_t *flag; /* Flag whether metadata cache flushes are disabled for this object (OUT) */ + } are_mdc_flushes_disabled; + + /* H5VL_NATIVE_OBJECT_GET_NATIVE_INFO */ + H5VL_native_object_get_native_info_t get_native_info; +} H5VL_native_object_optional_args_t; /*******************/ /* Public Typedefs */ diff --git a/libs/windows/include/H5VLpassthru.h b/libs/windows/include/H5VLpassthru.h index 79caca7..ec396cc 100644 --- a/libs/windows/include/H5VLpassthru.h +++ b/libs/windows/include/H5VLpassthru.h @@ -25,7 +25,7 @@ /* Characteristics of the pass-through VOL connector */ #define H5VL_PASSTHRU_NAME "pass_through" -#define H5VL_PASSTHRU_VALUE 505 /* VOL connector ID */ +#define H5VL_PASSTHRU_VALUE 1 /* VOL connector ID */ #define H5VL_PASSTHRU_VERSION 0 /* Pass-through VOL connector info */ diff --git a/libs/windows/include/H5VLpublic.h b/libs/windows/include/H5VLpublic.h index aec4851..30a2b5d 100644 --- a/libs/windows/include/H5VLpublic.h +++ b/libs/windows/include/H5VLpublic.h @@ -17,9 +17,8 @@ #ifndef H5VLpublic_H #define H5VLpublic_H -/* Public headers needed by this file */ -#include "H5public.h" /* Generic Functions */ -#include "H5Ipublic.h" /* IDs */ +#include "H5public.h" /* Generic Functions */ +#include "H5Ipublic.h" /* Identifiers */ /*****************/ /* Public Macros */ @@ -27,14 +26,14 @@ /** * \ingroup H5VLDEF - * \brief Version # of VOL class struct & callbacks + * \brief Version number of VOL class struct & callbacks * * \details Each VOL connector must set the 'version' field in the H5VL_class_t * struct to the version of the H5VL_class_t struct that the connector * implements. The HDF5 library will reject connectors with * incompatible structs. */ -#define H5VL_VERSION 0 +#define H5VL_VERSION 3 /* VOL connector identifier values * These are H5VL_class_value_t values, NOT hid_t values! @@ -60,6 +59,73 @@ */ #define H5_VOL_MAX 65535 +/* + * Capability flags for VOL connectors + */ +#define H5VL_CAP_FLAG_NONE 0x0000000000000000 /**< No special connector capabilities */ +#define H5VL_CAP_FLAG_THREADSAFE 0x0000000000000001 /**< Connector is threadsafe */ +#define H5VL_CAP_FLAG_ASYNC 0x0000000000000002 /**< Connector performs operations asynchronously*/ +#define H5VL_CAP_FLAG_NATIVE_FILES 0x0000000000000004 /**< Connector produces native file format */ +#define H5VL_CAP_FLAG_ATTR_BASIC 0x0000000000000008 /**< H5A create/delete/exists/open/close/read/write */ +#define H5VL_CAP_FLAG_ATTR_MORE 0x0000000000000010 /**< All other H5A API calls */ +#define H5VL_CAP_FLAG_DATASET_BASIC 0x0000000000000020 /**< H5D create/open/close/read/write */ +#define H5VL_CAP_FLAG_DATASET_MORE 0x0000000000000040 /**< All other H5D API calls */ +#define H5VL_CAP_FLAG_FILE_BASIC 0x0000000000000080 /**< H5F create/open/close/read/write */ +#define H5VL_CAP_FLAG_FILE_MORE 0x0000000000000100 /**< All other H5F API calls */ +#define H5VL_CAP_FLAG_GROUP_BASIC 0x0000000000000200 /**< H5G create/open/close */ +#define H5VL_CAP_FLAG_GROUP_MORE 0x0000000000000400 /**< All other H5G API calls*/ +#define H5VL_CAP_FLAG_LINK_BASIC 0x0000000000000800 /**< H5L exists/delete */ +#define H5VL_CAP_FLAG_LINK_MORE 0x0000000000001000 /**< All other H5L API calls */ +#define H5VL_CAP_FLAG_MAP_BASIC \ + 0x0000000000002000 /**< H5M create/open/close/get*type/get_count/put/get/exists/delete */ +#define H5VL_CAP_FLAG_MAP_MORE 0x0000000000004000 /**< All other H5M API calls */ +#define H5VL_CAP_FLAG_OBJECT_BASIC 0x0000000000008000 /**< H5O open/close/exists */ +#define H5VL_CAP_FLAG_OBJECT_MORE 0x0000000000010000 /**< All other H5O API calls */ +#define H5VL_CAP_FLAG_REF_BASIC 0x0000000000020000 /**< H5Rdestroy */ +#define H5VL_CAP_FLAG_REF_MORE 0x0000000000040000 /**< All other H5R API calls */ +#define H5VL_CAP_FLAG_OBJ_REF 0x0000000000080000 /**< Connector supports object references */ +#define H5VL_CAP_FLAG_REG_REF 0x0000000000100000 /**< Connector supports regional references */ +#define H5VL_CAP_FLAG_ATTR_REF 0x0000000000200000 /**< Connector supports attribute references */ +#define H5VL_CAP_FLAG_STORED_DATATYPES 0x0000000000400000 /**< Connector supports stored datatypes */ +#define H5VL_CAP_FLAG_CREATION_ORDER 0x0000000000800000 /**< Connector tracks creation order */ +#define H5VL_CAP_FLAG_ITERATE 0x0000000001000000 /**< Connector supports iteration functions */ +#define H5VL_CAP_FLAG_STORAGE_SIZE 0x0000000002000000 /**< Connector can return a meaningful storage size */ +#define H5VL_CAP_FLAG_BY_IDX 0x0000000004000000 /**< "by index" API calls are supported */ +#define H5VL_CAP_FLAG_GET_PLIST \ + 0x0000000008000000 /**< Connector can return the property lists used to create an object */ +#define H5VL_CAP_FLAG_FLUSH_REFRESH 0x0000000010000000 /**< flush/refresh calls are supported */ +#define H5VL_CAP_FLAG_EXTERNAL_LINKS 0x0000000020000000 /**< External links are supported */ +#define H5VL_CAP_FLAG_HARD_LINKS 0x0000000040000000 /**< Hard links are supported */ +#define H5VL_CAP_FLAG_SOFT_LINKS 0x0000000080000000 /**< Soft links are supported */ +#define H5VL_CAP_FLAG_UD_LINKS 0x0000000100000000 /**< User-defined links are supported */ +#define H5VL_CAP_FLAG_TRACK_TIMES 0x0000000200000000 /**< Connector tracks creation, etc. times */ +#define H5VL_CAP_FLAG_MOUNT 0x0000000400000000 /**< H5Fmount/unmount supported */ +#define H5VL_CAP_FLAG_FILTERS 0x0000000800000000 /**< Connector implements a filter pipeline */ +#define H5VL_CAP_FLAG_FILL_VALUES 0x0000001000000000 /**< Connector allows fill values to be set */ + +/** + * \ingroup H5VLDEF + * + * Flags to return from H5VLquery_optional API and 'opt_query' callbacks + * + * \details Operations which access multiple objects' data or metadata in a + * container should be registered as file-level optional operations. + * (e.g. "H5Dwrite_multi" takes a list of datasets to write data to, so + * a VOL connector that implemented it should register it as an optional + * file operation, and pass-through VOL connectors that are stacked above + * the connector that registered it should assume that dataset elements + * for _any_ dataset in the file could be written to) + */ +#define H5VL_OPT_QUERY_SUPPORTED 0x0001 /**< VOL connector supports this operation */ +#define H5VL_OPT_QUERY_READ_DATA 0x0002 /**< Operation reads data for object */ +#define H5VL_OPT_QUERY_WRITE_DATA 0x0004 /**< Operation writes data for object */ +#define H5VL_OPT_QUERY_QUERY_METADATA 0x0008 /**< Operation reads metadata for object */ +#define H5VL_OPT_QUERY_MODIFY_METADATA 0x0010 /**< Operation modifies metadata for object */ +#define H5VL_OPT_QUERY_COLLECTIVE \ + 0x0020 /**< Operation is collective (operations without this flag are assumed to be independent) */ +#define H5VL_OPT_QUERY_NO_ASYNC 0x0040 /**< Operation may NOT be executed asynchronously */ +#define H5VL_OPT_QUERY_MULTI_OBJ 0x0080 /**< Operation involves multiple objects */ + /*******************/ /* Public Typedefs */ /*******************/ @@ -97,6 +163,9 @@ typedef enum H5VL_subclass_t { H5VL_SUBCLS_REQUEST, /**< 'Request' subclass */ H5VL_SUBCLS_BLOB, /**< 'Blob' subclass */ H5VL_SUBCLS_TOKEN /**< 'Token' subclass */ + /* NOTE: if more operations are added, the + * H5VL_opt_vals_g[] array size should be updated. + */ } H5VL_subclass_t; /********************/ @@ -328,20 +397,27 @@ H5_DLL herr_t H5VLunregister_connector(hid_t connector_id); * \obj_id * \param[in] subcls VOL subclass * \param[in] opt_type Option type - * \param[out] supported Flag + * \param[out] flags Operation flags * \return \herr_t * - * \since 1.12.0 + * \since 1.12.1 */ -H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, hbool_t *supported); +H5_DLL herr_t H5VLquery_optional(hid_t obj_id, H5VL_subclass_t subcls, int opt_type, uint64_t *flags); +/** + * \ingroup H5VL + * \brief Determines whether an object ID represents a native + * VOL connector object. + * + * \obj_id + * \param[out] is_native Boolean determining whether object is a native VOL connector object + * \return \herr_t + * + * \since 1.12.2 + */ +H5_DLL herr_t H5VLobject_is_native(hid_t obj_id, hbool_t *is_native); #ifdef __cplusplus } #endif -/* Semi-public headers mainly for VOL connector authors */ -#include "H5VLconnector.h" /* VOL connector author routines */ -#include "H5VLconnector_passthru.h" /* Pass-through VOL connector author routines */ -#include "H5VLnative.h" /* Native VOL connector macros, for VOL connector authors */ - #endif /* H5VLpublic_H */ diff --git a/libs/windows/include/H5VarLenType.h b/libs/windows/include/H5VarLenType.h index f767e0e..318681a 100644 --- a/libs/windows/include/H5VarLenType.h +++ b/libs/windows/include/H5VarLenType.h @@ -1,7 +1,6 @@ // C++ informative line for the emacs editor: -*- C++ -*- /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -33,11 +32,11 @@ class H5_DLLCPP VarLenType : public DataType { // Returns an VarLenType object via DataType* by decoding the // binary object description of this type. - virtual DataType *decode() const; + virtual DataType *decode() const override; ///\brief Returns this class name. virtual H5std_string - fromClass() const + fromClass() const override { return ("VarLenType"); } @@ -53,7 +52,7 @@ class H5_DLLCPP VarLenType : public DataType { VarLenType(const H5Location &loc, const H5std_string &name); // Noop destructor - virtual ~VarLenType(); + virtual ~VarLenType() override; // Default constructor VarLenType(); diff --git a/libs/windows/include/H5Zdevelop.h b/libs/windows/include/H5Zdevelop.h new file mode 100644 index 0000000..736c283 --- /dev/null +++ b/libs/windows/include/H5Zdevelop.h @@ -0,0 +1,439 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * This file contains public declarations for the H5Z (data filter) developer + * support routines. + */ + +#ifndef H5Zdevelop_H +#define H5Zdevelop_H + +/* Include package's public header */ +#include "H5Zpublic.h" + +/*****************/ +/* Public Macros */ +/*****************/ + +/** + * Current version of the H5Z_class_t struct + */ +#define H5Z_CLASS_T_VERS (1) + +/*******************/ +/* Public Typedefs */ +/*******************/ + +/** + * Structure for filter callback property + */ +typedef struct H5Z_cb_t { + H5Z_filter_func_t func; + void *op_data; +} H5Z_cb_t; + +/** + * \brief This callback determines if a filter can be applied to the dataset + * with the characteristics provided + * + * \dcpl_id + * \type_id + * \space_id + * + * \return \htri_t + * + * \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. + */ +//! +typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); +//! + +/** + * \brief The filter operation callback function, defining a filter's operation + * on data + * + * \dcpl_id + * \type_id + * \space_id + * + * \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. + */ +//! +typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); +//! + +/** + * \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 + * operate, and pointers to a buffer and its allocated size. + * + * The filter should store the result in the supplied buffer if + * possible, otherwise it can allocate a new buffer, freeing the + * original. The allocated size of the new buffer should be returned + * through the \p buf_size pointer and the new buffer through the \p + * buf pointer. + * + * The return value from the filter is the number of bytes in the + * output buffer. If an error occurs then the function should return + * zero and leave all pointer arguments unchanged. + */ +//! +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); +//! + +/** + * The filter table maps filter identification numbers to structs that + * contain a pointers to the filter function and timing statistics. + */ +//! +typedef struct H5Z_class2_t { + int version; /**< Version number of the H5Z_class_t struct */ + H5Z_filter_t id; /**< Filter ID number */ + unsigned encoder_present; /**< Does this filter have an encoder? */ + unsigned decoder_present; /**< Does this filter have a decoder? */ + const char *name; /**< Comment for debugging */ + H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */ + 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; +//! + +/********************/ +/* Public Variables */ +/********************/ + +/*********************/ +/* Public Prototypes */ +/*********************/ + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * \ingroup H5Z + * + * \brief Registers a new filter with the HDF5 library + * + * \param[in] cls A pointer to a buffer for the struct containing the + * filter-definition + * + * \return \herr_t + * + * \details H5Zregister() registers a new filter with the HDF5 library. + * + * \details Making a new filter available to an application is a two-step + * process. The first step is to write the three filter callback + * functions described below: \c can_apply, \c set_local, and \c + * filter. This call to H5Zregister(), registering the filter with the + * library, is the second step. The can_apply and set_local fields can + * be set to NULL if they are not required for the filter being + * registered. + * + * H5Zregister() accepts a single parameter, a pointer to a buffer for + * the \p cls data structure. That data structure must conform to one + * of the following definitions: + * \snippet this H5Z_class1_t_snip + * or + * \snippet this H5Z_class2_t_snip + * + * \c version is a library-defined value reporting the version number + * of the #H5Z_class_t struct. This currently must be set to + * #H5Z_CLASS_T_VERS. + * + * \c id is the identifier for the new filter. This is a user-defined + * value between #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX. These + * values are defined in the HDF5 source file H5Zpublic.h, but the + * symbols #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX should always be + * used instead of the literal values. + * + * \c encoder_present is a library-defined value indicating whether + * the filter's encoding capability is available to the application. + * + * \c decoder_present is a library-defined value indicating whether + * the filter's encoding capability is available to the application. + * + * \c name is a descriptive comment used for debugging, may contain a + * descriptive name for the filter, and may be the null pointer. + * + * \c can_apply, described in detail below, is a user-defined callback + * function that determines whether the combination of the dataset + * creation property list values, the datatype, and the dataspace + * represent a valid combination to apply this filter to. + * + * \c set_local, described in detail below, is a user-defined callback + * function that sets any parameters that are specific to this + * dataset, based on the combination of the dataset creation property + * list values, the datatype, and the dataspace. + * + * \c filter, described in detail below, is a user-defined callback + * function which performs the action of the filter. + * + * The statistics associated with a filter are not reset by this + * function; they accumulate over the life of the library. + * + * #H5Z_class_t is a macro that maps to either H5Z_class1_t or + * H5Z_class2_t, depending on the needs of the application. To affect + * only this macro, H5Z_class_t_vers may be defined as either 1 or 2. + * Otherwise, it will behave in the same manner as other API + * compatibility macros. See API Compatibility Macros in HDF5 for more + * information. H5Z_class1_t matches the #H5Z_class_t structure that is + * used in the 1.6.x versions of the HDF5 library. + * + * H5Zregister() will automatically detect which structure type has + * been passed in, regardless of the mapping of the #H5Z_class_t macro. + * However, the application must make sure that the fields are filled + * in according to the correct structure definition if the macro is + * used to declare the structure. + * + * \Bold{The callback functions:}\n Before H5Zregister() can link a + * filter into an application, three callback functions must be + * defined as described in the HDF5 library header file H5Zpublic.h. + * + * When a filter is applied to the fractal heap for a group (e.g., + * when compressing group metadata) and if they can apply and set local + * callback functions that have been defined for that filter, HDF5 passes + * the value -1 for all parameters for those callback functions. This + * is done to ensure that the filter will not be applied to groups if + * it relies on these parameters, as they are not applicable to group + * fractal heaps; to operate on group fractal heaps, a filter must be + * capable of operating on an opaque block of binary data. + * + * The \Emph{can-apply} callback function must return a positive value + * for a valid combination, zero for an invalid combination, and a + * negative value for an error. + * \snippet this H5Z_can_apply_func_t_snip + * + * Before a dataset is created, the \Emph{can apply} callbacks for any + * filters used in the dataset creation property list are called with + * the dataset's dataset creation property list, \c dcpl_id, the + * dataset's datatype, \p type_id, and a dataspace describing a chunk, + * \p space_id, (for chunked dataset storage). + * + * This callback must determine whether the combination of the dataset + * creation property list settings, the datatype, and the dataspace + * represent a valid combination to which to apply this filter. For + * example, an invalid combination may involve the filter not + * operating correctly on certain datatypes, on certain datatype + * sizes, or on certain sizes of the chunk dataspace. If this filter + * is enabled through H5Pset_filter() as optional and the can apply + * function returns 0, the library will skip the filter in the filter + * pipeline. + * + * This callback can be the NULL pointer, in which case the library + * will assume that the filter can be applied to a dataset with any + * combination of dataset creation property list values, datatypes, + * and dataspaces. + * + * The \Emph{set local} callback function is defined as follows: + * \snippet this H5Z_set_local_func_t_snip + * + * After the can apply callbacks are checked for a new dataset, the + * \Emph{set local} callback functions for any filters used in the + * dataset creation property list are called. These callbacks receive + * \c dcpl_id, the dataset's private copy of the dataset creation + * property list passed into H5Dcreate() (i.e. not the actual + * property list passed into H5Dcreate()); \c type_id, the datatype + * identifier passed into H5Dcreate(), which is not copied and should + * not be modified; and \c space_id, a dataspace describing the chunk + * (for chunked dataset storage), which should also not be modified. + * + * The set local callback must set any filter 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, datatype sizes, numbers of dimensions, or dataspace + * sizes. + * + * The \Emph{set local} callback may be the NULL pointer, in which + * case, the library will assume that there are no dataset-specific + * settings for this filter. + * + * The \Emph{set local} callback function must return a non-negative + * value on success and a negative value for an error. + * + * The \Emph{filter operation} callback function, defining the + * filter's operation on the data, is defined as follows: + * \snippet this H5Z_func_t_snip + * + * The parameters \c flags, \c cd_nelmts, and \c cd_values are the + * same as for the function H5Pset_filter(). The one exception is that + * an additional flag, #H5Z_FLAG_REVERSE, is set when the filter is + * called as part of the input pipeline. + * + * The parameter \c buf points to the input buffer which has a size of + * \c buf_size bytes, \c nbytes of which are valid data. + * + * The filter should perform the transformation in place if possible. + * If the transformation cannot be done in place, then the filter + * should allocate a new buffer and assign it to \c buf, assigning + * the allocated size of that buffer to \c buf_size. The old + * buffer should be freed by the filter. + * + * Some care must be taken with the functions that allocate and free + * memory. Standard C library functions like malloc(3) and free(3) + * will work in many cases, but if there is a mismatch between the + * memory allocators used in the library and any filter that + * reallocates a buffer, there could be problems. This is most often + * the case with Windows and/or when debugging memory allocators are being + * used. In both cases, the "state" of the memory allocator lies in + * different libraries and will get corrupted if you allocate in one + * library and free in another. Windows adds the C standard library + * via dlls that can vary with Visual Studio version and debug vs. + * release builds. Static links to the MSVC CRT can also introduce + * a new memory allocator state. + * + * The library does provide H5allocate_memory() and H5free_memory() + * functions that will use the library's allocation and free functions, + * however using these functions will require linking your filter to + * a particular version of the library, which may be inconvenient. + * + * If successful, the \Emph{filter operation} callback function + * returns the number of valid bytes of data contained in \c buf. In + * the case of failure, the return value is 0 (zero) and all pointer + * arguments are left unchanged. + * + * \version 1.8.6 Return type for the \Emph{can apply} callback function, + * \ref H5Z_can_apply_func_t, changed to \ref htri_t. + * \version 1.8.5 Semantics of the \Emph{can apply} and \Emph{set local} + * callback functions changed to accommodate the use of filters + * with group fractal heaps. + * \version 1.8.3 #H5Z_class_t renamed to H5Z_class2_t, H5Z_class1_t structure + * introduced for backwards compatibility with release 1.6.x, + * and #H5Z_class_t macro introduced in this release. Function + * modified to accept either structure type. + * \version 1.8.0 The fields \c version, \c encoder_present, and + * \c decoder_present were added to the #H5Z_class_t \c struct + * in this release. + * \version 1.6.0 This function was substantially revised in Release 1.6.0 with + * a new #H5Z_class_t struct and new set local and can apply + * callback functions. + * + */ +H5_DLL herr_t H5Zregister(const void *cls); +/** + * \ingroup H5Z + * + * \brief Unregisters a filter. + * + * \param[in] id Identifier of the filter to be unregistered. + * \return \herr_t + * + * \details H5Zunregister() unregisters the filter specified in \p id. + * + * \details This function first iterates through all opened datasets and + * groups. If an open object that uses this filter is found, the + * function will fail with a message indicating that an object using + * the filter is still open. All open files are then flushed to make + * sure that all cached data that may use this filter are written out. + * + * If the application is a parallel program, all processes that + * participate in collective data writing should call this function to + * ensure that all data is flushed. + * + * After a call to H5Zunregister(), the filter specified in filter + * will no longer be available to the application. + * + * \version 1.8.12 Function modified to check for open objects using the + * filter. + * \since 1.6.0 + */ +H5_DLL herr_t H5Zunregister(H5Z_filter_t id); + +#ifdef __cplusplus +} +#endif + +/* Symbols defined for compatibility with previous versions of the HDF5 API. + * + * Use of these symbols is deprecated. + */ +#ifndef H5_NO_DEPRECATED_SYMBOLS + +/** + * The filter table maps filter identification numbers to structs that + * contain a pointers to the filter function and timing statistics. + */ +//! +typedef struct H5Z_class1_t { + H5Z_filter_t id; /**< Filter ID number */ + const char *name; /**< Comment for debugging */ + H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */ + 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; +//! + +#endif /* H5_NO_DEPRECATED_SYMBOLS */ + +#endif /* H5Zdevelop_H */ diff --git a/libs/windows/include/H5Zpublic.h b/libs/windows/include/H5Zpublic.h index 90277cf..d906e3c 100644 --- a/libs/windows/include/H5Zpublic.h +++ b/libs/windows/include/H5Zpublic.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -11,15 +10,10 @@ * help@hdfgroup.org. * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* Programmer: Robb Matzke - * Thursday, April 16, 1998 - */ - #ifndef H5Zpublic_H #define H5Zpublic_H -/* Public headers needed by this file */ -#include "H5public.h" +#include "H5public.h" /* Generic Functions */ /** * \brief Filter identifiers @@ -206,11 +200,6 @@ typedef enum H5Z_SO_scale_type_t { H5Z_SO_INT = 2 } H5Z_SO_scale_type_t; -/** - * Current version of the H5Z_class_t struct - */ -#define H5Z_CLASS_T_VERS (1) - /** * \ingroup FLETCHER32 * Values to decide if EDC is enabled for reading data @@ -243,353 +232,10 @@ typedef enum H5Z_cb_return_t { typedef H5Z_cb_return_t (*H5Z_filter_func_t)(H5Z_filter_t filter, void *buf, size_t buf_size, void *op_data); //! -/** - * Structure for filter callback property - */ -typedef struct H5Z_cb_t { - H5Z_filter_func_t func; - void * op_data; -} H5Z_cb_t; - #ifdef __cplusplus extern "C" { #endif -/** - * \brief This callback determines if a filter can be applied to the dataset - * with the characteristics provided - * - * \dcpl_id - * \type_id - * \space_id - * - * \return \htri_t - * - * \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. - */ -//! -typedef htri_t (*H5Z_can_apply_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); -//! -/** - * \brief The filter operation callback function, defining a filter's operation - * on data - * - * \dcpl_id - * \type_id - * \space_id - * - * \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. - */ -//! -typedef herr_t (*H5Z_set_local_func_t)(hid_t dcpl_id, hid_t type_id, hid_t space_id); -//! - -/** - * \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 - * operate, and pointers to a buffer and its allocated size. - * - * The filter should store the result in the supplied buffer if - * possible, otherwise it can allocate a new buffer, freeing the - * original. The allocated size of the new buffer should be returned - * through the \p buf_size pointer and the new buffer through the \p - * buf pointer. - * - * The return value from the filter is the number of bytes in the - * output buffer. If an error occurs then the function should return - * zero and leave all pointer arguments unchanged. - */ -//! -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); -//! -/** - * The filter table maps filter identification numbers to structs that - * contain a pointers to the filter function and timing statistics. - */ -//! -typedef struct H5Z_class2_t { - int version; /**< Version number of the H5Z_class_t struct */ - H5Z_filter_t id; /**< Filter ID number */ - unsigned encoder_present; /**< Does this filter have an encoder? */ - unsigned decoder_present; /**< Does this filter have a decoder? */ - const char * name; /**< Comment for debugging */ - H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */ - 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; -//! - -/** - * \ingroup H5Z - * - * \brief Registers a new filter with the HDF5 library - * - * \param[in] cls A pointer to a buffer for the struct containing the - * filter-definition - * - * \return \herr_t - * - * \details H5Zregister() registers a new filter with the HDF5 library. - * - * \details Making a new filter available to an application is a two-step - * process. The first step is to write the three filter callback - * functions described below: \c can_apply, \c set_local, and \c - * filter. This call to H5Zregister(), registering the filter with the - * library, is the second step. The can_apply and set_local fields can - * be set to NULL if they are not required for the filter being - * registered. - * - * H5Zregister() accepts a single parameter, a pointer to a buffer for - * the \p cls data structure. That data structure must conform to one - * of the following definitions: - * \snippet this H5Z_class1_t_snip - * or - * \snippet this H5Z_class2_t_snip - * - * \c version is a library-defined value reporting the version number - * of the #H5Z_class_t struct. This currently must be set to - * #H5Z_CLASS_T_VERS. - * - * \c id is the identifier for the new filter. This is a user-defined - * value between #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX. These - * values are defined in the HDF5 source file H5Zpublic.h, but the - * symbols #H5Z_FILTER_RESERVED and #H5Z_FILTER_MAX should always be - * used instead of the literal values. - * - * \c encoder_present is a library-defined value indicating whether - * the filter’s encoding capability is available to the application. - * - * \c decoder_present is a library-defined value indicating whether - * the filter’s encoding capability is available to the application. - * - * \c name is a descriptive comment used for debugging, may contain a - * descriptive name for the filter, and may be the null pointer. - * - * \c can_apply, described in detail below, is a user-defined callback - * function which determines whether the combination of the dataset - * creation property list values, the datatype, and the dataspace - * represent a valid combination to apply this filter to. - * - * \c set_local, described in detail below, is a user-defined callback - * function which sets any parameters that are specific to this - * dataset, based on the combination of the dataset creation property - * list values, the datatype, and the dataspace. - * - * \c filter, described in detail below, is a user-defined callback - * function which performs the action of the filter. - * - * The statistics associated with a filter are not reset by this - * function; they accumulate over the life of the library. - * - * #H5Z_class_t is a macro which maps to either H5Z_class1_t or - * H5Z_class2_t, depending on the needs of the application. To affect - * only this macro, H5Z_class_t_vers may be defined to either 1 or 2. - * Otherwise, it will behave in the same manner as other API - * compatibility macros. See API Compatibility Macros in HDF5 for more - * information. H5Z_class1_t matches the #H5Z_class_t structure that is - * used in the 1.6.x versions of the HDF5 library. - * - * H5Zregister() will automatically detect which structure type has - * been passed in, regardless of the mapping of the #H5Z_class_t macro. - * However, the application must make sure that the fields are filled - * in according to the correct structure definition if the macro is - * used to declare the structure. - * - * \Bold{The callback functions:}\n Before H5Zregister() can link a - * filter into an application, three callback functions must be - * defined as described in the HDF5 library header file H5Zpublic.h. - * - * When a filter is applied to the fractal heap for a group (e.g., - * when compressing group metadata) and if the can apply and set local - * callback functions have been defined for that filter, HDF5 passes - * the value -1 for all parameters for those callback functions. This - * is done to ensure that the filter will not be applied to groups if - * it relies on these parameters, as they are not applicable to group - * fractal heaps; to operate on group fractal heaps, a filter must be - * capable of operating on an opaque block of binary data. - * - * The \Emph{can apply} callback function must return a positive value - * for a valid combination, zero for an invalid combination, and a - * negative value for an error. - * \snippet this H5Z_can_apply_func_t_snip - * - * Before a dataset is created, the \Emph{can apply} callbacks for any - * filters used in the dataset creation property list are called with - * the dataset's dataset creation property list, \c dcpl_id, the - * dataset's datatype, \p type_id, and a dataspace describing a chunk, - * \p space_id, (for chunked dataset storage). - * - * This callback must determine whether the combination of the dataset - * creation property list settings, the datatype, and the dataspace - * represent a valid combination to which to apply this filter. For - * example, an invalid combination may involve the filter not - * operating correctly on certain datatypes, on certain datatype - * sizes, or on certain sizes of the chunk dataspace. If this filter - * is enabled through H5Pset_filter() as optional and the can apply - * function returns 0, the library will skip the filter in the filter - * pipeline. - * - * This callback can be the NULL pointer, in which case the library - * will assume that the filter can be applied to a dataset with any - * combination of dataset creation property list values, datatypes, - * and dataspaces. - * - * The \Emph{set local} callback function is defined as follows: - * \snippet this H5Z_set_local_func_t_snip - * - * After the can apply callbacks are checked for a new dataset, the - * \Emph{set local} callback functions for any filters used in the - * dataset creation property list are called. These callbacks receive - * \c dcpl_id, 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()); \c type_id, the datatype - * identifier passed in to H5Dcreate(), which is not copied and should - * not be modified; and \c space_id, a dataspace describing the chunk - * (for chunked dataset storage), which should also not be modified. - * - * The set local callback must set any filter 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, datatype sizes, numbers of dimensions, or dataspace - * sizes. - * - * The \Emph{set local} callback may be the NULL pointer, in which - * case, the library will assume that there are no dataset-specific - * settings for this filter. - * - * The \Emph{set local} callback function must return a non-negative - * value on success and a negative value for an error. - * - * The \Emph{filter operation} callback function, defining the - * filter's operation on the data, is defined as follows: - * \snippet this H5Z_func_t_snip - * - * The parameters \c flags, \c cd_nelmts, and \c cd_values are the - * same as for the function H5Pset_filter(). The one exception is that - * an additional flag, #H5Z_FLAG_REVERSE, is set when the filter is - * called as part of the input pipeline. - * - * The parameter \c buf points to the input buffer which has a size of - * \c buf_size bytes, \c nbytes of which are valid data. - * - * The filter should perform the transformation in place if possible. - * If the transformation cannot be done in place, then the filter - * should allocate a new buffer with malloc() and assign it to \c buf, - * assigning the allocated size of that buffer to \c buf_size. The old - * buffer should be freed by calling free(). - * - * If successful, the \Emph{filter operation} callback function - * returns the number of valid bytes of data contained in \c buf. In - * the case of failure, the return value is 0 (zero) and all pointer - * arguments are left unchanged. - * - * \version 1.8.6 Return type for the \Emph{can apply} callback function, - * \ref H5Z_can_apply_func_t, changed to \ref htri_t. - * \version 1.8.5 Semantics of the \Emph{can apply} and \Emph{set local} - * callback functions changed to accommodate the use of filters - * with group fractal heaps. - * \version 1.8.3 #H5Z_class_t renamed to H5Z_class2_t, H5Z_class1_t structure - * introduced for backwards compatibility with release 1.6.x, - * and #H5Z_class_t macro introduced in this release. Function - * modified to accept either structure type. - * \version 1.8.0 The fields \c version, \c encoder_present, and - * \c decoder_present were added to the #H5Z_class_t \c struct - * in this release. - * \version 1.6.0 This function was substantially revised in Release 1.6.0 with - * a new #H5Z_class_t struct and new set local and can apply - * callback functions. - * - */ -H5_DLL herr_t H5Zregister(const void *cls); -/** - * \ingroup H5Z - * - * \brief Unregisters a filter. - * - * \param[in] id Identifier of the filter to be unregistered. - * \return \herr_t - * - * \details H5Zunregister() unregisters the filter specified in \p id. - * - * \details This function first iterates through all opened datasets and - * groups. If an open object that uses this filter is found, the - * function will fail with a message indicating that an object using - * the filter is still open. All open files are then flushed to make - * sure that all cached data that may use this filter are written out. - * - * If the application is a parallel program, all processes that - * participate in collective data write should call this function to - * ensure that all data is flushed. - * - * After a call to H5Zunregister(), the filter specified in filter - * will no longer be available to the application. - * - * \version 1.8.12 Function modified to check for open objects using the - * filter. - * \since 1.6.0 - */ -H5_DLL herr_t H5Zunregister(H5Z_filter_t id); /** * \ingroup H5Z * @@ -617,7 +263,7 @@ H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id); * \details H5Zget_filter_info() retrieves information about a filter. At * present, this means that the function retrieves a filter's * configuration flags, indicating whether the filter is configured to - * decode data, to encode data, neither, or both. + * decode data, encode data, neither, or both. * * If \p filter_config_flags is not set to NULL prior to the function * call, the returned parameter contains a bit field specifying the @@ -640,7 +286,7 @@ H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id); * H5Z_FILTER_CONFIG_ENCODE_ENABLED & filter_config_flags * \endcode * is true, i.e., greater than 0 (zero), the queried filter - * is configured to encode data; if the value is \c FALSE, i.e., equal to + * is configured to encode data; if the value is \c false, i.e., equal to * 0 (zero), the filter is not so configured. * * If a filter is not encode-enabled, the corresponding \c H5Pset_* @@ -654,37 +300,16 @@ H5_DLL htri_t H5Zfilter_avail(H5Z_filter_t id); * to read an existing file encoded with that filter. * * This function should be called, and the returned \p - * filter_config_flags analyzed, before calling any other function, - * such as H5Pset_szip() , that might require a particular filter + * filter_config_flags should be analyzed, before calling any other function, + * such as H5Pset_szip(), that might require a particular filter * configuration. * * \since 1.6.3 */ H5_DLL herr_t H5Zget_filter_info(H5Z_filter_t filter, unsigned int *filter_config_flags); -/* Symbols defined for compatibility with previous versions of the HDF5 API. - * - * Use of these symbols is deprecated. - */ -#ifndef H5_NO_DEPRECATED_SYMBOLS - -/** - * The filter table maps filter identification numbers to structs that - * contain a pointers to the filter function and timing statistics. - */ -//! -typedef struct H5Z_class1_t { - H5Z_filter_t id; /**< Filter ID number */ - const char * name; /**< Comment for debugging */ - H5Z_can_apply_func_t can_apply; /**< The "can apply" callback for a filter */ - 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; -//! - -#endif /* H5_NO_DEPRECATED_SYMBOLS */ - #ifdef __cplusplus } #endif -#endif + +#endif /* _H5Zpublic_H */ diff --git a/libs/windows/include/H5api_adpt.h b/libs/windows/include/H5api_adpt.h index 53080b7..a9c34ae 100644 --- a/libs/windows/include/H5api_adpt.h +++ b/libs/windows/include/H5api_adpt.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -14,7 +13,6 @@ /* * H5api_adpt.h * Used for the HDF5 dll project - * Created by Patrick Lu on 1/12/99 */ #ifndef H5API_ADPT_H #define H5API_ADPT_H diff --git a/libs/windows/include/H5encode.h b/libs/windows/include/H5encode.h new file mode 100644 index 0000000..5be75d5 --- /dev/null +++ b/libs/windows/include/H5encode.h @@ -0,0 +1,292 @@ +/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + * Copyright by The HDF Group. * + * All rights reserved. * + * * + * This file is part of HDF5. The full HDF5 copyright notice, including * + * terms governing use, modification, and redistribution, is contained in * + * the COPYING file, which can be found at the root of the source code * + * distribution tree, or in https://www.hdfgroup.org/licenses. * + * If you do not have access to either file, you may request a copy from * + * help@hdfgroup.org. * + * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ + +/* + * File-independent encode/decode routines + */ + +#ifndef H5encode_H +#define H5encode_H + +/***********/ +/* Headers */ +/***********/ +#include "H5MMprivate.h" /* Memory management */ + +/**************************/ +/* Library Private Macros */ +/**************************/ + +/* + * Encode and decode macros for file meta-data. + * Currently, all file meta-data is little-endian. + */ + +#define INT16ENCODE(p, i) \ + do { \ + *(p) = (uint8_t)((unsigned)(i)&0xff); \ + (p)++; \ + *(p) = (uint8_t)(((unsigned)(i) >> 8) & 0xff); \ + (p)++; \ + } while (0) + +#define UINT16ENCODE(p, i) \ + do { \ + *(p) = (uint8_t)((unsigned)(i)&0xff); \ + (p)++; \ + *(p) = (uint8_t)(((unsigned)(i) >> 8) & 0xff); \ + (p)++; \ + } while (0) + +#define INT32ENCODE(p, i) \ + do { \ + *(p) = (uint8_t)((uint32_t)(i)&0xff); \ + (p)++; \ + *(p) = (uint8_t)(((uint32_t)(i) >> 8) & 0xff); \ + (p)++; \ + *(p) = (uint8_t)(((uint32_t)(i) >> 16) & 0xff); \ + (p)++; \ + *(p) = (uint8_t)(((uint32_t)(i) >> 24) & 0xff); \ + (p)++; \ + } while (0) + +#define UINT32ENCODE(p, i) \ + do { \ + *(p) = (uint8_t)((i)&0xff); \ + (p)++; \ + *(p) = (uint8_t)(((i) >> 8) & 0xff); \ + (p)++; \ + *(p) = (uint8_t)(((i) >> 16) & 0xff); \ + (p)++; \ + *(p) = (uint8_t)(((i) >> 24) & 0xff); \ + (p)++; \ + } while (0) + +/* Encode an unsigned integer into a variable-sized buffer */ +/* (Assumes that the high bits of the integer are zero) */ +#define ENCODE_VAR(p, typ, n, l) \ + do { \ + typ _n = (n); \ + size_t _i; \ + uint8_t *_p = (uint8_t *)(p); \ + \ + for (_i = 0; _i < l; _i++, _n >>= 8) \ + *_p++ = (uint8_t)(_n & 0xff); \ + (p) = (uint8_t *)(p) + l; \ + } while (0) + +/* Encode a 32-bit unsigned integer into a variable-sized buffer */ +/* (Assumes that the high bits of the integer are zero) */ +#define UINT32ENCODE_VAR(p, n, l) ENCODE_VAR(p, uint32_t, n, l) + +#define INT64ENCODE(p, n) \ + do { \ + int64_t _n = (n); \ + size_t _i; \ + uint8_t *_p = (uint8_t *)(p); \ + \ + for (_i = 0; _i < sizeof(int64_t); _i++, _n >>= 8) \ + *_p++ = (uint8_t)(_n & 0xff); \ + for (/*void*/; _i < 8; _i++) \ + *_p++ = (uint8_t)((n) < 0 ? 0xff : 0); \ + (p) = (uint8_t *)(p) + 8; \ + } while (0) + +#define UINT64ENCODE(p, n) \ + do { \ + uint64_t _n = (n); \ + size_t _i; \ + uint8_t *_p = (uint8_t *)(p); \ + \ + for (_i = 0; _i < sizeof(uint64_t); _i++, _n >>= 8) \ + *_p++ = (uint8_t)(_n & 0xff); \ + for (/*void*/; _i < 8; _i++) \ + *_p++ = 0; \ + (p) = (uint8_t *)(p) + 8; \ + } while (0) + +/* Encode a 64-bit unsigned integer into a variable-sized buffer */ +/* (Assumes that the high bits of the integer are zero) */ +#define UINT64ENCODE_VAR(p, n, l) ENCODE_VAR(p, uint64_t, n, l) + +#define H5_ENCODE_UNSIGNED(p, n) \ + do { \ + HDcompile_assert(sizeof(unsigned) == sizeof(uint32_t)); \ + UINT32ENCODE(p, n); \ + } while (0) + +/* Assumes the endianness of uint64_t is the same as double */ +#define H5_ENCODE_DOUBLE(p, n) \ + do { \ + uint64_t _n; \ + size_t _u; \ + uint8_t *_p = (uint8_t *)(p); \ + \ + HDcompile_assert(sizeof(double) == 8); \ + HDcompile_assert(sizeof(double) == sizeof(uint64_t)); \ + H5MM_memcpy(&_n, &n, sizeof(double)); \ + for (_u = 0; _u < sizeof(uint64_t); _u++, _n >>= 8) \ + *_p++ = (uint8_t)(_n & 0xff); \ + (p) = (uint8_t *)(p) + 8; \ + } while (0) + +/* DECODE converts little endian bytes pointed by p to integer values and store + * it in i. For signed values, need to do sign-extension when converting + * the last byte which carries the sign bit. + * The macros does not require i be of a certain byte sizes. It just requires + * i be big enough to hold the intended value range. E.g. INT16DECODE works + * correctly even if i is actually a 64bit int like in a Cray. + */ + +#define INT16DECODE(p, i) \ + do { \ + (i) = (int16_t)((*(p)&0xff)); \ + (p)++; \ + (i) |= (int16_t)(((*(p)&0xff) << 8) | ((*(p)&0x80) ? ~0xffff : 0x0)); \ + (p)++; \ + } while (0) + +#define UINT16DECODE(p, i) \ + do { \ + (i) = (uint16_t)(*(p)&0xff); \ + (p)++; \ + (i) |= (uint16_t)((*(p)&0xff) << 8); \ + (p)++; \ + } while (0) + +#define INT32DECODE(p, i) \ + do { \ + (i) = ((int32_t)(*(p)&0xff)); \ + (p)++; \ + (i) |= ((int32_t)(*(p)&0xff) << 8); \ + (p)++; \ + (i) |= ((int32_t)(*(p)&0xff) << 16); \ + (p)++; \ + (i) |= ((int32_t)(((*(p) & (unsigned)0xff) << 24) | ((*(p)&0x80) ? ~0xffffffffULL : 0x0ULL))); \ + (p)++; \ + } while (0) + +#define UINT32DECODE(p, i) \ + do { \ + (i) = (uint32_t)(*(p)&0xff); \ + (p)++; \ + (i) |= ((uint32_t)(*(p)&0xff) << 8); \ + (p)++; \ + (i) |= ((uint32_t)(*(p)&0xff) << 16); \ + (p)++; \ + (i) |= ((uint32_t)(*(p)&0xff) << 24); \ + (p)++; \ + } while (0) + +/* Decode a variable-sized buffer */ +/* (Assumes that the high bits of the integer will be zero) */ +#define DECODE_VAR(p, n, l) \ + do { \ + size_t _i; \ + \ + n = 0; \ + (p) += l; \ + for (_i = 0; _i < l; _i++) \ + n = (n << 8) | *(--p); \ + (p) += l; \ + } while (0) + +/* Decode a variable-sized buffer into a 32-bit unsigned integer */ +/* (Assumes that the high bits of the integer will be zero) */ +#define UINT32DECODE_VAR(p, n, l) DECODE_VAR(p, n, l) + +#define INT64DECODE(p, n) \ + do { \ + /* WE DON'T CHECK FOR OVERFLOW! */ \ + size_t _i; \ + \ + n = 0; \ + (p) += 8; \ + for (_i = 0; _i < sizeof(int64_t); _i++) \ + n = (n << 8) | *(--p); \ + (p) += 8; \ + } while (0) + +#define UINT64DECODE(p, n) \ + do { \ + /* WE DON'T CHECK FOR OVERFLOW! */ \ + size_t _i; \ + \ + n = 0; \ + (p) += 8; \ + for (_i = 0; _i < sizeof(uint64_t); _i++) \ + n = (n << 8) | *(--p); \ + (p) += 8; \ + } while (0) + +/* Decode a variable-sized buffer into a 64-bit unsigned integer */ +/* (Assumes that the high bits of the integer will be zero) */ +#define UINT64DECODE_VAR(p, n, l) DECODE_VAR(p, n, l) + +#define H5_DECODE_UNSIGNED(p, n) \ + do { \ + HDcompile_assert(sizeof(unsigned) == sizeof(uint32_t)); \ + UINT32DECODE(p, n); \ + } while (0) + +/* Assumes the endianness of uint64_t is the same as double */ +#define H5_DECODE_DOUBLE(p, n) \ + do { \ + uint64_t _n; \ + size_t _u; \ + \ + HDcompile_assert(sizeof(double) == 8); \ + HDcompile_assert(sizeof(double) == sizeof(uint64_t)); \ + _n = 0; \ + (p) += 8; \ + for (_u = 0; _u < sizeof(uint64_t); _u++) \ + _n = (_n << 8) | *(--p); \ + H5MM_memcpy(&(n), &_n, sizeof(double)); \ + (p) += 8; \ + } while (0) + +/* Macros to encode/decode offset/length's for storing in the file */ +#define H5_ENCODE_LENGTH_LEN(p, l, s) \ + do { \ + switch (s) { \ + case 4: \ + UINT32ENCODE(p, l); \ + break; \ + case 8: \ + UINT64ENCODE(p, l); \ + break; \ + case 2: \ + UINT16ENCODE(p, l); \ + break; \ + default: \ + assert("bad sizeof size" && 0); \ + } \ + } while (0) + +#define H5_DECODE_LENGTH_LEN(p, l, s) \ + do { \ + switch (s) { \ + case 4: \ + UINT32DECODE(p, l); \ + break; \ + case 8: \ + UINT64DECODE(p, l); \ + break; \ + case 2: \ + UINT16DECODE(p, l); \ + break; \ + default: \ + assert("bad sizeof size" && 0); \ + } \ + } while (0) + +#endif /* H5encode_H */ diff --git a/libs/windows/include/H5overflow.h b/libs/windows/include/H5overflow.h index 833f5ca..5003873 100644 --- a/libs/windows/include/H5overflow.h +++ b/libs/windows/include/H5overflow.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * diff --git a/libs/windows/include/H5pubconf.h b/libs/windows/include/H5pubconf.h index 7906449..84fbc79 100644 --- a/libs/windows/include/H5pubconf.h +++ b/libs/windows/include/H5pubconf.h @@ -14,27 +14,28 @@ #ifndef H5_CONFIG_H_ #define H5_CONFIG_H_ -/* Define if the Windows virtual file driver should be compiled */ +/* Define if this is a Windows machine */ #define H5_HAVE_WINDOWS 1 /* Define if using MinGW */ /* #undef H5_HAVE_MINGW */ -/* Define if on the Windows platform and default WIN32 API */ +/* Define if on the Windows platform and using the Win32 API */ #define H5_HAVE_WIN32_API 1 /* Define if using a Windows compiler (i.e. Visual Studio) */ #define H5_HAVE_VISUAL_STUDIO 1 -/* Define if C++ compiler recognizes offsetof */ -/* #undef H5_CXX_HAVE_OFFSETOF */ - /* Define the default plugins path to compile */ #define H5_DEFAULT_PLUGINDIR "%ALLUSERSPROFILE%\\hdf5\\lib\\plugin" /* Define if dev_t is a scalar */ /* #undef H5_DEV_T_IS_SCALAR */ +/* Define if your system is IBM ppc64le and cannot convert some long double + values correctly. */ +/* #undef H5_DISABLE_SOME_LDOUBLE_CONV */ + /* Define to dummy `main' function (if any) required to link to the Fortran libraries. */ /* #undef H5_FC_DUMMY_MAIN */ @@ -70,13 +71,13 @@ /* Define Fortran compiler ID */ #define H5_Fortran_COMPILER_ID +/* Define number of valid Fortran INTEGER KINDs (must be defined before F_IKIND)*/ +/* #undef H5_H5CONFIG_F_NUM_IKIND */ + /* Define valid Fortran INTEGER KINDs */ /* #undef H5_H5CONFIG_F_IKIND */ -/* Define number of valid Fortran INTEGER KINDs */ -/* #undef H5_H5CONFIG_F_NUM_IKIND */ - -/* Define number of valid Fortran REAL KINDs */ +/* Define number of valid Fortran REAL KINDs (must be defined before F_RKIND) */ /* #undef H5_H5CONFIG_F_NUM_RKIND */ /* Define valid Fortran REAL KINDs */ @@ -97,28 +98,21 @@ /* Define if the __attribute__(()) extension is present */ /* #undef H5_HAVE_ATTRIBUTE */ -/* Define if the compiler understands C99 designated initialization of structs - and unions */ -/* #undef H5_HAVE_C99_DESIGNATED_INITIALIZER */ - -/* Define if the compiler understands the __func__ keyword */ -/* #undef H5_HAVE_C99_FUNC */ - /* Define to 1 if you have the `clock_gettime' function. */ /* #undef H5_HAVE_CLOCK_GETTIME */ +/* Define to 1 if CLOCK_MONOTONIC_COARSE is available */ +/* #undef H5_HAVE_CLOCK_MONOTONIC_COARSE */ + /* Define if the function stack tracing code is to be compiled in */ /* #undef H5_HAVE_CODESTACK */ /* Define to 1 if you have the header file. */ -/* #undef H5_HAVE_CURL_H */ +/* #undef H5_HAVE_CURL_CURL_H */ /* Define if Darwin or Mac OS X */ /* #undef H5_HAVE_DARWIN */ -/* Define to 1 if you have the `difftime' function. */ -#define H5_HAVE_DIFFTIME 1 - /* Define if the direct I/O virtual file driver (VFD) should be compiled */ /* #undef H5_HAVE_DIRECT */ @@ -128,9 +122,6 @@ /* Define to 1 if you have the header file. */ /* #undef H5_HAVE_DLFCN_H */ -/* Define to 1 if you have the header file. */ -/* #undef H5_HAVE_DMALLOC_H */ - /* Define if library information should be embedded in the executables */ #define H5_HAVE_EMBEDDED_LIBINFO 1 @@ -155,18 +146,9 @@ /* Define to 1 if you have the `fork' function. */ /* #undef H5_HAVE_FORK */ -/* Define to 1 if you have the `frexpf' function. */ -/* #undef H5_HAVE_FREXPF */ - -/* Define to 1 if you have the `frexpl' function. */ -/* #undef H5_HAVE_FREXPL */ - /* Define to 1 if you have the `fseeko' function. */ /* #undef H5_HAVE_FSEEKO */ -/* Define if the compiler understands the __FUNCTION__ keyword */ -#define H5_HAVE_FUNCTION 1 - /* Determine if INTEGER*16 is available */ /* #undef H5_HAVE_Fortran_INTEGER_SIZEOF_16 */ @@ -176,9 +158,6 @@ /* Define to 1 if you have the `gethostname' function. */ #define H5_HAVE_GETHOSTNAME 1 -/* Define to 1 if you have the `getpwuid' function. */ -/* #undef H5_HAVE_GETPWUID */ - /* Define to 1 if you have the `getrusage' function. */ /* #undef H5_HAVE_GETRUSAGE */ @@ -191,22 +170,16 @@ /* Define to 1 if you have the header file. */ /* #undef H5_HAVE_HDFS_H */ -/* Define if the compiler understands inline */ -#define H5_HAVE_INLINE 1 - /* Define if parallel library will contain instrumentation to detect correct optimization operation */ /* #undef H5_HAVE_INSTRUMENTED_LIBRARY */ -/* Define to 1 if you have the header file. */ -#define H5_HAVE_INTTYPES_H 1 +/* Define if IOC VFD is built */ +/* #undef H5_HAVE_IOC_VFD */ /* Define to 1 if you have the `ioctl' function. */ /* #undef H5_HAVE_IOCTL */ -/* Define to 1 if you have the header file. */ -#define H5_HAVE_IO_H 1 - /* Define to 1 if you have the `crypto' library (-lcrypto). */ /* #undef H5_HAVE_LIBCRYPTO */ @@ -216,9 +189,6 @@ /* Define to 1 if you have the `dl' library (-ldl). */ /* #undef H5_HAVE_LIBDL */ -/* Define to 1 if you have the `dmalloc' library (-ldmalloc). */ -/* #undef H5_HAVE_LIBDMALLOC */ - /* Proceed to build with libhdfs */ /* #undef H5_HAVE_LIBHDFS */ @@ -228,9 +198,6 @@ /* Define to 1 if you have the `m' library (-lm). */ #define H5_HAVE_LIBM 1 -/* Define to 1 if you have the `mpe' library (-lmpe). */ -/* #undef H5_HAVE_LIBMPE */ - /* Define to 1 if you have the `pthread' library (-lpthread). */ /* #undef H5_HAVE_LIBPTHREAD */ @@ -243,42 +210,15 @@ /* Define to 1 if you have the `z' library (-lz). */ #define H5_HAVE_LIBZ 1 -/* Define to 1 if you have the `llround' function. */ -#define H5_HAVE_LLROUND 1 - -/* Define to 1 if you have the `llroundf' function. */ -#define H5_HAVE_LLROUNDF 1 - -/* Define to 1 if you have the `longjmp' function. */ -#define H5_HAVE_LONGJMP 1 - -/* Define to 1 if you have the `lround' function. */ -#define H5_HAVE_LROUND 1 - -/* Define to 1 if you have the `lroundf' function. */ -#define H5_HAVE_LROUNDF 1 - /* Define to 1 if you have the `lseek64' function. */ /* #undef H5_HAVE_LSEEK64 */ -/* Define to 1 if you have the `lstat' function. */ -/* #undef H5_HAVE_LSTAT */ - /* Define if the map API (H5M) should be compiled */ /* #undef H5_HAVE_MAP_API */ -/* Define to 1 if you have the header file. */ -#define H5_HAVE_MEMORY_H 1 - /* Define whether the Mirror virtual file driver (VFD) will be compiled */ /* #undef H5_HAVE_MIRROR_VFD */ -/* Define if we have MPE support */ -/* #undef H5_HAVE_MPE */ - -/* Define to 1 if you have the header file. */ -/* #undef H5_HAVE_MPE_H */ - /* Define if MPI_Comm_c2f and MPI_Comm_f2c exist */ /* #undef H5_HAVE_MPI_MULTI_LANG_Comm */ @@ -303,12 +243,24 @@ /* Define if we have parallel support */ /* #undef H5_HAVE_PARALLEL */ +/* Define if we have support for writing to filtered datasets in parallel */ +/* #undef H5_HAVE_PARALLEL_FILTERED_WRITES */ + /* Define if both pread and pwrite exist. */ /* #undef H5_HAVE_PREADWRITE */ /* Define to 1 if you have the header file. */ /* #undef H5_HAVE_PTHREAD_H */ +/* Define to 1 if 'pthread_condattr_setclock()' is available */ +/* #undef H5_HAVE_PTHREAD_CONDATTR_SETCLOCK */ + +/* Define to 1 if PTHREAD_MUTEX_ADAPTIVE_NP is available */ +/* #undef H5_HAVE_PTHREAD_MUTEX_ADAPTIVE_NP */ + +/* Define to 1 if you have the header file. */ +/* #undef H5_HAVE_PWD_H */ + /* Define to 1 if you have the header file. */ /* #undef H5_HAVE_QUADMATH_H */ @@ -322,87 +274,33 @@ compiled */ /* #undef H5_HAVE_ROS3_VFD */ -/* Define to 1 if you have the `round' function. */ -#define H5_HAVE_ROUND 1 - -/* Define to 1 if you have the `roundf' function. */ -#define H5_HAVE_ROUNDF 1 - -/* Define to 1 if you have the `setjmp' function. */ -#define H5_HAVE_SETJMP 1 - -/* Define to 1 if you have the header file. */ -#define H5_HAVE_SETJMP_H 1 - -/* Define to 1 if you have the `setsysinfo' function. */ -/* #undef H5_HAVE_SETSYSINFO */ - -/* Define to 1 if you have the `siglongjmp' function. */ -/* #undef H5_HAVE_SIGLONGJMP */ - -/* Define to 1 if you have the `signal' function. */ -#define H5_HAVE_SIGNAL 1 - -/* Define to 1 if you have the `sigprocmask' function. */ -/* #undef H5_HAVE_SIGPROCMASK */ - -/* Define to 1 if you have the `sigsetjmp' function. */ -/* #undef H5_HAVE_SIGSETJMP */ - -/* Define to 1 if you have the `snprintf' function. */ -/* #undef H5_HAVE_SNPRINTF */ - -/* Define to 1 if you have the `srandom' function. */ -/* #undef H5_HAVE_SRANDOM */ - /* Define to 1 if you have the `stat64' function. */ /* #undef H5_HAVE_STAT64 */ -/* Define if `struct stat' has the `st_blocks' field */ +/* Define if struct stat has the st_blocks field */ /* #undef H5_HAVE_STAT_ST_BLOCKS */ -/* Define to 1 if you have the header file. */ -#define H5_HAVE_STDBOOL_H 1 - -/* Define to 1 if you have the header file. */ -#define H5_HAVE_STDDEF_H 1 - -/* Define to 1 if you have the header file. */ -#define H5_HAVE_STDINT_H 1 - -/* Define to 1 if you have the header file for Cplusplus. */ -#define H5_HAVE_STDINT_H_CXX 1 - -/* Define to 1 if you have the header file. */ -#define H5_HAVE_STDLIB_H 1 +/* Define to 1 if you have the `strcasestr' function. */ +/* #undef H5_HAVE_STRCASESTR */ /* Define to 1 if you have the `strdup' function. */ #define H5_HAVE_STRDUP 1 -/* Define to 1 if you have the header file. */ -/* #undef H5_HAVE_STRINGS_H */ - -/* Define to 1 if you have the header file. */ -#define H5_HAVE_STRING_H 1 - -/* Define to 1 if you have the `strtoll' function. */ -#define H5_HAVE_STRTOLL 1 - -/* Define to 1 if you have the `strtoull' function. */ -#define H5_HAVE_STRTOULL 1 - /* Define if struct text_info is defined */ /* #undef H5_HAVE_STRUCT_TEXT_INFO */ /* Define if struct videoconfig is defined */ /* #undef H5_HAVE_STRUCT_VIDEOCONFIG */ +/* Define if Subfiling VFD is built */ +/* #undef H5_HAVE_SUBFILING_VFD */ + +/* Define if have stdatomic.h for Subfiling VFD */ +/* #undef H5_HAVE_STDATOMIC_H */ + /* Define to 1 if you have the `symlink' function. */ /* #undef H5_HAVE_SYMLINK */ -/* Define to 1 if you have the `system' function. */ -#define H5_HAVE_SYSTEM 1 - /* Define to 1 if you have the header file. */ /* #undef H5_HAVE_SYS_FILE_H */ @@ -456,9 +354,6 @@ /* Define to 1 if you have the `vasprintf' function. */ /* #undef H5_HAVE_VASPRINTF */ -/* Define to 1 if you have the `vsnprintf' function. */ -/* #undef H5_HAVE_VSNPRINTF */ - /* Define to 1 if you have the `waitpid' function. */ /* #undef H5_HAVE_WAITPID */ @@ -468,9 +363,6 @@ /* Define if your system has window style path name. */ #define H5_HAVE_WINDOW_PATH 1 -/* Define to 1 if you have the header file. */ -#define H5_HAVE_WINSOCK2_H 1 - /* Define to 1 if you have the header file. */ #define H5_HAVE_ZLIB_H 1 @@ -480,18 +372,15 @@ /* Define to 1 if you have the `_scrsize' function. */ /* #undef H5_HAVE__SCRSIZE */ -/* Define if the compiler understands __inline */ -#define H5_HAVE___INLINE 1 - -/* Define if the compiler understands __inline__ */ -/* #undef H5_HAVE___INLINE__ */ - /* Define if the library will ignore file locks when disabled */ #define H5_IGNORE_DISABLED_FILE_LOCKS 1 /* Define if the high-level library headers should be included in hdf5.h */ #define H5_INCLUDE_HL 1 +/* Define if new-style references should be used with dimension scales */ +/* #undef H5_DIMENSION_SCALES_WITH_NEW_REF */ + /* Define if your system can convert long double to (unsigned) long long values correctly. */ #define H5_LDOUBLE_TO_LLONG_ACCURATE 1 @@ -508,18 +397,9 @@ with special algorithm. */ /* #undef H5_LONG_TO_LDOUBLE_SPECIAL */ -/* Define if your system is power6 and cannot convert some long double values. */ -/* #undef H5_DISABLE_SOME_LDOUBLE_CONV */ - /* Define to the sub-directory where libtool stores uninstalled libraries. */ /* #undef H5_LT_OBJDIR */ -/* Define to enable internal memory allocation sanity checking. */ -/* #undef H5_MEMORY_ALLOC_SANITY_CHECK */ - -/* Define if we can violate pointer alignment restrictions */ -#define H5_NO_ALIGNMENT_RESTRICTIONS 1 - /* Define if deprecated public API symbols are disabled */ /* #undef H5_NO_DEPRECATED_SYMBOLS */ @@ -533,7 +413,7 @@ #define H5_PACKAGE_NAME "HDF5" /* Define to the full name and version of this package. */ -#define H5_PACKAGE_STRING "HDF5 1.12.1" +#define H5_PACKAGE_STRING "HDF5 1.14.3" /* Define to the one symbol short name of this package. */ #define H5_PACKAGE_TARNAME "hdf5" @@ -542,17 +422,14 @@ #define H5_PACKAGE_URL "http://www.hdfgroup.org" /* Define to the version of this package. */ -#define H5_PACKAGE_VERSION "1.12.1" +#define H5_PACKAGE_VERSION "1.14.3" /* Determine the maximum decimal precision in C */ -#define H5_PAC_C_MAX_REAL_PRECISION 0 +#define H5_PAC_C_MAX_REAL_PRECISION /* Define Fortran Maximum Real Decimal Precision */ #define H5_PAC_FC_MAX_REAL_PRECISION -/* Width for printf() for type `long long' or `__int64', use `ll' */ -#define H5_PRINTF_LL_WIDTH "I64" - /* The size of `bool', as computed by sizeof. */ #define H5_SIZEOF_BOOL 1 @@ -645,8 +522,7 @@ #endif -/* Define size of long long and/or __int64 bit integer type only if the type - exists. */ +/* The size of `long long', as computed by sizeof. */ #if !defined(__APPLE__) #define H5_SIZEOF_LONG_LONG 8 #else @@ -708,16 +584,10 @@ #define H5_SIZEOF_UNSIGNED 4 /* The size of `_Quad', as computed by sizeof. */ -#define H5_SIZEOF__QUAD 0 +#define H5_SIZEOF__QUAD /* The size of `__float128', as computed by sizeof. */ -#define H5_SIZEOF___FLOAT128 0 - -/* The size of `__int64', as computed by sizeof. */ -#define H5_SIZEOF___INT64 8 - -/* Define to 1 if you have the ANSI C header files. */ -#define H5_STDC_HEADERS 1 +#define H5_SIZEOF___FLOAT128 /* Define if strict file format checks are enabled */ /* #undef H5_STRICT_FORMAT_CHECKS */ @@ -726,9 +596,6 @@ PTHREAD_SCOPE_SYSTEM) call. */ /* #undef H5_SYSTEM_SCOPE_THREADS */ -/* Define to 1 if you can safely include both and . */ -/* #undef H5_TIME_WITH_SYS_TIME */ - /* Define using v1.6 public API symbols by default */ /* #undef H5_USE_16_API_DEFAULT */ @@ -739,23 +606,23 @@ /* #undef H5_USE_110_API_DEFAULT */ /* Define using v1.12 public API symbols by default */ -#define H5_USE_112_API_DEFAULT 1 +/* #undef H5_USE_112_API_DEFAULT */ + +/* Define using v1.14 public API symbols by default */ +#define H5_USE_114_API_DEFAULT 1 /* Define if the library will use file locking */ #define H5_USE_FILE_LOCKING 1 -/* Define if the library will use recursive RW locks for thread safety */ -/* #undef H5_USE_RECURSIVE_RW_LOCKS */ - /* Define if a memory checking tool will be used on the library, to cause library to be very picky about memory operations and also disable the internal free list manager code. */ /* #undef H5_USING_MEMCHECKER */ /* Version number of package */ -#define H5_VERSION "1.12.1" +#define H5_VERSION "1.14.3" -/* Data accuracy is prefered to speed during data conversions */ +/* Data accuracy is preferred to speed during data conversions */ #define H5_WANT_DATA_ACCURACY 1 /* Check exception handling functions during data conversions */ @@ -781,18 +648,9 @@ /* Define for large files, on AIX-style hosts. */ /* #undef H5__LARGE_FILES */ -/* Define to empty if `const' does not conform to ANSI C. */ -/* #undef H5_const */ - /* Define to `long int' if does not define. */ /* #undef H5_off_t */ -/* Define to `long' if does not define. */ -/* #undef H5_ptrdiff_t */ - -/* Define to `unsigned long' if does not define. */ -/* #undef H5_size_t */ - /* Define to `long' if does not define. */ /* #undef H5_ssize_t */ diff --git a/libs/windows/include/H5public.h b/libs/windows/include/H5public.h index 44072ba..0b259db 100644 --- a/libs/windows/include/H5public.h +++ b/libs/windows/include/H5public.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -34,62 +33,43 @@ #ifdef H5_HAVE_FEATURES_H #include /* For setting POSIX, BSD, etc. compatibility */ #endif -#ifdef H5_HAVE_SYS_TYPES_H -#include -#endif -#ifdef H5_STDC_HEADERS -#include /* For H5T_NATIVE_CHAR defn in H5Tpublic.h */ -#include /* For variadic functions in H5VLpublic.h */ -#endif -#ifndef __cplusplus -#ifdef H5_HAVE_STDINT_H -#include /* For C9x types */ -#endif + +/* C library header files for things that appear in HDF5 public headers */ +#ifdef __cplusplus +#include #else -#ifdef H5_HAVE_STDINT_H_CXX -#include /* For C9x types (when included from C++) */ +#include #endif -#endif -#ifdef H5_HAVE_INTTYPES_H -#include /* C99/POSIX.1 header for uint64_t, PRIu64 */ -#endif -#ifdef H5_HAVE_STDDEF_H +#include +#include +#include #include +#include + +/* Unlike most sys/ headers, which are POSIX-only, sys/types.h is available + * on Windows, though it doesn't necessarily contain all the POSIX types + * we need for HDF5 (e.g. ssize_t). + */ +#ifdef H5_HAVE_SYS_TYPES_H +#include #endif + #ifdef H5_HAVE_PARALLEL /* Don't link against MPI C++ bindings */ +#ifndef MPICH_SKIP_MPICXX #define MPICH_SKIP_MPICXX 1 -#define OMPI_SKIP_MPICXX 1 +#endif +#ifndef OMPI_SKIP_MPICXX +#define OMPI_SKIP_MPICXX 1 +#endif #include #ifndef MPI_FILE_NULL /* MPIO may be defined in mpi.h already */ #include #endif #endif -/* Include the Windows API adapter header early */ -#include "H5api_adpt.h" - -#ifdef __cplusplus -extern "C" { -#endif - -/* Macros for enabling/disabling particular GCC warnings */ -/* (see the following web-sites for more info: - * http://www.dbp-consulting.com/tutorials/SuppressingGCCWarnings.html - * http://gcc.gnu.org/onlinedocs/gcc/Diagnostic-Pragmas.html#Diagnostic-Pragmas - */ -/* These pragmas are only implemented usefully in gcc 4.6+ */ -#if ((__GNUC__ * 100) + __GNUC_MINOR__) >= 406 -#define H5_GCC_DIAG_JOINSTR(x, y) x y -#define H5_GCC_DIAG_DO_PRAGMA(x) _Pragma(#x) -#define H5_GCC_DIAG_PRAGMA(x) H5_GCC_DIAG_DO_PRAGMA(GCC diagnostic x) - -#define H5_GCC_DIAG_OFF(x) H5_GCC_DIAG_PRAGMA(push) H5_GCC_DIAG_PRAGMA(ignored H5_GCC_DIAG_JOINSTR("-W", x)) -#define H5_GCC_DIAG_ON(x) H5_GCC_DIAG_PRAGMA(pop) -#else -#define H5_GCC_DIAG_OFF(x) -#define H5_GCC_DIAG_ON(x) -#endif +/* Macro to hide a symbol from further preprocessor substitutions */ +#define H5_NO_EXPAND(x) (x) /* Version numbers */ /** @@ -99,11 +79,11 @@ extern "C" { /** * For minor interface/format changes */ -#define H5_VERS_MINOR 12 +#define H5_VERS_MINOR 14 /** * For tweaks, bug-fixes, or development */ -#define H5_VERS_RELEASE 1 +#define H5_VERS_RELEASE 3 /** * For pre-releases like \c snap0. Empty string for official releases. */ @@ -111,7 +91,7 @@ extern "C" { /** * Full version string */ -#define H5_VERS_INFO "HDF5 library version: 1.12.1" +#define H5_VERS_INFO "HDF5 library version: 1.14.3" #define H5check() H5check_version(H5_VERS_MAJOR, H5_VERS_MINOR, H5_VERS_RELEASE) @@ -188,12 +168,65 @@ extern "C" { (((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR == Min) && (H5_VERS_RELEASE <= Rel)) || \ ((H5_VERS_MAJOR == Maj) && (H5_VERS_MINOR < Min)) || (H5_VERS_MAJOR < Maj)) +/* Macros for various environment variables that HDF5 interprets */ +/** + * Used to specify the name of an HDF5 Virtual File Driver to use as + * the default file driver for file access. Setting this environment + * variable overrides the default file driver for File Access Property + * Lists. + */ +#define HDF5_DRIVER "HDF5_DRIVER" +/** + * Used to specify a configuration string for the HDF5 Virtual File + * Driver being used for file access. + */ +#define HDF5_DRIVER_CONFIG "HDF5_DRIVER_CONFIG" +/** + * Used to specify the name of an HDF5 Virtual Object Layer Connector + * to use as the default VOL connector for file access. Setting this + * environment variable overrides the default VOL connector for File + * Access Property Lists. + */ +#define HDF5_VOL_CONNECTOR "HDF5_VOL_CONNECTOR" +/** + * Used to specify a delimiter-separated (currently, ';' for Windows + * and ':' for other systems) list of paths that HDF5 should search + * when loading plugins. + */ +#define HDF5_PLUGIN_PATH "HDF5_PLUGIN_PATH" +/** + * Used to control the loading of HDF5 plugins at runtime. If this + * environment variable is set to the special string "::" (defined + * in H5PLpublic.h as H5PL_NO_PLUGIN), then dynamic loading of any + * HDF5 plugins will be disabled. No other values are valid for this + * environment variable. + */ +#define HDF5_PLUGIN_PRELOAD "HDF5_PLUGIN_PRELOAD" +/** + * Used to control whether HDF5 uses file locking when creating or + * opening a file. Valid values for this environment variable are + * as follows: + * + * "TRUE" or "1" - Request that file locks should be used + * "FALSE" or "0" - Request that file locks should NOT be used + * "BEST_EFFORT" - Request that file locks should be used and + * that any locking errors caused by file + * locking being disabled on the system + * should be ignored + */ +#define HDF5_USE_FILE_LOCKING "HDF5_USE_FILE_LOCKING" +/** + * Used to instruct HDF5 not to cleanup files created during testing. + */ +#define HDF5_NOCLEANUP "HDF5_NOCLEANUP" + /** * 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: + * The negative failure value is most commonly -1, but don't bet on it. + * + * The proper way to detect failure is something like: * \code * if((dset = H5Dopen2(file, name)) < 0) * fprintf(stderr, "unable to open the requested dataset\n"); @@ -202,11 +235,23 @@ extern "C" { 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 - * (false), positive (true), or negative (failure). The proper way to test - * for truth from a #htri_t function is: + * C99-style Boolean type. Successful return values are zero (false) or positive + * (true). The typical true value is 1 but don't bet on it. + * + * \deprecated Now that we require C99, hbool_t is typedef'd to C99's bool + * and hbool_t is considered deprecated. Due to its long-standing, + * widespread use, we have no plans to remove the hbool_t typedef + * from the public API, though we will probably switch to using + * bool in the public API starting in the next major release of HDF5. + * \attention Boolean functions cannot fail. + */ +#include +typedef bool hbool_t; +/** + * Three-valued Boolean type. 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: * \code * if ((retval = H5Tcommitted(type)) > 0) { * printf("data type is committed\n"); @@ -217,23 +262,16 @@ typedef int herr_t; * } * \endcode */ -#ifdef H5_HAVE_STDBOOL_H -#include -#else /* H5_HAVE_STDBOOL_H */ -#ifndef __cplusplus -#if defined(H5_SIZEOF_BOOL) && (H5_SIZEOF_BOOL != 0) -#define bool _Bool -#else -#define bool unsigned int -#endif -#define true 1 -#define false 0 -#endif /* __cplusplus */ -#endif /* H5_HAVE_STDBOOL_H */ -typedef bool hbool_t; -typedef int htri_t; +typedef int htri_t; -/* Define the ssize_t type if it not is defined */ +/* The signed version of size_t + * + * ssize_t is POSIX and not defined in any C standard. It's used in some + * public HDF5 API calls so this work-around will define it if it's not + * present. + * + * Use of ssize_t should be discouraged in new code. + */ #if H5_SIZEOF_SSIZE_T == 0 /* Undefine this size, we will re-define it in one of the sections below */ #undef H5_SIZEOF_SSIZE_T @@ -251,137 +289,52 @@ typedef long long ssize_t; #endif #endif -/* int64_t type is used for creation order field for links. It may be - * defined in Posix.1g, otherwise it is defined here. - */ -#if H5_SIZEOF_INT64_T >= 8 -#elif H5_SIZEOF_INT >= 8 -typedef int int64_t; -#undef H5_SIZEOF_INT64_T -#define H5_SIZEOF_INT64_T H5_SIZEOF_INT -#elif H5_SIZEOF_LONG >= 8 -typedef long int64_t; -#undef H5_SIZEOF_INT64_T -#define H5_SIZEOF_INT64_T H5_SIZEOF_LONG -#elif H5_SIZEOF_LONG_LONG >= 8 -typedef long long int64_t; -#undef H5_SIZEOF_INT64_T -#define H5_SIZEOF_INT64_T H5_SIZEOF_LONG_LONG -#else -#error "nothing appropriate for int64_t" -#endif - -/* uint64_t type is used for fields for H5O_info_t. It may be - * defined in Posix.1g, otherwise it is defined here. +/** + * The size of file objects. + * + * \internal Defined as a (minimum) 64-bit integer type. */ -#if H5_SIZEOF_UINT64_T >= 8 -#ifndef UINT64_MAX -#define UINT64_MAX ((uint64_t)-1) -#endif -#elif H5_SIZEOF_INT >= 8 -typedef unsigned uint64_t; -#define UINT64_MAX UINT_MAX -#undef H5_SIZEOF_UINT64_T -#define H5_SIZEOF_UINT64_T H5_SIZEOF_INT -#elif H5_SIZEOF_LONG >= 8 -typedef unsigned long uint64_t; -#define UINT64_MAX ULONG_MAX -#undef H5_SIZEOF_UINT64_T -#define H5_SIZEOF_UINT64_T H5_SIZEOF_LONG -#elif H5_SIZEOF_LONG_LONG >= 8 -typedef unsigned long long uint64_t; -#define UINT64_MAX ULLONG_MAX -#undef H5_SIZEOF_UINT64_T -#define H5_SIZEOF_UINT64_T H5_SIZEOF_LONG_LONG -#else -#error "nothing appropriate for uint64_t" -#endif +typedef uint64_t hsize_t; -/* - * The sizes of file objects have their own types defined here, use a minimum - * 64-bit type. - */ -#if H5_SIZEOF_LONG_LONG >= 8 -H5_GCC_DIAG_OFF("long-long") -typedef unsigned long long hsize_t; -typedef signed long long hssize_t; -H5_GCC_DIAG_ON("long-long") -#define PRIdHSIZE H5_PRINTF_LL_WIDTH "d" -#define PRIiHSIZE H5_PRINTF_LL_WIDTH "i" -#define PRIoHSIZE H5_PRINTF_LL_WIDTH "o" -#define PRIuHSIZE H5_PRINTF_LL_WIDTH "u" -#define PRIxHSIZE H5_PRINTF_LL_WIDTH "x" -#define PRIXHSIZE H5_PRINTF_LL_WIDTH "X" -#define H5_SIZEOF_HSIZE_T H5_SIZEOF_LONG_LONG -#define H5_SIZEOF_HSSIZE_T H5_SIZEOF_LONG_LONG -#define HSIZE_UNDEF ULLONG_MAX -#else -#error "nothing appropriate for hsize_t" -#endif - -/* - * File addresses have their own types. - */ -#if H5_SIZEOF_INT >= 8 -typedef unsigned haddr_t; -#define HADDR_UNDEF UINT_MAX -#define H5_SIZEOF_HADDR_T H5_SIZEOF_INT -#ifdef H5_HAVE_PARALLEL -#define HADDR_AS_MPI_TYPE MPI_UNSIGNED -#endif /* H5_HAVE_PARALLEL */ -#define PRIdHADDR "d" -#define PRIoHADDR "o" -#define PRIuHADDR "u" -#define PRIxHADDR "x" -#define PRIXHADDR "X" -#elif H5_SIZEOF_LONG >= 8 -typedef unsigned long haddr_t; -#define HADDR_UNDEF ULONG_MAX -#define H5_SIZEOF_HADDR_T H5_SIZEOF_LONG #ifdef H5_HAVE_PARALLEL -#define HADDR_AS_MPI_TYPE MPI_UNSIGNED_LONG -#endif /* H5_HAVE_PARALLEL */ -#define PRIdHADDR "ld" -#define PRIoHADDR "lo" -#define PRIuHADDR "lu" -#define PRIxHADDR "lx" -#define PRIXHADDR "lX" -#elif H5_SIZEOF_LONG_LONG >= 8 -typedef unsigned long long haddr_t; -#define HADDR_UNDEF ULLONG_MAX -#define H5_SIZEOF_HADDR_T H5_SIZEOF_LONG_LONG -#ifdef H5_HAVE_PARALLEL -#define HADDR_AS_MPI_TYPE MPI_LONG_LONG_INT -#endif /* H5_HAVE_PARALLEL */ -#define PRIdHADDR H5_PRINTF_LL_WIDTH "d" -#define PRIoHADDR H5_PRINTF_LL_WIDTH "o" -#define PRIuHADDR H5_PRINTF_LL_WIDTH "u" -#define PRIxHADDR H5_PRINTF_LL_WIDTH "x" -#define PRIXHADDR H5_PRINTF_LL_WIDTH "X" -#else -#error "nothing appropriate for haddr_t" +#define HSIZE_AS_MPI_TYPE MPI_UINT64_T #endif + +/** + * The size of file objects. Used when negative values are needed to indicate errors. + * + * \internal Defined as a (minimum) 64-bit integer type. Use of hssize_t + * should be discouraged in new code. + */ +typedef int64_t hssize_t; +#define PRIdHSIZE PRId64 +#define PRIiHSIZE PRIi64 +#define PRIoHSIZE PRIo64 +#define PRIuHSIZE PRIu64 +#define PRIxHSIZE PRIx64 +#define PRIXHSIZE PRIX64 +#define H5_SIZEOF_HSIZE_T 8 +#define H5_SIZEOF_HSSIZE_T 8 +#define HSIZE_UNDEF UINT64_MAX + +/** + * The address of an object in the file. + * + * \internal Defined as a (minimum) 64-bit unsigned integer type. + */ +typedef uint64_t haddr_t; +#define PRIdHADDR PRId64 +#define PRIoHADDR PRIo64 +#define PRIuHADDR PRIu64 +#define PRIxHADDR PRIx64 +#define PRIXHADDR PRIX64 +#define H5_SIZEOF_HADDR_T 8 +#define HADDR_UNDEF UINT64_MAX #define H5_PRINTF_HADDR_FMT "%" PRIuHADDR #define HADDR_MAX (HADDR_UNDEF - 1) -/* uint32_t type is used for creation order field for messages. It may be - * defined in Posix.1g, otherwise it is defined here. - */ -#if H5_SIZEOF_UINT32_T >= 4 -#elif H5_SIZEOF_SHORT >= 4 -typedef short uint32_t; -#undef H5_SIZEOF_UINT32_T -#define H5_SIZEOF_UINT32_T H5_SIZEOF_SHORT -#elif H5_SIZEOF_INT >= 4 -typedef unsigned int uint32_t; -#undef H5_SIZEOF_UINT32_T -#define H5_SIZEOF_UINT32_T H5_SIZEOF_INT -#elif H5_SIZEOF_LONG >= 4 -typedef unsigned long uint32_t; -#undef H5_SIZEOF_UINT32_T -#define H5_SIZEOF_UINT32_T H5_SIZEOF_LONG -#else -#error "nothing appropriate for uint32_t" +#ifdef H5_HAVE_PARALLEL +#define HADDR_AS_MPI_TYPE MPI_UINT64_T #endif //! @@ -401,9 +354,9 @@ typedef enum { /* (Actually, any positive value will cause the iterator to stop and pass back * that positive value to the function that called the iterator) */ -#define H5_ITER_ERROR (-1) -#define H5_ITER_CONT (0) -#define H5_ITER_STOP (1) +#define H5_ITER_ERROR (-1) /**< Error, stop iteration */ +#define H5_ITER_CONT (0) /**< Continue iteration */ +#define H5_ITER_STOP (1) /**< Stop iteration, short-circuit success */ //! /** @@ -450,17 +403,16 @@ typedef struct H5O_token_t { //! /** - * Allocation statistics info struct + * Library shutdown callback, used by H5atclose(). */ -typedef struct H5_alloc_stats_t { - unsigned long long total_alloc_bytes; /**< Running count of total # of bytes allocated */ - size_t curr_alloc_bytes; /**< Current # of bytes allocated */ - size_t peak_alloc_bytes; /**< Peak # of bytes allocated */ - size_t max_block_size; /**< Largest block allocated */ - size_t total_alloc_blocks_count; /**< Running count of total # of blocks allocated */ - size_t curr_alloc_blocks_count; /**< Current # of blocks allocated */ - size_t peak_alloc_blocks_count; /**< Peak # of blocks allocated */ -} H5_alloc_stats_t; +typedef void (*H5_atclose_func_t)(void *ctx); + +/* API adapter header (defines H5_DLL, etc.) */ +#include "H5api_adpt.h" + +#ifdef __cplusplus +extern "C" { +#endif /* Functions in H5.c */ /** @@ -475,10 +427,37 @@ typedef struct H5_alloc_stats_t { * issued. If one finds that an HDF5 library function is failing * inexplicably, H5open() can be called first. It is safe to call * H5open() before an application issues any other function calls to - * the HDF5 library as there are no damaging side effects in calling + * the HDF5 library, as there are no damaging side effects in calling * it more than once. */ H5_DLL herr_t H5open(void); +/** + * \ingroup H5 + * \brief Registers a callback for the library to invoke when it's closing. + * \param[in] func The function pointer to invoke + * \param[in] ctx Context to pass to \p func when invoked + * \return \herr_t + * + * \details H5atclose() registers a callback that the HDF5 library will invoke + * when closing. The full capabilities of the HDF5 library are + * available to callbacks invoked through this mechanism, and library + * shutdown will only begin in earnest when all callbacks have been + * invoked and have returned. + * + * Registered callbacks are invoked in LIFO order, similar to the + * Standard C 'atexit' routine. For example, if 'func1' is registered, + * then 'func2', when the library is closing 'func2', will + * be invoked first, then 'func1'. + * + * The \p ctx pointer will be passed to \p func when it's invoked. + * NULL is allowed for \p ctx. + * + * If the HDF5 library is initialized and closed more than once, the + * \p func callback must be registered within each open/close cycle. + * + * \since 1.14.0 + */ +H5_DLL herr_t H5atclose(H5_atclose_func_t func, void *ctx); /** * \ingroup H5 * \brief Flushes all data to disk, closes all open objects, and releases memory @@ -501,13 +480,13 @@ H5_DLL herr_t H5close(void); * function is in situations where the library is dynamically linked * into an application and is un-linked from the application before * exit() gets called. In those situations, a routine installed with - * atexit() would jump to a routine which was no longer in memory, + * atexit() would jump to a routine that was no longer in memory, * causing errors. * * \attention In order to be effective, this routine \Emph{must} be called * before any other HDF5 function calls, and must be called each * time the library is loaded/linked into the application (the first - * time and after it's been un-loaded). + * time and after it's been unloaded). */ H5_DLL herr_t H5dont_atexit(void); /** @@ -519,7 +498,7 @@ H5_DLL herr_t H5dont_atexit(void); * of the library, freeing any unused memory. * * It is not required that H5garbage_collect() be called at any - * particular time; it is only necessary in certain situations where + * particular time; it is only necessary for certain situations where * the application has performed actions that cause the library to * allocate many objects. The application should call * H5garbage_collect() if it eventually releases those objects and @@ -600,30 +579,9 @@ H5_DLL herr_t H5set_free_list_limits(int reg_global_lim, int reg_list_lim, int a * garbage collected with H5garbage_collect(). These lists are global * for the entire library. * - * \since 1.12.1 + * \since 1.10.7 */ H5_DLL herr_t H5get_free_list_sizes(size_t *reg_size, size_t *arr_size, size_t *blk_size, size_t *fac_size); -/** - * \ingroup H5 - * \brief Gets the memory allocation statistics for the library - * - * \param[out] stats Memory allocation statistics - * \return \herr_t - * - * \details H5get_alloc_stats() gets the memory allocation statistics for the - * library, if the \c --enable-memory-alloc-sanity-check option was - * given when building the library. Applications can check whether - * this option was enabled detecting if the - * \c H5_MEMORY_ALLOC_SANITY_CHECK macro is defined. This option is - * enabled by default for debug builds of the library and disabled by - * default for non-debug builds. If the option is not enabled, all the - * values returned with be 0. These statistics are global for the - * entire library, but do not include allocations from chunked dataset - * I/O filters or non-native VOL connectors. - * - * \since 1.12.1 - */ -H5_DLL herr_t H5get_alloc_stats(H5_alloc_stats_t *stats); /** * \ingroup H5 * \brief Returns the HDF library release number @@ -671,7 +629,7 @@ H5_DLL herr_t H5get_libversion(unsigned *majnum, unsigned *minnum, unsigned *rel * currently linked. If this check fails, H5check_version() causes the * application to abort (by means of a standard C abort() call) and * prints information that is usually useful for debugging. This - * precaution is is taken to avoid the risks of data corruption or + * precaution is taken to avoid the risks of data corruption or * segmentation faults. * * The most common cause of this failure is that an application was @@ -687,6 +645,22 @@ H5_DLL herr_t H5get_libversion(unsigned *majnum, unsigned *minnum, unsigned *rel * */ H5_DLL herr_t H5check_version(unsigned majnum, unsigned minnum, unsigned relnum); +/** + * \ingroup H5 + * \brief Checks whether the HDF5 library is closing. + * \param[out] is_terminating Flag indicating whether library is shutting down + * \return \herr_t + * + * \details H5is_library_terminating() queries whether the HDF5 library is in + * the process of shutting down. The \p is_terminating flag will only + * be set to true after shutdown starts, it will be false before the + * library has been initialized, while the library is initialized, and + * after it has been closed. The value of \p is_terminating is + * undefined if this routine fails. + * + * \since 1.14.0 + */ +H5_DLL herr_t H5is_library_terminating(hbool_t *is_terminating); /** * \ingroup H5 * \brief Determines whether the HDF5 library was built with the thread-safety @@ -710,13 +684,13 @@ H5_DLL herr_t H5is_library_threadsafe(hbool_t *is_ts); * \param[in] mem Buffer to be freed. Can be NULL * \return \herr_t * - * \details H5free_memory() frees memory that has been allocated by the caller + * \details H5free_memory() frees the memory that has been allocated by the caller * with H5allocate_memory() or by the HDF5 library on behalf of the * caller. * * H5Tget_member_name() provides an example of memory allocation on * behalf of the caller: The function returns a buffer containing the - * name of a compound datatype member. It is the caller’s + * name of a compound datatype member. It is the caller's * responsibility to eventually free that buffer with H5free_memory(). * * \attention It is especially important to use this function to free memory @@ -742,7 +716,7 @@ H5_DLL herr_t H5is_library_threadsafe(hbool_t *is_ts); H5_DLL herr_t H5free_memory(void *mem); /** * \ingroup H5 - * \brief Frees memory allocated by the HDF5 library + * \brief Allocates memory that will be freed later internally. * * \param[in] size The size in bytes of the buffer to be allocated * \param[in] clear Flag whether the new buffer is to be initialized with 0 @@ -755,12 +729,12 @@ H5_DLL herr_t H5free_memory(void *mem); * will later be freed internally by the HDF5 library. * * The boolean \p clear parameter specifies whether the buffer should - * be initialized. If clear is \c TRUE, all bits in the buffer are to be - * set to 0 (zero); if clear is \c FALSE, the buffer will not be + * be initialized. If clear is \c true, all bits in the buffer are to be + * set to 0 (zero); if clear is \c false, the buffer will not be * initialized. * * This function is intended to have the semantics of malloc() and - * calloc(). However, unlike malloc() and calloc() which allow for a + * calloc(). However, unlike malloc() and calloc(), which allow for a * "special" pointer to be returned instead of NULL, this function * always returns NULL on failure or when size is set to 0 (zero). * @@ -772,7 +746,7 @@ H5_DLL herr_t H5free_memory(void *mem); * the same library that initially allocated it. In most cases, the * HDF5 API uses resources that are allocated and freed either * entirely by the user or entirely by the library, so this is not a - * problem. In rare cases, however, HDF5 API calls will free memory + * problem. In rare cases, however, HDF5 API calls will free the memory * that the user allocated. This function allows the user to safely * allocate this memory.\n * It is particularly important to use this function to allocate diff --git a/libs/windows/include/H5version.h b/libs/windows/include/H5version.h index 89ee7f6..945868b 100644 --- a/libs/windows/include/H5version.h +++ b/libs/windows/include/H5version.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -36,12 +35,16 @@ #define H5_USE_110_API 1 #endif /* H5_USE_110_API_DEFAULT && !H5_USE_110_API */ +#if defined(H5_USE_112_API_DEFAULT) && !defined(H5_USE_112_API) + #define H5_USE_112_API 1 +#endif /* H5_USE_112_API_DEFAULT && !H5_USE_112_API */ + /* Issue error if contradicting macros have been defined. */ /* (Can't use an older (deprecated) API version if deprecated symbols have been disabled) */ -#if (defined(H5_USE_16_API) || defined(H5_USE_18_API) || defined(H5_USE_110_API)) && defined(H5_NO_DEPRECATED_SYMBOLS) +#if (defined(H5_USE_16_API) || defined(H5_USE_18_API) || defined(H5_USE_110_API) || defined(H5_USE_112_API)) && defined(H5_NO_DEPRECATED_SYMBOLS) #error "Can't choose old API versions when deprecated APIs are disabled" -#endif /* (defined(H5_USE_16_API) || defined(H5_USE_18_API) || defined(H5_USE_110_API)) && defined(H5_NO_DEPRECATED_SYMBOLS) */ +#endif /* (defined(H5_USE_16_API) || defined(H5_USE_18_API) || defined(H5_USE_110_API) || defined(H5_USE_112_API)) && defined(H5_NO_DEPRECATED_SYMBOLS) */ /* If a particular "global" version of the library's interfaces is chosen, @@ -499,6 +502,178 @@ #endif /* H5_USE_110_API */ +#ifdef H5_USE_112_API + +/*************/ +/* Functions */ +/*************/ + +#if !defined(H5Acreate_vers) + #define H5Acreate_vers 2 +#endif /* !defined(H5Acreate_vers) */ + +#if !defined(H5Aiterate_vers) + #define H5Aiterate_vers 2 +#endif /* !defined(H5Aiterate_vers) */ + +#if !defined(H5Dcreate_vers) + #define H5Dcreate_vers 2 +#endif /* !defined(H5Dcreate_vers) */ + +#if !defined(H5Dopen_vers) + #define H5Dopen_vers 2 +#endif /* !defined(H5Dopen_vers) */ + +#if !defined(H5Eclear_vers) + #define H5Eclear_vers 2 +#endif /* !defined(H5Eclear_vers) */ + +#if !defined(H5Eget_auto_vers) + #define H5Eget_auto_vers 2 +#endif /* !defined(H5Eget_auto_vers) */ + +#if !defined(H5Eprint_vers) + #define H5Eprint_vers 2 +#endif /* !defined(H5Eprint_vers) */ + +#if !defined(H5Epush_vers) + #define H5Epush_vers 2 +#endif /* !defined(H5Epush_vers) */ + +#if !defined(H5Eset_auto_vers) + #define H5Eset_auto_vers 2 +#endif /* !defined(H5Eset_auto_vers) */ + +#if !defined(H5Ewalk_vers) + #define H5Ewalk_vers 2 +#endif /* !defined(H5Ewalk_vers) */ + +#if !defined(H5Fget_info_vers) + #define H5Fget_info_vers 2 +#endif /* !defined(H5Fget_info_vers) */ + +#if !defined(H5Gcreate_vers) + #define H5Gcreate_vers 2 +#endif /* !defined(H5Gcreate_vers) */ + +#if !defined(H5Gopen_vers) + #define H5Gopen_vers 2 +#endif /* !defined(H5Gopen_vers) */ + +#if !defined(H5Lget_info_vers) + #define H5Lget_info_vers 2 +#endif /* !defined(H5Lget_info_vers) */ + +#if !defined(H5Lget_info_by_idx_vers) + #define H5Lget_info_by_idx_vers 2 +#endif /* !defined(H5Lget_info_by_idx_vers) */ + +#if !defined(H5Literate_vers) + #define H5Literate_vers 2 +#endif /* !defined(H5Literate_vers) */ + +#if !defined(H5Literate_by_name_vers) + #define H5Literate_by_name_vers 2 +#endif /* !defined(H5Literate_by_name_vers) */ + +#if !defined(H5Lvisit_vers) + #define H5Lvisit_vers 2 +#endif /* !defined(H5Lvisit_vers) */ + +#if !defined(H5Lvisit_by_name_vers) + #define H5Lvisit_by_name_vers 2 +#endif /* !defined(H5Lvisit_by_name_vers) */ + +#if !defined(H5Oget_info_vers) + #define H5Oget_info_vers 3 +#endif /* !defined(H5Oget_info_vers) */ + +#if !defined(H5Oget_info_by_idx_vers) + #define H5Oget_info_by_idx_vers 3 +#endif /* !defined(H5Oget_info_by_idx_vers) */ + +#if !defined(H5Oget_info_by_name_vers) + #define H5Oget_info_by_name_vers 3 +#endif /* !defined(H5Oget_info_by_name_vers) */ + +#if !defined(H5Ovisit_vers) + #define H5Ovisit_vers 3 +#endif /* !defined(H5Ovisit_vers) */ + +#if !defined(H5Ovisit_by_name_vers) + #define H5Ovisit_by_name_vers 3 +#endif /* !defined(H5Ovisit_by_name_vers) */ + +#if !defined(H5Pencode_vers) + #define H5Pencode_vers 2 +#endif /* !defined(H5Pencode_vers) */ + +#if !defined(H5Pget_filter_vers) + #define H5Pget_filter_vers 2 +#endif /* !defined(H5Pget_filter_vers) */ + +#if !defined(H5Pget_filter_by_id_vers) + #define H5Pget_filter_by_id_vers 2 +#endif /* !defined(H5Pget_filter_by_id_vers) */ + +#if !defined(H5Pinsert_vers) + #define H5Pinsert_vers 2 +#endif /* !defined(H5Pinsert_vers) */ + +#if !defined(H5Pregister_vers) + #define H5Pregister_vers 2 +#endif /* !defined(H5Pregister_vers) */ + +#if !defined(H5Rdereference_vers) + #define H5Rdereference_vers 2 +#endif /* !defined(H5Rdereference_vers) */ + +#if !defined(H5Rget_obj_type_vers) + #define H5Rget_obj_type_vers 2 +#endif /* !defined(H5Rget_obj_type_vers) */ + +#if !defined(H5Sencode_vers) + #define H5Sencode_vers 2 +#endif /* !defined(H5Sencode_vers) */ + +#if !defined(H5Tarray_create_vers) + #define H5Tarray_create_vers 2 +#endif /* !defined(H5Tarray_create_vers) */ + +#if !defined(H5Tcommit_vers) + #define H5Tcommit_vers 2 +#endif /* !defined(H5Tcommit_vers) */ + +#if !defined(H5Tget_array_dims_vers) + #define H5Tget_array_dims_vers 2 +#endif /* !defined(H5Tget_array_dims_vers) */ + +#if !defined(H5Topen_vers) + #define H5Topen_vers 2 +#endif /* !defined(H5Topen_vers) */ + +/************/ +/* Typedefs */ +/************/ + +#if !defined(H5E_auto_t_vers) + #define H5E_auto_t_vers 2 +#endif /* !defined(H5E_auto_t_vers) */ + +#if !defined(H5O_info_t_vers) + #define H5O_info_t_vers 2 +#endif /* !defined(H5O_info_t_vers) */ + +#if !defined(H5O_iterate_t_vers) + #define H5O_iterate_t_vers 2 +#endif /* !defined(H5O_iterate_t_vers) */ + +#if !defined(H5Z_class_t_vers) + #define H5Z_class_t_vers 2 +#endif /* !defined(H5Z_class_t_vers) */ + +#endif /* H5_USE_112_API */ + /* Choose the correct version of each API symbol, defaulting to the latest * version of each. The "best" name for API parameters/data structures diff --git a/libs/windows/include/hdf5.h b/libs/windows/include/hdf5.h index c13e472..5be0efe 100644 --- a/libs/windows/include/hdf5.h +++ b/libs/windows/include/hdf5.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * @@ -24,6 +23,7 @@ #include "H5ACpublic.h" /* Metadata cache */ #include "H5Dpublic.h" /* Datasets */ #include "H5Epublic.h" /* Errors */ +#include "H5ESpublic.h" /* Event Sets */ #include "H5Fpublic.h" /* Files */ #include "H5FDpublic.h" /* File drivers */ #include "H5Gpublic.h" /* Groups */ @@ -40,6 +40,20 @@ #include "H5VLpublic.h" /* Virtual Object Layer */ #include "H5Zpublic.h" /* Data filters */ +/* Plugin/component developer headers */ +#include "H5ESdevelop.h" /* Event Sets */ +#include "H5FDdevelop.h" /* File drivers */ +#include "H5Idevelop.h" /* ID management */ +#include "H5Ldevelop.h" /* Links */ +#include "H5Tdevelop.h" /* Datatypes */ +#include "H5TSdevelop.h" /* Threadsafety */ +#include "H5Zdevelop.h" /* Data filters */ + +/* Virtual object layer (VOL) connector developer support */ +#include "H5VLconnector.h" /* VOL connector author routines */ +#include "H5VLconnector_passthru.h" /* Pass-through VOL connector author routines */ +#include "H5VLnative.h" /* Native VOL connector macros, for VOL connector authors */ + /* Predefined file drivers */ #include "H5FDcore.h" /* Files stored entirely in memory */ #include "H5FDdirect.h" /* Linux direct I/O */ @@ -49,6 +63,7 @@ #include "H5FDmirror.h" /* Mirror VFD and IPC definitions */ #include "H5FDmpi.h" /* MPI-based file drivers */ #include "H5FDmulti.h" /* Usage-partitioned file family */ +#include "H5FDonion.h" /* Onion file I/O */ #include "H5FDros3.h" /* R/O S3 "file" I/O */ #include "H5FDsec2.h" /* POSIX unbuffered file I/O */ #include "H5FDsplitter.h" /* Twin-channel (R/W & R/O) I/O passthrough */ @@ -56,6 +71,8 @@ #ifdef H5_HAVE_WINDOWS #include "H5FDwindows.h" /* Win32 I/O */ #endif +#include "H5FDsubfiling.h" /* Subfiling VFD */ +#include "H5FDioc.h" /* I/O Concentrator VFD */ /* Virtual object layer (VOL) connectors */ #include "H5VLnative.h" /* Native VOL connector */ diff --git a/libs/windows/include/hdf5_hl.h b/libs/windows/include/hdf5_hl.h index 9960b97..7757b39 100644 --- a/libs/windows/include/hdf5_hl.h +++ b/libs/windows/include/hdf5_hl.h @@ -1,6 +1,5 @@ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * Copyright by The HDF Group. * - * Copyright by the Board of Trustees of the University of Illinois. * * All rights reserved. * * * * This file is part of HDF5. The full HDF5 copyright notice, including * diff --git a/libs/windows/include/libaec.h b/libs/windows/include/libaec.h index 44505e4..b159f34 100644 --- a/libs/windows/include/libaec.h +++ b/libs/windows/include/libaec.h @@ -2,19 +2,7 @@ * @file libaec.h * * @section LICENSE - * Copyright 2012 - 2019 - * - * Mathis Rosenhauer, Moritz Hanke, Joerg Behrens - * Deutsches Klimarechenzentrum GmbH - * Bundesstr. 45a - * 20146 Hamburg Germany - * - * Luis Kornblueh - * Max-Planck-Institut fuer Meteorologie - * Bundesstr. 53 - * 20146 Hamburg - * Germany - * + * Copyright 2021 Mathis Rosenhauer, Moritz Hanke, Joerg Behrens, Luis Kornblueh * All rights reserved. * * Redistribution and use in source and binary forms, with or without @@ -52,12 +40,16 @@ #include -#include "libaec_Export.h" - #ifdef __cplusplus extern "C"{ #endif +#if BUILDING_LIBAEC && HAVE_VISIBILITY +# define LIBAEC_DLL_EXPORTED __attribute__((__visibility__("default"))) +#else +# define LIBAEC_DLL_EXPORTED +#endif + struct internal_state; struct aec_stream { @@ -83,7 +75,7 @@ struct aec_stream { /* block size in samples */ unsigned int block_size; - /* Reference sample interval, the number of Coded Data Sets + /* Reference sample interval, the number of blocks * between consecutive reference samples (up to 4096). */ unsigned int rsi; @@ -113,7 +105,9 @@ struct aec_stream { /* Use restricted set of code options */ #define AEC_RESTRICTED 16 -/* Pad RSI to byte boundary. Only for decoding CCSDS sample data. */ +/* Pad RSI to byte boundary. Only used for decoding some CCSDS sample + * data. Do not use this to produce new data as it violates the + * standard. */ #define AEC_PAD_RSI 32 /* Do not enforce standard regarding legal block sizes. */ @@ -140,26 +134,27 @@ struct aec_stream { * set AEC_FLUSH to drain all output. * * It is not possible to continue encoding of the same stream after it - * has been flushed because the last byte may be padded with fill - * bits. */ + * has been flushed. For one, the last block may be padded zeros after + * preprocessing. Secondly, the last encoded byte may be padded with + * fill bits. */ #define AEC_FLUSH 1 /*********************************************/ /* Streaming encoding and decoding functions */ /*********************************************/ -libaec_EXPORT int aec_encode_init(struct aec_stream *strm); -libaec_EXPORT int aec_encode(struct aec_stream *strm, int flush); -libaec_EXPORT int aec_encode_end(struct aec_stream *strm); +LIBAEC_DLL_EXPORTED int aec_encode_init(struct aec_stream *strm); +LIBAEC_DLL_EXPORTED int aec_encode(struct aec_stream *strm, int flush); +LIBAEC_DLL_EXPORTED int aec_encode_end(struct aec_stream *strm); -libaec_EXPORT int aec_decode_init(struct aec_stream *strm); -libaec_EXPORT int aec_decode(struct aec_stream *strm, int flush); -libaec_EXPORT int aec_decode_end(struct aec_stream *strm); +LIBAEC_DLL_EXPORTED int aec_decode_init(struct aec_stream *strm); +LIBAEC_DLL_EXPORTED int aec_decode(struct aec_stream *strm, int flush); +LIBAEC_DLL_EXPORTED int aec_decode_end(struct aec_stream *strm); /***************************************************************/ /* Utility functions for encoding or decoding a memory buffer. */ /***************************************************************/ -libaec_EXPORT int aec_buffer_encode(struct aec_stream *strm); -libaec_EXPORT int aec_buffer_decode(struct aec_stream *strm); +LIBAEC_DLL_EXPORTED int aec_buffer_encode(struct aec_stream *strm); +LIBAEC_DLL_EXPORTED int aec_buffer_decode(struct aec_stream *strm); #ifdef __cplusplus } diff --git a/libs/windows/include/szlib.h b/libs/windows/include/szlib.h new file mode 100644 index 0000000..256b3a4 --- /dev/null +++ b/libs/windows/include/szlib.h @@ -0,0 +1,82 @@ +/** + * @file szlib.h + * + * @section LICENSE + * Copyright 2021 Mathis Rosenhauer, Moritz Hanke, Joerg Behrens, Luis Kornblueh + * All rights reserved. + * + * Redistribution and use in source and binary forms, with or without + * modification, are permitted provided that the following conditions + * are met: + * + * 1. Redistributions of source code must retain the above copyright + * notice, this list of conditions and the following disclaimer. + * 2. Redistributions in binary form must reproduce the above + * copyright notice, this list of conditions and the following + * disclaimer in the documentation and/or other materials provided + * with the distribution. + * + * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS + * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT + * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS + * FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE + * COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, + * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) + * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED + * OF THE POSSIBILITY OF SUCH DAMAGE. + * + * @section DESCRIPTION + * + * Adaptive Entropy Coding library + * + */ + +#ifndef SZLIB_H +#define SZLIB_H 1 + +#include + +#define SZ_ALLOW_K13_OPTION_MASK 1 +#define SZ_CHIP_OPTION_MASK 2 +#define SZ_EC_OPTION_MASK 4 +#define SZ_LSB_OPTION_MASK 8 +#define SZ_MSB_OPTION_MASK 16 +#define SZ_NN_OPTION_MASK 32 +#define SZ_RAW_OPTION_MASK 128 + +#define SZ_OK AEC_OK +#define SZ_OUTBUFF_FULL 2 + +#define SZ_NO_ENCODER_ERROR -1 +#define SZ_PARAM_ERROR AEC_CONF_ERROR +#define SZ_MEM_ERROR AEC_MEM_ERROR + +#define SZ_MAX_PIXELS_PER_BLOCK 32 +#define SZ_MAX_BLOCKS_PER_SCANLINE 128 +#define SZ_MAX_PIXELS_PER_SCANLINE \ + (SZ_MAX_BLOCKS_PER_SCANLINE) * (SZ_MAX_PIXELS_PER_BLOCK) + +typedef struct SZ_com_t_s +{ + int options_mask; + int bits_per_pixel; + int pixels_per_block; + int pixels_per_scanline; +} SZ_com_t; + +LIBAEC_DLL_EXPORTED int SZ_BufftoBuffCompress( + void *dest, size_t *destLen, + const void *source, size_t sourceLen, + SZ_com_t *param); +LIBAEC_DLL_EXPORTED int SZ_BufftoBuffDecompress( + void *dest, size_t *destLen, + const void *source, size_t sourceLen, + SZ_com_t *param); + +LIBAEC_DLL_EXPORTED int SZ_encoder_enabled(void); + +#endif /* SZLIB_H */ diff --git a/libs/windows/include/zconf.h b/libs/windows/include/zconf.h index 352f552..38b7146 100644 --- a/libs/windows/include/zconf.h +++ b/libs/windows/include/zconf.h @@ -40,6 +40,9 @@ # define crc32 z_crc32 # define crc32_combine z_crc32_combine # define crc32_combine64 z_crc32_combine64 +# define crc32_combine_gen z_crc32_combine_gen +# define crc32_combine_gen64 z_crc32_combine_gen64 +# define crc32_combine_op z_crc32_combine_op # define crc32_z z_crc32_z # define deflate z_deflate # define deflateBound z_deflateBound @@ -240,7 +243,11 @@ #endif #ifdef Z_SOLO - typedef unsigned long z_size_t; +# ifdef _WIN64 + typedef unsigned long long z_size_t; +# else + typedef unsigned long z_size_t; +# endif #else # define z_longlong long long # if defined(NO_SIZE_T) @@ -351,6 +358,9 @@ # ifdef FAR # undef FAR # endif +# ifndef WIN32_LEAN_AND_MEAN +# define WIN32_LEAN_AND_MEAN +# endif # include /* No need for _export, use ZLIB.DEF instead. */ /* For complete Windows compatibility, use WINAPI, not __stdcall. */ @@ -469,11 +479,18 @@ typedef uLong FAR uLongf; # undef _LARGEFILE64_SOURCE #endif -#if defined(__WATCOMC__) && !defined(Z_HAVE_UNISTD_H) -# define Z_HAVE_UNISTD_H +#ifndef Z_HAVE_UNISTD_H +# ifdef __WATCOMC__ +# define Z_HAVE_UNISTD_H +# endif +#endif +#ifndef Z_HAVE_UNISTD_H +# if defined(_LARGEFILE64_SOURCE) && !defined(_WIN32) +# define Z_HAVE_UNISTD_H +# endif #endif #ifndef Z_SOLO -# if defined(Z_HAVE_UNISTD_H) || defined(_LARGEFILE64_SOURCE) +# if defined(Z_HAVE_UNISTD_H) # include /* for SEEK_*, off_t, and _LFS64_LARGEFILE */ # ifdef VMS # include /* for off_t */ @@ -509,7 +526,7 @@ typedef uLong FAR uLongf; #if !defined(_WIN32) && defined(Z_LARGE64) # define z_off64_t off64_t #else -# if defined(_WIN32) && !defined(__GNUC__) && !defined(Z_SOLO) +# if defined(_WIN32) && !defined(__GNUC__) # define z_off64_t __int64 # else # define z_off64_t z_off_t diff --git a/libs/windows/lib/hdf5.lib b/libs/windows/lib/hdf5.lib index 07bb8f8..5ba7736 100644 Binary files a/libs/windows/lib/hdf5.lib and b/libs/windows/lib/hdf5.lib differ diff --git a/libs/windows/lib/hdf5_cpp.lib b/libs/windows/lib/hdf5_cpp.lib index 8e441ff..a5e179f 100644 Binary files a/libs/windows/lib/hdf5_cpp.lib and b/libs/windows/lib/hdf5_cpp.lib differ