Help us improve by taking our short survey: https://www.hdfgroup.org/website-survey/

| HDF5 Last Updated on 2026-03-23 The HDF5 Field Guide

Loading...
Searching...
No Matches
Parallel
Files (H5F)

## Detailed Description

## Functions
herr_t | H5Fget_mpi_atomicity (hid_t file_id, bool *flag)
| Retrieves the atomicity mode in use.
herr_t | H5Fset_mpi_atomicity (hid_t file_id, bool flag)
| Sets the MPI atomicity mode.

## Function Documentation

## ◆ H5Fget_mpi_atomicity()

herr_t H5Fget_mpi_atomicity | ( | hid_t | file_id,
|  | bool * | flag )

Retrieves the atomicity mode in use.

Parameters

  [in] | file_id | File identifier
  [out] | flag | Logical flag for atomicity setting. Valid values are: 1 – MPI file access is set to atomic mode. 0 – MPI file access is set to nonatomic mode.

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

H5Fget_mpi_atomicity() retrieves the current consistency semantics mode for data access for the file `file_id`.

Upon successful return, `flag` will be set to `1` if file access is set to atomic mode and `0` if file access is set to nonatomic mode.

See also
  Enabling a Strict Consistency Semantics Model in Parallel HDF5

Since
  1.8.9

## ◆ H5Fset_mpi_atomicity()

herr_t H5Fset_mpi_atomicity | ( | hid_t | file_id,
|  | bool | flag )

Sets the MPI atomicity mode.

Parameters

  [in] | file_id | File identifier
  [in] | flag | Logical flag for atomicity setting. Valid values are: `1` – Sets MPI file access to atomic mode. `0` – Sets MPI file access to nonatomic mode.

Returns
  Returns a non-negative value if successful; otherwise, returns a negative value.

Motivation
  H5Fset_mpi_atomicity() is applicable only in parallel environments using MPI I/O. The function is one of the tools used to ensure sequential consistency. This means that a set of operations will behave as though they were performed in a serial order consistent with the program order.

H5Fset_mpi_atomicity() sets MPI consistency semantics for data access to the file, `file_id`.

If `flag` is set to `1`, all file access operations will appear atomic, guaranteeing sequential consistency. If `flag` is set to `0`, enforcement of atomic file access will be turned off.

H5Fset_mpi_atomicity() is a collective function and all participating processes must pass the same values for `file_id` and `flag`.

This function is available only when the HDF5 library is configured with parallel support (HDF5_ENABLE_PARALLEL). It is useful only when used with the H5FD_MPIO driver (see H5Pset_fapl_mpio()).

Attention

  H5Fset_mpi_atomicity() calls MPI_File_set_atomicity underneath and is not supported if the execution platform does not support MPI_File_set_atomicity. When it is supported and used, the performance of data access operations may drop significantly.

  In certain scenarios, even when MPI_File_set_atomicity is supported, setting atomicity with H5Fset_mpi_atomicity() and `flag` set to 1 does not always yield strictly atomic updates. For example, some H5Dwrite() calls translate to multiple MPI_File_write_at calls. This happens in all cases where the high-level file access routine translates to multiple lower level file access routines. The following scenarios will raise this issue:

  - Non-contiguous file access using independent I/O
  - Partial collective I/O using chunked access
  - Collective I/O using filters or when data conversion is required

  This issue arises because MPI atomicity is a matter of MPI file access operations rather than HDF5 access operations. But the user is normally seeking atomicity at the HDF5 level. To accomplish this, the application must set a barrier after a write, H5Dwrite(), but before the next read, H5Dread(), in addition to calling H5Fset_mpi_atomicity().The barrier will guarantee that all underlying write operations execute atomically before the read operations starts. This ensures additional ordering semantics and will normally produce the desired behavior.

See also
  Enabling a Strict Consistency Semantics Model in Parallel HDF5

Since
  1.8.9