summaryrefslogtreecommitdiffstats
path: root/src/H5Fpublic.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/H5Fpublic.h')
-rw-r--r--src/H5Fpublic.h588
1 files changed, 97 insertions, 491 deletions
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index 24fe350..164b412 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -47,27 +47,23 @@
* We're assuming that these constants are used rather early in the hdf5
* session.
*/
-#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /**< absence of rdwr => rd-only */
-#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /**< open for read and write */
-#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /**< overwrite existing files */
-#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /**< fail if file already exists*/
+#define H5F_ACC_RDONLY (H5CHECK H5OPEN 0x0000u) /**< Absence of RDWR: read-only */
+#define H5F_ACC_RDWR (H5CHECK H5OPEN 0x0001u) /**< Open for read and write */
+#define H5F_ACC_TRUNC (H5CHECK H5OPEN 0x0002u) /**< Overwrite existing files */
+#define H5F_ACC_EXCL (H5CHECK H5OPEN 0x0004u) /**< Fail if file already exists*/
/* NOTE: 0x0008u was H5F_ACC_DEBUG, now deprecated */
-#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /**< create non-existing files */
+#define H5F_ACC_CREAT (H5CHECK H5OPEN 0x0010u) /**< Create non-existing files */
#define H5F_ACC_SWMR_WRITE \
- (H5CHECK 0x0020u) /**< indicate that this file is open for writing in a \
- single-writer/multi-reader (SWMR) scenario. \
- Note that the process(es) opening the file for reading must \
- open the file with RDONLY access, and use the special "SWMR_READ" \
- access flag. */
+ (H5CHECK 0x0020u) /**< Indicate that this file is open for writing in a \
+ * single-writer/multi-reader (SWMR) scenario. \
+ * Note that the process(es) opening the file for reading \
+ * must open the file with #H5F_ACC_RDONLY and use the \
+ * #H5F_ACC_SWMR_READ access flag. */
#define H5F_ACC_SWMR_READ \
- (H5CHECK 0x0040u) /**< indicate that this file is \
- * open for reading in a \
- * single-writer/multi-reader (SWMR) \
- * scenario. Note that the \
- * process(es) opening the file \
- * for SWMR reading must also \
- * open the file with the RDONLY \
- * flag. */
+ (H5CHECK 0x0040u) /**< Indicate that this file is open for reading in a \
+ * single-writer/multi-reader (SWMR) scenario. Note that \
+ * the process(es) opening the file for SWMR reading must \
+ * also open the file with the #H5F_ACC_RDONLY flag. */
/**
* Default property list identifier
@@ -91,7 +87,7 @@
#define H5F_FAMILY_DEFAULT (hsize_t)0
#ifdef H5_HAVE_PARALLEL
-/*
+/**
* Use this constant string as the MPI_Info key to set H5Fmpio debug flags.
* To turn on H5Fmpio debug flags, set the MPI_Info value with this key to
* have the value of a string consisting of the characters that turn on the
@@ -101,11 +97,12 @@
#endif /* H5_HAVE_PARALLEL */
/**
- * The difference between a single file and a set of mounted files
+ * The scope of an operation such as H5Fflush(), e.g.,
+ * a single file vs. a set of mounted files
*/
typedef enum H5F_scope_t {
- H5F_SCOPE_LOCAL = 0, /**< specified file handle only */
- H5F_SCOPE_GLOBAL = 1 /**< entire virtual file */
+ H5F_SCOPE_LOCAL = 0, /**< The specified file handle only */
+ H5F_SCOPE_GLOBAL = 1 /**< The entire virtual file */
} H5F_scope_t;
/**
@@ -117,16 +114,16 @@ typedef enum H5F_scope_t {
* How does file close behave?
*/
typedef enum H5F_close_degree_t {
- H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlining VFL */
+ H5F_CLOSE_DEFAULT = 0, /**< Use the degree pre-defined by underlying VFD */
H5F_CLOSE_WEAK = 1, /**< File closes only after all opened objects are closed */
- H5F_CLOSE_SEMI = 2, /**< If no opened objects, file is close; otherwise, file close fails */
+ H5F_CLOSE_SEMI = 2, /**< If no opened objects, file is closed; otherwise, file close fails */
H5F_CLOSE_STRONG = 3 /**< If there are opened objects, close them first, then close file */
} H5F_close_degree_t;
/**
* Current "global" information about file
*/
-//! [H5F_info2_t_snip]
+//! <!-- [H5F_info2_t_snip] -->
typedef struct H5F_info2_t {
struct {
unsigned version; /**< Superblock version # */
@@ -144,7 +141,7 @@ typedef struct H5F_info2_t {
H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */
} sohm;
} H5F_info2_t;
-//! [H5F_info2_t_snip]
+//! <!-- [H5F_info2_t_snip] -->
/**
* Types of allocation requests. The values larger than #H5FD_MEM_DEFAULT
@@ -176,12 +173,12 @@ typedef enum H5F_mem_t {
/**
* Free space section information
*/
-//! [H5F_sect_info_t_snip]
+//! <!-- [H5F_sect_info_t_snip] -->
typedef struct H5F_sect_info_t {
haddr_t addr; /**< Address of free space section */
hsize_t size; /**< Size of free space section */
} H5F_sect_info_t;
-//! [H5F_sect_info_t_snip]
+//! <!-- [H5F_sect_info_t_snip] -->
/**
* Library's format versions
@@ -193,7 +190,7 @@ typedef enum H5F_libver_t {
H5F_LIBVER_V110 = 2, /**< Use the latest v110 format for storing objects */
H5F_LIBVER_V112 = 3, /**< Use the latest v112 format for storing objects */
H5F_LIBVER_V114 = 4, /**< Use the latest v114 format for storing objects */
- H5F_LIBVER_NBOUNDS
+ H5F_LIBVER_NBOUNDS /**< Sentinel */
} H5F_libver_t;
#define H5F_LIBVER_LATEST H5F_LIBVER_V114
@@ -201,7 +198,7 @@ typedef enum H5F_libver_t {
/**
* File space handling strategy
*/
-//! [H5F_fspace_strategy_t_snip]
+//! <!-- [H5F_fspace_strategy_t_snip] -->
typedef enum H5F_fspace_strategy_t {
H5F_FSPACE_STRATEGY_FSM_AGGR = 0, /**< Mechanisms: free-space managers, aggregators, and virtual file
drivers This is the library default when not set */
@@ -211,7 +208,7 @@ typedef enum H5F_fspace_strategy_t {
H5F_FSPACE_STRATEGY_NONE = 3, /**< Mechanisms: virtual file drivers */
H5F_FSPACE_STRATEGY_NTYPES /**< Sentinel */
} H5F_fspace_strategy_t;
-//! [H5F_fspace_strategy_t_snip]
+//! <!-- [H5F_fspace_strategy_t_snip] -->
/**
* File space handling strategy for release 1.10.0
@@ -228,7 +225,7 @@ typedef enum H5F_file_space_type_t {
H5F_FILE_SPACE_NTYPES /**< Sentinel */
} H5F_file_space_type_t;
-//! [H5F_retry_info_t_snip]
+//! <!-- [H5F_retry_info_t_snip] -->
#define H5F_NUM_METADATA_READ_RETRY_TYPES 21
/**
@@ -239,7 +236,7 @@ typedef struct H5F_retry_info_t {
unsigned nbins;
uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES];
} H5F_retry_info_t;
-//! [H5F_retry_info_t_snip]
+//! <!-- [H5F_retry_info_t_snip] -->
/**
* Callback for H5Pset_object_flush_cb() in a file access property list
@@ -277,11 +274,6 @@ extern "C" {
*/
H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id);
/**
- * \example H5Fcreate.c
- * After creating an HDF5 file with H5Fcreate(), we close it with
- * H5Fclose().
- */
-/**
* \ingroup H5F
*
* \brief Creates an HDF5 file
@@ -321,7 +313,8 @@ H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id);
* this file identifier should be closed by calling H5Fclose() when
* it is no longer needed.
*
- * \include H5Fcreate.c
+ * \par Example
+ * \snippet H5F_examples.c minimal
*
* \note #H5F_ACC_TRUNC and #H5F_ACC_EXCL are mutually exclusive; use
* exactly one.
@@ -359,6 +352,11 @@ H5_DLL htri_t H5Fis_accessible(const char *container_name, hid_t fapl_id);
*
*/
H5_DLL hid_t H5Fcreate(const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Fcreate}
+ */
H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigned app_line,
const char *filename, unsigned flags, hid_t fcpl_id, hid_t fapl_id, hid_t es_id);
/**
@@ -408,6 +406,9 @@ H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigne
* identifier should be closed by calling H5Fclose() when it is no
* longer needed.
*
+ * \par Example
+ * \snippet H5F_examples.c open
+ *
* \note #H5F_ACC_RDWR and #H5F_ACC_RDONLY are mutually exclusive; use
* exactly one.
*
@@ -451,6 +452,11 @@ H5_DLL hid_t H5Fcreate_async(const char *app_file, const char *app_func, unsigne
*
*/
H5_DLL hid_t H5Fopen(const char *filename, unsigned flags, hid_t fapl_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Fopen}
+ */
H5_DLL hid_t H5Fopen_async(const char *app_file, const char *app_func, unsigned app_line,
const char *filename, unsigned flags, hid_t access_plist, hid_t es_id);
/**
@@ -479,6 +485,11 @@ H5_DLL hid_t H5Fopen_async(const char *app_file, const char *app_func, unsigned
*
*/
H5_DLL hid_t H5Freopen(hid_t file_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Freopen}
+ */
H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigned app_line, hid_t file_id,
hid_t es_id);
/**
@@ -503,6 +514,9 @@ H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigne
* global or local. Valid values are as follows:
* \scopes
*
+ * \par Example
+ * \snippet H5F_examples.c flush
+ *
* \attention HDF5 does not possess full control over buffering. H5Fflush()
* flushes the internal HDF5 buffers then asks the operating system
* (the OS) to flush the system buffers for the open files. After
@@ -511,13 +525,13 @@ H5_DLL hid_t H5Freopen_async(const char *app_file, const char *app_func, unsigne
*
*/
H5_DLL herr_t H5Fflush(hid_t object_id, H5F_scope_t scope);
-H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigned app_line, hid_t object_id,
- H5F_scope_t scope, hid_t es_id);
/**
- * \example H5Fclose.c
- * After creating an HDF5 file with H5Fcreate(), we close it with
- * H5Fclose().
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Fflush}
*/
+H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigned app_line, hid_t object_id,
+ H5F_scope_t scope, hid_t es_id);
/**
* \ingroup H5F
*
@@ -534,8 +548,8 @@ H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigne
* identifier, or shared datatype identifier), the file will be fully
* closed and access will end.
*
- * Use H5Fclose() as shown in the following example:
- * \include H5Fclose.c
+ * \par Example
+ * \snippet H5F_examples.c minimal
*
* \note \Bold{Delayed close:} Note the following deviation from the
* above-described behavior. If H5Fclose() is called for a file but one
@@ -562,6 +576,11 @@ H5_DLL herr_t H5Fflush_async(const char *app_file, const char *app_func, unsigne
*
*/
H5_DLL herr_t H5Fclose(hid_t file_id);
+/**
+ * --------------------------------------------------------------------------
+ * \ingroup ASYNC
+ * \async_variant_of{H5Fclose}
+ */
H5_DLL herr_t H5Fclose_async(const char *app_file, const char *app_func, unsigned app_line, hid_t file_id,
hid_t es_id);
/**
@@ -655,7 +674,7 @@ H5_DLL hid_t H5Fget_access_plist(hid_t file_id);
* \note The function will not return an error if intent is NULL; it will
* simply do nothing.
*
- * \version 1.10.0 C function enhanced to work with SWMR functionality.
+ * \version 1.10.0 Function enhanced to work with SWMR functionality.
*
* \since 1.8.0
*
@@ -707,7 +726,7 @@ H5_DLL herr_t H5Fget_fileno(hid_t file_id, unsigned long *fileno);
* \c (#H5F_OBJ_DATASET|#H5F_OBJ_GROUP) would call for datasets and
* groups.
*
- * \version 1.6.8, 1.8.2 C function return type changed to \c ssize_t.
+ * \version 1.6.8, 1.8.2 Function return type changed to \c ssize_t.
* \version 1.6.5 #H5F_OBJ_LOCAL has been added as a qualifier on the types
* of objects to be counted. #H5F_OBJ_LOCAL restricts the
* search to objects opened through current file identifier.
@@ -745,9 +764,9 @@ H5_DLL ssize_t H5Fget_obj_count(hid_t file_id, unsigned types);
* To retrieve a count of open objects, use the H5Fget_obj_count()
* function. This count can be used to set the \p max_objs parameter.
*
- * \version 1.8.2 C function return type changed to \c ssize_t and \p
+ * \version 1.8.2 Function return type changed to \c ssize_t and \p
* max_objs parameter datatype changed to \c size_t.
- * \version 1.6.8 C function return type changed to \c ssize_t and \p
+ * \version 1.6.8 Function return type changed to \c ssize_t and \p
* max_objs parameter datatype changed to \c size_t.
* \since 1.6.0
*
@@ -798,6 +817,9 @@ H5_DLL herr_t H5Fget_vfd_handle(hid_t file_id, hid_t fapl, void **file_handle);
* attribute, then the file will be mounted at the location where the
* attribute, dataset, or named datatype is attached.
*
+ * \par Example
+ * \snippet H5F_examples.c mount
+ *
* \note To date, no file mount properties have been defined in HDF5. The
* proper value to pass for \p plist is #H5P_DEFAULT, indicating the
* default file mount property list.
@@ -868,8 +890,6 @@ H5_DLL hssize_t H5Fget_freespace(hid_t file_id);
* if any, the HDF5 portion of the file, and any data that may have
* been appended beyond the data written through the HDF5 library.
*
- * \version 1.6.3 Fortran subroutine introduced in this release.
- *
* \since 1.6.3
*
*/
@@ -948,9 +968,7 @@ H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment);
*
* \note \Bold{Recommended Reading:} This function is part of the file image
* operations feature set. It is highly recommended to study the guide
- * "HDF5 File Image Operations" before using this feature set.\n See the
- * "See Also" section below for links to other elements of HDF5 file
- * image operations. \todo Fix the references.
+ * \ref_file_image_ops before using this feature set.
*
* \attention H5Pget_file_image() will fail, returning a negative value, if the
* file is too large for the supplied buffer.
@@ -958,8 +976,6 @@ H5_DLL herr_t H5Fincrement_filesize(hid_t file_id, hsize_t increment);
* \see H5LTopen_file_image(), H5Pset_file_image(), H5Pget_file_image(),
* H5Pset_file_image_callbacks(), H5Pget_file_image_callbacks()
*
- * \version 1.8.13 Fortran subroutine added in this release.
- *
* \since 1.8.0
*
*/
@@ -976,197 +992,18 @@ H5_DLL ssize_t H5Fget_file_image(hid_t file_id, void *buf_ptr, size_t buf_len);
* \ref H5AC-cache-config-t "here".
* \return \herr_t
*
+ * \note The \c in direction applies only to the H5AC_cache_config_t::version
+ * field. All other fields are out parameters.
+ *
* \details H5Fget_mdc_config() loads the current metadata cache configuration
* into the instance of H5AC_cache_config_t pointed to by the \p config_ptr
- * parameter.
- *
- * Note that the \c version field of \p config_ptr must be initialized
- * --this allows the library to support old versions of the H5AC_cache_config_t
- * structure.
- *
- * \par General configuration section
- * <table>
- * <tr>
- * <td><em>int</em> <code>version</code> </td>
- * <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This field should
- * be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined in H5ACpublic.h).</td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>rpt_fcn_enabled</code> </td>
- * <td><p>OUT: Boolean flag indicating whether the adaptive cache resize report function is enabled. This
- * field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is
- * reported via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.</p><p>The
- * report function is not supported code, and can be expected to change between versions of the
- * library. Use it at your own risk.</p></td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>open_trace_file</code> </td>
- * <td>OUT: Boolean field indicating whether the <code>trace_file_name</code> field should be used to
- * open a trace file for the cache. This field will always be set to <code>0</code> in this
- * context.</td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>close_trace_file</code> </td>
- * <td>OUT: Boolean field indicating whether the current trace file (if any) should be closed. This field
- * will always be set to <code>0</code> in this context.</td></tr>
- * <tr>
- * <td><em>char*</em><code>trace_file_name</code> </td>
- * <td>OUT: Full path name of the trace file to be opened if the <code>open_trace_file</code> field is
- * set to <code>1</code>. This field will always be set to the empty string in this context.</td></tr>
- * <tr>
- * <td><em>hbool_t</em> <code>evictions_enabled</code> </td>
- * <td>OUT: Boolean flag indicating whether metadata cache entry evictions are
- * enabled.</td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>set_initial_size</code> </td>
- * <td>OUT: Boolean flag indicating whether the cache should be created with a user specified initial
- * maximum size.<p>If the configuration is loaded from the cache, this flag will always be set
- * to <code>0</code>.</p></td>
- * </tr>
- * <tr>
- * <td><em>size_t</em> <code>initial_size</code> </td>
- * <td>OUT: Initial maximum size of the cache in bytes, if applicable.<p>If the configuration is loaded
- * from the cache, this field will contain the cache maximum size as of the time of the
- * call.</p></td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>min_clean_fraction</code> </td>
- * <td>OUT: Float value specifying the minimum fraction of the cache that must be kept either clean or
- * empty when possible.</td>
- * </tr>
- * <tr>
- * <td><em>size_t</em> <code>max_size</code> </td>
- * <td>OUT: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select
- * as the maximum cache size.</td>
- * </tr>
- * <tr>
- * <td><em>size_t</em> <code>min_size</code> </td>
- * <td>OUT: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select
- * as the maximum cache size.</td>
- * </tr>
- * <tr>
- * <td><em>long int</em> <code>epoch_length</code> </td>
- * <td>OUT: Number of cache accesses between runs of the adaptive cache resize
- * code.</td>
- * </tr>
- * </table>
- *
- * \par Increment configuration section
- * <table>
- * <tr>
- * <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code> </td>
- * <td>OUT: Enumerated value indicating the operational mode of the automatic cache size increase code.
- * At present, only the following values are legal:<p>\c H5C_incr__off: Automatic cache size increase
- * is disabled.</p><p>\c H5C_incr__threshold: Automatic cache size increase is enabled using the hit
- * rate threshold algorithm.</p></td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>lower_hr_threshold</code> </td>
- * <td>OUT: Hit rate threshold used in the hit rate threshold cache size increase algorithm.</td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>increment</code> </td>
- * <td>OUT: The factor by which the current maximum cache size is multiplied to obtain an initial new
- * maximum cache size if a size increase is triggered in the hit rate threshold cache size increase
- * algorithm.</td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>apply_max_increment</code> </td>
- * <td>OUT: Boolean flag indicating whether an upper limit will be applied to the size of cache size
- * increases.</td>
- * </tr>
- * <tr>
- * <td><em>size_t</em> <code>max_increment</code> </td>
- * <td>OUT: The maximum number of bytes by which the maximum cache size can be increased in a single step
- * -- if applicable.</td>
- * </tr>
- * <tr>
- * <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code> </td>
- * <td>OUT: Enumerated value indicating the operational mode of the flash cache size increase code. At
- * present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is
- * disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add
- * space algorithm.</p></td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>flash_threshold</code> </td>
- * <td>OUT: The factor by which the current maximum cache size is multiplied to obtain the minimum size
- * entry / entry size increase which may trigger a flash cache size
- * increase.</td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>flash_multiple</code> </td>
- * <td>OUT: The factor by which the size of the triggering entry / entry size increase is multiplied to
- * obtain the initial cache size increment. This increment may be reduced to reflect existing free
- * space in the cache and the <code>max_size</code> field above.</td>
- * </tr>
- * </table>
- *
- * \par Decrement configuration section
- * <table>
- * <tr><td colspan="2"><strong>Decrement configuration
- * section:</strong></td>
- * </tr>
- * <tr>
- * <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code> </td>
- * <td>OUT: Enumerated value indicating the operational mode of the automatic cache size decrease code.
- * At present, the following values are legal:<p>H5C_decr__off: Automatic cache size decrease is
- * disabled, and the remaining decrement fields are ignored.</p><p>H5C_decr__threshold: Automatic
- * cache size decrease is enabled using the hit rate threshold algorithm.</p><p>H5C_decr__age_out:
- * Automatic cache size decrease is enabled using the ageout algorithm.</p>
- * <p>H5C_decr__age_out_with_threshold: Automatic cache size decrease is enabled using the ageout
- * with hit rate threshold algorithm</p></td>
- * </tr>
- * <tr><td><em>double</em> <code>upper_hr_threshold</code> </td>
- * <td>OUT: Upper hit rate threshold. This value is only used if the decr_mode is either
- * H5C_decr__threshold or H5C_decr__age_out_with_threshold.</td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>decrement</code> </td>
- * <td>OUT: Factor by which the current max cache size is multiplied to obtain an initial value for the
- * new cache size when cache size reduction is triggered in the hit rate threshold cache size reduction
- * algorithm.</td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>apply_max_decrement</code> </td>
- * <td>OUT: Boolean flag indicating whether an upper limit should be applied to the size of cache size
- * decreases.</td>
- * </tr>
- * <tr>
- * <td><em>size_t</em> <code>max_decrement</code> </td>
- * <td>OUT: The maximum number of bytes by which cache size can be decreased if any single step, if
- * applicable.</td>
- * </tr>
- * <tr>
- * <td><em>int</em> <code>epochs_before_eviction</code> </td>
- * <td>OUT: The minimum number of epochs that an entry must reside unaccessed in cache before being
- * evicted under either of the ageout cache size reduction algorithms.</td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>apply_empty_reserve</code> </td>
- * <td>OUT: Boolean flag indicating whether an empty reserve should be maintained under either of the
- * ageout cache size reduction algorithms.</td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>empty_reserve</code> </td>
- * <td>OUT: Empty reserve for use with the ageout cache size reduction algorithms, if applicable.</td>
- * </tr>
- * </table>
- *
- * \par Parallel configuration section
- * <table>
- * <tr><td><em>int</em> <code>dirty_bytes_threshold</code> </td>
- * <td>OUT: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the
- * metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the
- * number of bytes of dirty metadata created since the last synchronization exceeds this
- * limit.</p></td>
- * </tr>
- * </table>
+ * parameter.\n
+ * The fields of the H5AC_cache_config_t structure are shown below:
+ * \snippet H5ACpublic.h H5AC_cache_config_t_snip
+ * \click4more
*
* \since 1.8.0
*
- * \todo Fix the reference!
- *
*/
H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
/**
@@ -1183,240 +1020,11 @@ H5_DLL herr_t H5Fget_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
*
* \details H5Fset_mdc_config() attempts to configure the file's metadata cache
* according configuration supplied in \p config_ptr.
- *
- * \par General configuration fields
- * <table>
- * <tr>
- * <td><em>int</em> <code>version</code></td>
- * <td>IN: Integer field indicating the the version of the H5AC_cache_config_t in use. This
- * field should be set to #H5AC__CURR_CACHE_CONFIG_VERSION (defined
- * in H5ACpublic.h).</td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>rpt_fcn_enabled</code></td>
- * <td>IN: Boolean flag indicating whether the adaptive cache resize report function is enabled. This
- * field should almost always be set to disabled (<code>0</code>). Since resize algorithm activity is
- * reported via stdout, it MUST be set to disabled (<code>0</code>) on Windows machines.<p>The report
- * function is not supported code, and can be expected to change between versions of the library. Use
- * it at your own risk.</p></td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>open_trace_File</code></td>
- * <td>IN: Boolean field indicating whether the <code>trace_file_name</code> field should be used to open
- * a trace file for the cache.<p>The trace file is a debuging feature that allows the capture of top
- * level metadata cache requests for purposes of debugging and/or optimization. This field should
- * <p>This field should only normally be set to <code>0</code>, as trace file collection imposes
- * considerable overhead.</p> be set to <code>1</code> when the <code>trace_file_name</code> contains
- * the full path of the desired trace file, and either there is no open trace file on the cache, or the
- * <code>close_trace_file</code> field is also <code>1</code>.</p><p>The trace file feature is
- * unsupported unless used at the direction of The HDF Group. It is intended to allow The HDF Group to
- * collect a trace of cache activity in cases of occult failures and/or poor performance seen in the
- * field, so as to aid in reproduction in the lab. If you use it absent the direction of The HDF Group,
- * you are on your own.</p></td>
- * </tr>
- * <tr><td><em>hbool_t</em> <code>close_trace_file</code></td>
- * <td>IN: Boolean field indicating whether the current trace file (if any) should be closed.<p>See the
- * above comments on the <code>open_trace_file</code> field. This field should be set to
- * <code>0</code> unless there is an open trace file on the cache that you wish to close.</p><p>The
- * trace file feature is unsupported unless used at the direction of The HDF Group. It is intended to
- * allow The HDF Group to collect a trace of cache activity in cases of occult failures and/or poor
- * performance seen in the field, so as to aid in reproduction in the lab. If you use it absent the
- * direction of The HDF Group, you are on your own.</p></td>
- * </tr>
- * <tr>
- * <td><em>char</em> <code>trace_file_name[]</code></td>
- * <td>IN: Full path of the trace file to be opened if the <code>open_trace_file</code> field is set
- * to <code>1</code>.<p>In the parallel case, an ascii representation of the mpi rank of the process
- * will be appended to the file name to yield a unique trace file name for each process.</p><p>The
- * length of the path must not exceed #H5AC__MAX_TRACE_FILE_NAME_LEN characters.</p><p>The trace file
- * feature is unsupported unless used at the direction of The HDF Group. It is intended to allow The
- * HDF Group to collect a trace of cache activity in cases of occult failures and/or poor performance
- * seen in the field, so as to aid in reproduction in the lab. If you use it absent the direction of
- * The HDF Group, you are on your own.</p></td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>evictions_enabled</code></td>
- * <td>IN: A boolean flag indicating whether evictions from the metadata cache are enabled. This flag is
- * initially set to enabled (<code>1</code>).<p>In rare circumstances, the raw data throughput
- * requirements may be so high that the user wishes to postpone metadata writes so as to reserve I/O
- * throughput for raw data. The <code>evictions_enabled</code> field exists to allow this. However,
- * this is an extreme step, and you have no business doing it unless you have read the User Guide
- * section on metadata caching, and have considered all other options carefully.</p><p>The
- * <code>evictions_enabled</code> field may not be set to disabled (<code>0</code>) unless all adaptive
- * cache resizing code is disabled via the <code>incr_mode</code>, <code>flash_incr_mode</code>, and
- * <code>decr_mode</code> fields.</p><p>When this flag is set to disabled (<code>0</code>), the
- * metadata cache will not attempt to evict entries to make space for new entries, and thus will grow
- * without bound.</p><p>Evictions will be re-enabled when this field is set back to <code>1</code>.
- * This should be done as soon as possible.</p></td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>set_initial_size</code></td>
- * <td>IN: Boolean flag indicating whether the cache should be forced to the user specified initial
- * size.</td>
- * </tr>
- * <tr>
- * <td><em>size_t</em> <code>initial_size</code></td>
- * <td>IN: If <code>set_initial_size</code> is set to <code>1</code>, then <code>initial_size</code> must
- * contain the desired initial size in bytes. This value must lie in the closed interval
- * <code>[min_size, max_size]</code>. (see below)</td>
- * </tr>
- * <tr><td><em>double</em> <code>min_clean_fraction</code></td>
- * <td>IN: This field specifies the minimum fraction of the cache that must be kept either clean or
- * empty.<p>The value must lie in the interval [0.0, 1.0]. 0.01 is a good place to start in the serial
- * case. In the parallel case, a larger value is needed -- see <a
- * href="/display/HDF5/Metadata+Caching+in+HDF5">Metadata Caching in HDF5</a> in the collection
- * "Advanced Topics in HDF5."</p></td>
- * </tr>
- * <tr><td><em>size_t</em> <code>max_size</code></td>
- * <td>IN: Upper bound (in bytes) on the range of values that the adaptive cache resize code can select
- * as the maximum cache size.</td>
- * </tr>
- * <tr>
- * <td><em>size_t</em> <code>min_size</code></td>
- * <td>IN: Lower bound (in bytes) on the range of values that the adaptive cache resize code can select
- * as the maximum cache size.</td>
- * </tr>
- * <tr><td><em>long int</em> <code>epoch_length</code></td>
- * <td>IN: Number of cache accesses between runs of the adaptive cache resize code. 50,000 is a good
- * starting number.</td>
- * </tr>
- * </table>
- *
- * \par Increment configuration fields
- * <table>
- * <tr>
- * <td><em>enum H5C_cache_incr_mode</em> <code>incr_mode</code></td>
- * <td>IN: Enumerated value indicating the operational mode of the automatic cache size increase code. At
- * present, only two values are legal:<p>\c H5C_incr__off: Automatic cache size increase is disabled,
- * and the remaining increment fields are ignored.</p><p>\c H5C_incr__threshold: Automatic cache size
- * increase is enabled using the hit rate threshold algorithm.</p></td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>lower_hr_threshold</code></td>
- * <td>IN: Hit rate threshold used by the hit rate threshold cache size increment algorithm.<p>When the
- * hit rate over an epoch is below this threshold and the cache is full, the maximum size of the
- * cache is multiplied by increment (below), and then clipped as necessary to stay within max_size, and
- * possibly max_increment.</p><p>This field must lie in the interval [0.0, 1.0]. 0.8 or 0.9 is a good
- * starting point.</p></td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>increment</code></td>
- * <td>IN: Factor by which the hit rate threshold cache size increment algorithm multiplies the current
- * maximum cache size to obtain a tentative new cache size.<p>The actual cache size increase will be
- * clipped to satisfy the max_size specified in the general configuration, and possibly max_increment
- * below.</p><p>The parameter must be greater than or equal to 1.0 -- 2.0 is a reasonable
- * value.</p><p>If you set it to 1.0, you will effectively disable cache size increases.</p></td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>apply_max_increment</code></td>
- * <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size
- * increases.</td>
- * </tr>
- * <tr>
- * <td><em>size_t</em> <code>max_increment</code></td>
- * <td>IN: Maximum number of bytes by which cache size can be increased in a single step -- if
- * applicable.</td>
- * </tr>
- * <tr>
- * <td><em>enum H5C_cache_flash_incr_mode</em> <code>flash_incr_mode</code></td>
- * <td>IN: Enumerated value indicating the operational mode of the flash cache size increase code. At
- * present, only the following values are legal:<p>\c H5C_flash_incr__off: Flash cache size increase is
- * disabled.</p><p>\c H5C_flash_incr__add_space: Flash cache size increase is enabled using the add
- * space algorithm.</p></td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>flash_threshold</code></td>
- * <td>IN: The factor by which the current maximum cache size is multiplied to obtain the minimum size
- * entry / entry size increase which may trigger a flash cache size increase.<p>At present, this value
- * must lie in the range [0.1, 1.0].</p></td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>flash_multiple</code></td>
- * <td>IN: The factor by which the size of the triggering entry / entry size increase is multiplied to
- * obtain the initial cache size increment. This increment may be reduced to reflect existing free
- * space in the cache and the <code>max_size</code> field above.<p>At present, this field must lie in
- * the range [0.1, 10.0].</p></td>
- * </tr>
- * </table>
- *
- * \par Decrement configuration fields
- * <table>
- * <tr>
- * <td><em>enum H5C_cache_decr_mode</em> <code>decr_mode</code></td>
- * <td>IN: Enumerated value indicating the operational mode of the automatic cache size decrease code. At
- * present, the following values are legal:<p>\c H5C_decr__off: Automatic cache size decrease is
- * disabled.</p><p>\c H5C_decr__threshold: Automatic cache size decrease is enabled using the hit
- * rate threshold algorithm.</p><p>\c H5C_decr__age_out: Automatic cache size decrease is enabled using
- * the ageout algorithm.</p><p>\c H5C_decr__age_out_with_threshold: Automatic cache size decrease is
- * enabled using the ageout with hit rate threshold algorithm</p></td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>upper_hr_threshold</code></td>
- * <td>IN: Hit rate threshold for the hit rate threshold and ageout with hit rate threshold cache size
- * decrement algorithms.<p>When \c decr_mode is \c H5C_decr__threshold, and the hit rate over a given
- * epoch exceeds the supplied threshold, the current maximum cache size is multiplied by decrement to
- * obtain a tentative new (and smaller) maximum cache size.</p><p>When \c decr_mode is \c
- * H5C_decr__age_out_with_threshold, there is no attempt to find and evict aged out entries unless the
- * hit rate in the previous epoch exceeded the supplied threshold.</p><p>This field must lie in the
- * interval [0.0, 1.0].</p><p>For \c H5C_incr__threshold, .9995 or .99995 is a good place to
- * start.</p><p>For \c H5C_decr__age_out_with_threshold, .999 might be more useful.</p></td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>decrement</code></td>
- * <td>IN: In the hit rate threshold cache size decrease algorithm, this parameter contains the factor by
- * which the current max cache size is multiplied to produce a tentative new cache size.<p>The actual
- * cache size decrease will be clipped to satisfy the min_size specified in the general configuration,
- * and possibly max_decrement below.</p><p>The parameter must be be in the interval
- * [0.0, 1.0].</p><p>If you set it to 1.0, you will effectively disable cache size decreases. 0.9 is a
- * reasonable starting point.</p></td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>apply_max_decrement</code></td>
- * <td>IN: Boolean flag indicating whether an upper limit should be applied to the size of cache size
- * decreases.</td>
- * </tr>
- * <tr>
- * <td><em>size_t</em> <code>max_decrement</code></td>
- * <td>IN: Maximum number of bytes by which the maximum cache size can be decreased in any single step --
- * if applicable.</td>
- * </tr>
- * <tr>
- * <td><em>int</em> <code>epochs_before_eviction</code></td>
- * <td>IN: In the ageout based cache size reduction algorithms, this field contains the minimum number of
- * epochs an entry must remain unaccessed in cache before the cache size reduction algorithm tries to
- * evict it. 3 is a reasonable value.</td>
- * </tr>
- * <tr>
- * <td><em>hbool_t</em> <code>apply_empty_reserve</code></td>
- * <td>IN: Boolean flag indicating whether the ageout based decrement algorithms will maintain a empty
- * reserve when decreasing cache size.</td>
- * </tr>
- * <tr>
- * <td><em>double</em> <code>empty_reserve</code></td>
- * <td>IN: Empty reserve as a fraction of maximum cache size if applicable.<p>When so directed, the
- * ageout based algorithms will not decrease the maximum cache size unless the empty reserve can be
- * met.</p><p>The parameter must lie in the interval [0.0, 1.0]. 0.1 or 0.05 is a good place to
- * start.</p></td>
- * </tr>
- * </table>
- *
- * \par Parallel configuration fields
- * <table>
- * <tr>
- * <td><em>int</em> <code>dirty_bytes_threshold</code></td>
- * <td>IN: Threshold number of bytes of dirty metadata generation for triggering synchronizations of the
- * metadata caches serving the target file in the parallel case.<p>Synchronization occurs whenever the
- * number of bytes of dirty metadata created since the last synchronization exceeds this
- * limit.</p><p>This field only applies to the parallel case. While it is ignored elsewhere, it can
- * still draw a value out of bounds error.</p><p>It must be consistant across all caches on any given
- * file.</p><p>By default, this field is set to 256 KB. It shouldn't be more than half the current
- * maximum cache size times the minimum clean fraction.</p></td>
- * </tr>
- * </table>
+ * \snippet H5ACpublic.h H5AC_cache_config_t_snip
+ * \click4more
*
* \since 1.8.0
*
- * \todo Fix the MDC document reference!
*/
H5_DLL herr_t H5Fset_mdc_config(hid_t file_id, H5AC_cache_config_t *config_ptr);
/**
@@ -1495,13 +1103,12 @@ H5_DLL herr_t H5Fget_mdc_size(hid_t file_id, size_t *max_size_ptr, size_t *min_c
* is enabled. However, the call should be useful if you choose to control metadata cache size from your
* program.
*
- * See "Metadata Caching in HDF5" for details about the metadata cache and the adaptive cache resizing
+ * See \ref_mdc_in_hdf5 for details about the metadata cache and the adaptive cache resizing
* algorithms. If you have not read, understood, and thought about the material covered in that
* documentation,
* you should not be using this API call.
* \endparblock
*
- * \todo Fix the MDC document reference!
*/
H5_DLL herr_t H5Freset_mdc_hit_rate_stats(hid_t file_id);
/**
@@ -1797,6 +1404,9 @@ H5_DLL herr_t H5Fclear_elink_file_cache(hid_t file_id);
* For the parameters \p low and \p high, see the description for
* H5Pset_libver_bounds().
*
+ * \par Example
+ * \snippet H5F_examples.c libver_bounds
+ *
* \since 1.10.2
*
*/
@@ -1835,7 +1445,7 @@ H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t
* list, and H5Fget_mdc_logging_status() will return the current state of
* the logging flags.
*
- * The log format is described in the \Emph{Metadata Cache Logging} document.
+ * The log format is described in the \ref_mdc_logging document.
*
* \note Logging can only be started or stopped if metadata cache logging was enabled
* via H5Pset_mdc_log_options().\n
@@ -1849,8 +1459,6 @@ H5_DLL herr_t H5Fset_libver_bounds(hid_t file_id, H5F_libver_t low, H5F_libver_t
*
* \since 1.10.0
*
- * \todo Fix the document reference!
- *
*/
H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id);
/**
@@ -1887,7 +1495,7 @@ H5_DLL herr_t H5Fstart_mdc_logging(hid_t file_id);
* list, and H5Fget_mdc_logging_status() will return the current state of
* the logging flags.
*
- * The log format is described in the \Emph{Metadata Cache Logging} document.
+ * The log format is described in the \ref_mdc_logging document.
*
* \note Logging can only be started or stopped if metadata cache logging was enabled
* via H5Pset_mdc_log_options().\n
@@ -1933,7 +1541,7 @@ H5_DLL herr_t H5Fstop_mdc_logging(hid_t file_id);
* list, and H5Fget_mdc_logging_status() will return the current state of
* the logging flags.
*
- * The log format is described in the \Emph{Metadata Cache Logging} document.
+ * The log format is described in the \ref_mdc_logging document.
*
* \note Unlike H5Fstart_mdc_logging() and H5Fstop_mdc_logging(), this function can
* be called on any open file identifier.
@@ -1944,7 +1552,7 @@ H5_DLL herr_t H5Fget_mdc_logging_status(hid_t file_id, hbool_t *is_enabled, hboo
/**
* \ingroup SWMR
*
- * \todo Finish this!
+ * \todo UFO?
*/
H5_DLL herr_t H5Fformat_convert(hid_t fid);
/**
@@ -1998,7 +1606,7 @@ H5_DLL herr_t H5Fget_page_buffering_stats(hid_t file_id, unsigned accesses[2], u
* \brief Obtains information about a cache image if it exists
*
* \file_id
- * \param[out] image_addr Offset of the cache image if it exists, or #HADDR_UNDEF if it does not
+ * \param[out] image_addr Offset of the cache image if it exists, or \c HADDR_UNDEF if it does not
* \param[out] image_size Length of the cache image if it exists, or 0 if it does not
* \returns \herr_t
*
@@ -2139,11 +1747,10 @@ H5_DLL herr_t H5Fwait(hid_t file_id);
* the desired behavior.
* \endparblock
*
- * \see Enabling a Strict Consistency Semantics Model in Parallel HDF5
+ * \see \ref_cons_semantics
*
* \since 1.8.9
*
- * \todo Fix the reference!
*/
H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag);
/**
@@ -2163,11 +1770,10 @@ H5_DLL herr_t H5Fset_mpi_atomicity(hid_t file_id, hbool_t flag);
* Upon successful return, \p flag will be set to \c 1 if file access is set
* to atomic mode and \c 0 if file access is set to nonatomic mode.
*
- * \see Enabling a Strict Consistency Semantics Model in Parallel HDF5
+ * \see \ref_cons_semantics
*
* \since 1.8.9
*
- * \todo Fix the reference!
*/
H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
#endif /* H5_HAVE_PARALLEL */
@@ -2199,14 +1805,14 @@ H5_DLL herr_t H5Fget_mpi_atomicity(hid_t file_id, hbool_t *flag);
#ifndef H5_NO_DEPRECATED_SYMBOLS
/* Macros */
-#define H5F_ACC_DEBUG (H5CHECK H5OPEN 0x0000u) /*print debug info (deprecated)*/
+#define H5F_ACC_DEBUG (H5CHECK H5OPEN 0x0000u) /**< Print debug info \deprecated In which version? */
/* Typedefs */
/**
* Current "global" information about file
*/
-//! [H5F_info1_t_snip]
+//! <!-- [H5F_info1_t_snip] -->
typedef struct H5F_info1_t {
hsize_t super_ext_size; /**< Superblock extension size */
struct {
@@ -2214,7 +1820,7 @@ typedef struct H5F_info1_t {
H5_ih_info_t msgs_info; /**< Shared object header message index & heap size */
} sohm;
} H5F_info1_t;
-//! [H5F_info1_t_snip]
+//! <!-- [H5F_info1_t_snip] -->
/* Function prototypes */
/**
@@ -2252,7 +1858,7 @@ typedef struct H5F_info1_t {
* header indexes. Each index might be either a B-tree or
* a list.
*
- * \version 1.10.0 C function H5Fget_info() renamed to H5Fget_info1() and
+ * \version 1.10.0 Function H5Fget_info() renamed to H5Fget_info1() and
* deprecated in this release.
*
* \since 1.8.0