Last modified: 18 February 2014
Name: H5Fstart_swmr_write
Signature:
  `herr_t H5Fstart_swmr_write(hid_t file_id)`
Purpose:
  Enables SWMR writing mode for a file.
Description:
  `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.

Parameters:

  `hid_t file_id` | IN: A file identifier.

Returns:
  Returns a non-negative value if successful; otherwise returns a negative value.
Example Usage:
  The example below illustrates the usage of this routine to activate the SWMR writing mode for an opened file.

      /*
       *   The writer process
       */
      /* Create a copy of the file access property list */
      fapl_id = H5Pcreate(H5P_FILE_ACCESS);

      /* Set to use the latest library format */
      H5Pset_libver_bounds(fapl_id, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST);

      /* Create a file with the latest library format */
      file_id = H5Fcreate(filename, H5F_ACC_TRUNC, H5P_DEFAULT, fapl_id);
      :
      :
      :
      /* Perform operations that are not SWMR-safe. */
      :
      :
      :
      /* Start a concurrent SWMR reader process (see coding below) at this point
         will fail because the file is not marked as SWMR-safe */

      /* Enable SWMR writing mode */
      H5Fstart_swmr_write(file_id);

      /* Start a concurrent SWMR reader process (see coding below) at this point
         will succeed because the file is marked as SWMR-safe */

      /* Perform SWMR-safe operations */
      :
      :
      :
      /* Close the file */
      H5Fclose(file_id);

      /* Close the property list */
      H5Pclose(fapl_id);

      /*
       *   The SWMR reader process
       */
      read_file_id = H5Fopen(filename, H5F_ACC_RDONLY|H5F_ACC_SWMR_READ, fapl_id);

      /* Perform reading operations */
      :
      :
      :
      /* Close the file */
      H5Fclose(read_file_id);

Fortran Interface:
  None
See Also:

- H5DOappend
- H5Pset_append_flush
- H5Pget_append_flush
- H5Pset_object_flush_cb
- H5Pget_object_flush_cb

- H5Odisable_mdc_flushes
- H5Oenable_mdc_flushes
- H5Oare_mdc_flushes_disabled
- H5Fdisable_mdc_flushes
- H5Fenable_mdc_flushes
- H5Fare_mdc_flushes_disabled
- H5Fget_mdc_flush_disabled_obj_ids

- H5Dflush
- H5Drefresh
- H5Gflush
- H5Grefresh
- H5Oflush
- H5Orefresh
- H5Tflush
- H5Trefresh

History:

  Release | Change
  1.10.0 | C function introduced with this release.