Please, help us to better serve our user community by answering the following short survey: https://www.hdfgroup.org/website-survey/
HDF5 1.14.5
API Reference
Loading...
Searching...
No Matches
Single Writer Multiple Readers

Detailed Description

Functions

herr_t H5Fget_metadata_read_retry_info (hid_t file_id, H5F_retry_info_t *info)
 Retrieves the collection of read retries for metadata entries with checksum.
 
herr_t H5Fstart_swmr_write (hid_t file_id)
 Retrieves free-space section information for a file.
 

Function Documentation

◆ H5Fget_metadata_read_retry_info()

herr_t H5Fget_metadata_read_retry_info ( hid_t  file_id,
H5F_retry_info_t info 
)

Retrieves the collection of read retries for metadata entries with checksum.

Parameters
[in]file_idFile identifier
[out]infoStruct containing the collection of read retries for metadata entries with checksum
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

Failure Modes:

  • When the input identifier is not a file identifier.
  • When the pointer to the output structure is NULL.
  • When the memory allocation for retries failed.

H5Fget_metadata_read_retry_info() retrieves information regarding the number of read retries for metadata entries with checksum for the file file_id. This information is reported in the H5F_retry_info_t struct defined in H5Fpublic.h as follows:

#define H5F_NUM_METADATA_READ_RETRY_TYPES 21
typedef struct H5F_retry_info_t {
unsigned nbins;
#define H5F_NUM_METADATA_READ_RETRY_TYPES
Definition H5Fpublic.h:227
Definition H5Fpublic.h:233
uint32_t * retries[21]
Definition H5Fpublic.h:235
unsigned nbins
Definition H5Fpublic.h:234

nbins is the number of bins for each retries[i] of metadata entry i. It is calculated based on the current number of read attempts used in the library and logarithmic base 10.

If read retries are incurred for a metadata entry i, the library will allocate memory for retries[i] (nbins * sizeof(uint32_t) and store the collection of retries there. If there are no retries for a metadata entry i, retries[i] will be NULL. After a call to this routine, users should free each retries[i] that is non-NULL, otherwise resource leak will occur.

For the library default read attempts of 100 for SWMR access, nbins will be 2 as depicted below:

  • retries[i][0] is the number of 1 to 9 read retries.
  • retries[i][1] is the number of 10 to 99 read retries. For the library default read attempts of 1 for non-SWMR access, nbins will be 0 and each retries[i] will be NULL.

The following table lists the 21 metadata entries of retries[]:

Index for retries[] Metadata entries*
0Object header (version 2)
1Object header chunk (version 2)
2B-tree header (version 2)
3B-tree internal node (version 2)
4B-tree leaf node (version 2)
5Fractal heap header
6Fractal heap direct block (optional checksum)
7Fractal heap indirect block
8Free-space header
9Free-space sections
10Shared object header message table
11Shared message record list
12Extensive array header
13Extensive array index block
14Extensive array super block
15Extensive array data block
16Extensive array data block page
17Fixed array super block
18Fixed array data block
19Fixed array data block page
20File's superblock (version 2)
* All entries are of version 0 (zero) unless indicated otherwise.
Note
On a system that is not atomic, the library might possibly read inconsistent metadata with checksum when performing single-writer/multiple-reader (SWMR) operations for an HDF5 file. Upon encountering such situations, the library will try reading the metadata again for a set number of times to attempt to obtain consistent data. The maximum number of read attempts used by the library will be either the value set via H5Pset_metadata_read_attempts() or the library default value when a value is not set.
When the current number of metadata read attempts used in the library is unable to remedy the reading of inconsistent metadata on a system, the user can assess the information obtained via this routine to derive a different maximum value. The information can also be helpful for debugging purposes to identify potential issues with metadata flush dependencies and SWMR implementation in general.
Since
1.10.0

◆ H5Fstart_swmr_write()

herr_t H5Fstart_swmr_write ( hid_t  file_id)

Retrieves free-space section information for a file.

Parameters
[in]file_idFile identifier
Returns
Returns a non-negative value if successful; otherwise, returns a negative value.

H5Fstart_swmr_write() will activate SWMR writing mode for a file associated with file_id. This routine will prepare and ensure the file is safe for SWMR writing as follows:

  • Check that the file is opened with write access (H5F_ACC_RDWR).
  • Check that the file is opened with the latest library format to ensure data structures with check-summed metadata are used.
  • Check that the file is not already marked in SWMR writing mode.
  • Enable reading retries for check-summed metadata to remedy possible checksum failures from reading inconsistent metadata on a system that is not atomic.
  • Turn off usage of the library's accumulator to avoid possible ordering problem on a system that is not atomic.
  • 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 the current implementation, groups and datasets can remain open when activating SWMR writing mode, but not committed datatypes. Attributes attached to objects cannot remain open either.

Since
1.10.0