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_id	File identifier
[out]	info	Struct 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;
    uint32_t *retries[H5F_NUM_METADATA_READ_RETRY_TYPES];
} H5F_retry_info_t;

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*
0	Object header (version 2)
1	Object header chunk (version 2)
2	B-tree header (version 2)
3	B-tree internal node (version 2)
4	B-tree leaf node (version 2)
5	Fractal heap header
6	Fractal heap direct block (optional checksum)
7	Fractal heap indirect block
8	Free-space header
9	Free-space sections
10	Shared object header message table
11	Shared message record list
12	Extensive array header
13	Extensive array index block
14	Extensive array super block
15	Extensive array data block
16	Extensive array data block page
17	Fixed array super block
18	Fixed array data block
19	Fixed array data block page
20	File'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_id

File 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