Last modified: 18 April 2012
Name: H5Fset_mpi_atomicity
Signature:
  herr_t `H5Fset_mpi_atomicity`( hid_t `file_id`, hbool_t `flag` )

Purpose:
  Sets the MPI atomicity mode.

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.

Description:
  `H5Fset_mpi_atomicity` sets MPI consistency semantics for data access to the file, `file_id`.

  If `flag` is set to `TRUE`, all file access operations will appear atomic, guaranteeing sequential consistency. If `flag` is set to `FALSE`, 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 (`--enable-parallel`). It is useful only when used with the `H5FD_MPIO` driver (see `H5Pset_fapl_mpio`).

  Limitations:
  `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 `TRUE` 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.

Parameters:

  hid_t `file_id`, |  | IN: HDF5 file identifier
  hbool_t `flag` |  | IN: Logical flag for atomicity setting Valid values are: `TRUE` Sets MPI file access to atomic mode. `FALSE` Sets MPI file access to nonatomic mode.

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

Fortran90 Interface: h5fset_mpi_atomicity_f

      SUBROUTINE h5fset_mpi_atomicity_f(file_id, flag, hdferr)
        IMPLICIT NONE
        INTEGER(HID_T), INTENT(IN) :: file_id    ! File identifier
        INTEGER(HBOOL_T), INTENT(IN) :: flag     ! Atomicity flag
        INTEGER, INTENT(OUT) :: hdferr           ! Error code
                                                 ! 0 on success; -1 on failure
      END SUBROUTINE h5fset_mpi_atomicity_f

See Also:
  Enabling a Strict Consistency Semantics Model in Parallel HDF5

  `H5Fget_mpi_atomicity`

History:

  Release | Change
  1.8.9 | C function and Fortran subroutine introduced in this release.