Introduction to SWMR

The Single-Writer / Multiple-Reader (SWMR) feature enables multiple processes to read an HDF5 file while it is being written to (by a single process) without using locks or requiring communication between processes.

All communication between processes must be performed via the HDF5 file. The HDF5 file under SWMR access must reside on a system that complies with POSIX write() semantics.

The basic engineering challenge for this to work was to ensure that the readers of an HDF5 file always see a coherent (though possibly not up to date) HDF5 file.

The issue is that when writing data there is information in the metadata cache in addition to the physical file on disk:

However, the readers can only see the state contained in the physical file:

The SWMR solution implements dependencies on when the metadata can be flushed to the file. This ensures that metadata cache flush operations occur in the proper order, so that there will never be internal file pointers in the physical file that point to invalid (unflushed) file addresses.

A beneficial side effect of using SWMR access is better fault tolerance. It is more difficult to corrupt a file when using SWMR.


SWMR User's Guide

HDF5 Library APIs


Design Documents

Programming Model

Please be aware that the SWMR feature requires that an HDF5 file be created with the latest file format. See H5P_SET_LIBVER_BOUNDS for more information.

To use SWMR follow the the general programming model for creating and accessing HDF5 files and objects along with the steps described below.

SWMR Writer:

The SWMR writer either opens an existing file and objects or creates them as follows.

Open an existing file:

Create a new file:

Example Code:

Create the file using the latest file format property:

   fapl = H5Pcreate (H5P_FILE_ACCESS); 
   status = H5Pset_libver_bounds (fapl, H5F_LIBVER_LATEST, H5F_LIBVER_LATEST); 
   fid = H5Fcreate (filename, H5F_ACC_TRUNC, H5P_DEFAULT, fapl); 

[Create objects (files, datasets, ...). Close any attributes and named datatype objects. Groups and datasets may remain open before starting SWMR access to them.]

Start SWMR access to the file:

   status = H5Fstart_swmr_write (fid);  

Reopen the datasets and start writing, periodically flushing data:

   status = H5Dwrite (dset_id, ...);
   status = H5Dflush (dset_id); 

SWMR Reader:

The SWMR reader must continually poll for new data:


Example Code:

Open the file using the SWMR read flag:

   fid = H5Fopen (filename, H5F_ACC_RDONLY | H5F_ACC_SWMR_READ, H5P_DEFAULT);

Open the dataset and then repeatedly poll the dataset, by getting the dimensions, reading new data, and refreshing:

   dset_id = H5Dopen (...);
   space_id = H5Dget_space (...);
   while (...) { 
      status = H5Dread (dset_id, ...);
      status = H5Drefresh (dset_id);
      space_id = H5Dget_space (...);

Limitations and Scope

An HDF5 file under SWMR access must reside on a system that complies with POSIX write() semantics. It is also limited in scope as follows:

The writer process is only allowed to modify raw data of existing datasets by;

The following operations are not allowed (and the corresponding HDF5 files will fail):

Tools for Working with SWMR

Two new tools, h5watch and h5clear, are available for use with SWMR. The other HDF5 utilities have also been modified to recognize SWMR:

Programming Example

A good example of using SWMR is included with the HDF5 tests in the source code. You can run it while reading the file it creates. If you then interrupt the application and reader and look at the resulting file, you will see that the file is still valid. Follow these steps: