-
-
Notifications
You must be signed in to change notification settings - Fork 265
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Documentation updates from develop (#4361)
* Fix grammar and content in HDF5Examples (#4333) * Add VDS and SWMR to documentation (#4336) * Fix dead links cont. (#4349) Added img/images_to_copy.dox as a temporary solution because doxygen didn't copy the images used in the examples/*.html files - will investigate more. This was necessary for the links to intro_SWMR.html and intro_VDS.html.
- Loading branch information
Showing
16 changed files
with
225 additions
and
25 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| <html> | ||
| <head> | ||
| <title>Introduction to Single-Writer_Multiple-Reader (SWMR)</title> | ||
|
|
||
| <h2 id="introduction-to-swmr">Introduction to SWMR</h2> | ||
| <p>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.</p> | ||
| <p><img src=tutr-swmr1.png alt="tutr-swmr1.png" width=500> | ||
| <p>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.</p> | ||
| <p>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.</p> | ||
| <p>The issue is that when writing data there is information in the metadata cache in addition to the physical file on disk:</p> | ||
| <p><img src=tutr-swmr2.png alt="tutr-swmr2.png" width=500> | ||
| <p>However, the readers can only see the state contained in the physical file:</p> | ||
| <p><img src=tutr-swmr3.png alt="tutr-swmr3.png" width=500> | ||
| <p>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.</p> | ||
| <p>A beneficial side effect of using SWMR access is better fault tolerance. It is more difficult to corrupt a file when using SWMR.</p> | ||
| <h2 id="documentation">Documentation</h2> | ||
| <h3 id="swmr-users-guide"><a href="https://docs.hdfgroup.org/hdf5/tn/HDF5_SWMR_User_Guide.pdf">SWMR User's Guide</a></h3> | ||
| <h3 id="hdf5-library-apis">HDF5 Library APIs</h3> | ||
| <ul> | ||
| <li><a href="https://docs.hdfgroup.org/hdf5/develop/group___s_w_m_r.html#ga159be34fbe7e4a959589310ef0196dfe">H5F_START_SWMR_WRITE</a> — Enables SWMR writing mode for a file</li> | ||
| <li><a href="https://docs.hdfgroup.org/hdf5/develop/group___h5_d_o.html#ga316caac160af15192e0c78228667341e">H5DO_APPEND</a> — Appends data to a dataset along a specified dimension</li> | ||
| <li>H5P_SET_OBJECT_FLUSH_CB — Sets a callback function to invoke when an object flush occurs in the file</li> | ||
| <li>H5P_GET_OBJECT_FLUSH_CB — Retrieves the object flush property values from the file access property list</li> | ||
| <li>H5O_DISABLE_MDC_FLUSHES — Prevents metadata entries for an HDF5 object from being flushed from the metadata cache to storage</li> | ||
| <li>H5O_ENABLE_MDC_FLUSHES — Enables flushing of dirty metadata entries from a file’s metadata cache</li> | ||
| <li>H5O_ARE_MDC_FLUSHES_DISABLED — Determines if an HDF5 object has had flushes of metadata entries disabled</li> | ||
| </ul> | ||
| <h3 id="tools">Tools</h3> | ||
| <ul> | ||
| <li>h5watch — Outputs new records appended to a dataset as the dataset grows</li> | ||
| <li>h5format_convert — Converts the layout format version and chunked indexing types of datasets created with HDF5-1.10 so that applications built with HDF5-1.8 can access them</li> | ||
| <li>h5clear — Clears superblock status_flags field, removes metadata cache image, prints EOA and EOF, or sets EOA of a file</li> | ||
| </ul> | ||
| <h3 id="design-documents">Design Documents</h3> | ||
| <p>Error while fetching page properties report data:</p> | ||
| <h2 id="programming-model">Programming Model</h2> | ||
| <p>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.</p> | ||
| <p>To use SWMR follow the the general programming model for creating and accessing HDF5 files and objects along with the steps described below.</p> | ||
| <h3 id="swmr-writer">SWMR Writer:</h3> | ||
| <p>The SWMR writer either opens an existing file and objects or creates them as follows.</p> | ||
| <p>Open an existing file:</p> | ||
| <p>Call H5Fopen using the H5F_ACC_SWMR_WRITE flag. | ||
| Begin writing datasets. | ||
| Periodically flush data. | ||
| Create a new file:</p> | ||
| <p>Call H5Fcreate using the latest file format. | ||
| Create groups, datasets and attributes, and then close the attributes. | ||
| Call H5F_START_SWMR_WRITE to start SWMR access to the file. | ||
| Periodically flush data.</p> | ||
| <h4 id="example-code">Example Code:</h4> | ||
| <p>Create the file using the latest file format property:</p> | ||
| <p> | ||
| 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.]</p> | ||
| <p>Start SWMR access to the file:</p> | ||
| <p> status = H5Fstart_swmr_write (fid); | ||
| Reopen the datasets and start writing, periodically flushing data:</p> | ||
| <p> status = H5Dwrite (dset_id, ...); | ||
| status = H5Dflush (dset_id);</p> | ||
| <h3 id="swmr-reader">SWMR Reader:</h3> | ||
| <p>The SWMR reader must continually poll for new data:</p> | ||
| <p>Call H5Fopen using the H5F_ACC_SWMR_READ flag. | ||
| Poll, checking the size of the dataset to see if there is new data available for reading. | ||
| Read new data, if any.</p> | ||
| <h4 id="example-code-1">Example Code:</h4> | ||
| <p>Open the file using the SWMR read flag:</p> | ||
| <p> 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:</p> | ||
| <p> dset_id = H5Dopen (...); | ||
| space_id = H5Dget_space (...); | ||
| while (...) { | ||
| status = H5Dread (dset_id, ...); | ||
| status = H5Drefresh (dset_id); | ||
| space_id = H5Dget_space (...); | ||
| }</p> | ||
| <h2 id="limitations-and-scope">Limitations and Scope</h2> | ||
| <p>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:</p> | ||
| <p>The writer process is only allowed to modify raw data of existing datasets by;</p> | ||
| <p>Appending data along any unlimited dimension. | ||
| Modifying existing data | ||
| The following operations are not allowed (and the corresponding HDF5 files will fail):</p> | ||
| <p>The writer cannot add new objects to the file. | ||
| The writer cannot delete objects in the file. | ||
| The writer cannot modify or append data with variable length, string or region reference datatypes. | ||
| File space recycling is not allowed. As a result the size of a file modified by a SWMR writer may be larger than a file modified by a non-SWMR writer.</p> | ||
| <h2 id="tools-for-working-with-swmr">Tools for Working with SWMR</h2> | ||
| <p>Two new tools, h5watch and h5clear, are available for use with SWMR. The other HDF5 utilities have also been modified to recognize SWMR:</p> | ||
| <p>The h5watch tool allows a user to monitor the growth of a dataset. | ||
| The h5clear tool clears the status flags in the superblock of an HDF5 file. | ||
| The rest of the HDF5 tools will exit gracefully but not work with SWMR otherwise.</p> | ||
| <h2 id="programming-example">Programming Example</h2> | ||
| <p>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:</p> | ||
| <p>Download the HDF5-1.10 source code to a local directory on a filesystem (that complies with POSIX write() semantics). Build the software. No special configuration options are needed to use SWMR.</p> | ||
| <p>Invoke two command terminal windows. In one window go into the bin/ directory of the built binaries. In the other window go into the test/ directory of the HDF5-1.10 source code that was just built.</p> | ||
| <p>In the window in the test/ directory compile and run use_append_chunk.c. The example writes a three dimensional dataset by planes (with chunks of size 1 x 256 x 256).</p> | ||
| <p>In the other window (in the bin/ directory) run h5watch on the file created by use_append_chunk.c (use_append_chunk.h5). It should be run while use_append_chunk is executing and you will see valid data displayed with h5watch.</p> | ||
| <p>Interrupt use_append_chunk while it is running, and stop h5watch.</p> | ||
| <p>Use h5clear to clear the status flags in the superblock of the HDF5 file (use_append_chunk.h5).</p> | ||
| <p>View the file with h5dump. You will see that it is a valid file even though the application did not close properly. It will contain data up to the point that it was interrupted.</p> | ||
|
|
||
| </body></html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,72 @@ | ||
| <html> | ||
| <head> | ||
| <title>Introduction to the Virtual Dataset - VDS</title> | ||
|
|
||
| <p>The HDF5 Virtual Dataset (VDS) feature enables users to access data in a collection of HDF5 files as a single HDF5 dataset and to use the HDF5 APIs to work with that dataset.</p> | ||
| <p>For example, your data may be collected into four files:</p> | ||
|
|
||
| <p><img src="tutrvds-multimgs.png" alt="tutrvds-multimgs.png" width=750></center> | ||
|
|
||
| <p>You can map the datasets in the four files into a single VDS that can be accessed just like any other dataset:</p> | ||
|
|
||
| <p><img src="tutrvds-snglimg.png" alt="tutrvds-snglimg.png" width=500></center> | ||
|
|
||
| <p>The mapping between a VDS and the HDF5 source datasets is persistent and transparent to an application. If a source file is missing the fill value will be displayed.</p> | ||
| <p>See the Virtual (VDS) Documentation for complete details regarding the VDS feature.</p> | ||
| <p>The VDS feature was implemented using hyperslab selection (H5S_SELECT_HYPERSLAB). See the tutorial on Reading From or Writing to a Subset of a Dataset for more information on selecting hyperslabs.</p> | ||
| <p>Programming Model | ||
| To create a Virtual Dataset you simply follow the HDF5 programming model and add a few additional API calls to map the source code datasets to the VDS.</p> | ||
| <p>Following are the steps for creating a Virtual Dataset:</p> | ||
| <p>Create the source datasets that will comprise the VDS | ||
| Create the VDS: ‐ Define a datatype and dataspace (can be unlimited) | ||
| ‐ Define the dataset creation property list (including fill value) | ||
| ‐ (Repeat for each source dataset) Map elements from the source dataset to elements of the VDS: | ||
| Select elements in the source dataset (source selection) | ||
| Select elements in the virtual dataset (destination selection) | ||
| Map destination selections to source selections (see Functions for Working with a VDS)</p> | ||
| <p>‐ Call H5Dcreate using the properties defined above | ||
| Access the VDS as a regular HDF5 dataset | ||
| Close the VDS when finished</p> | ||
| <p>Functions for Working with a VDS | ||
| The H5P_SET_VIRTUAL API sets the mapping between virtual and source datasets. This is a dataset creation property list. Using this API will change the layout of the dataset to H5D_VIRTUAL. As with specifying any dataset creation property list, an instance of the property list is created, modified, passed into the dataset creation call and then closed:</p> | ||
| <p> dcpl = H5Pcreate (H5P_DATASET_CREATE);</p> | ||
| <p> src_space = H5screate_simple ... | ||
| status = H5Sselect_hyperslab (space, ... | ||
| status = H5Pset_virtual (dcpl, space, SRC_FILE[i], SRC_DATASET[i], src_space);</p> | ||
| <p> dset = H5Dcreate2 (file, DATASET, H5T_NATIVE_INT, space, H5P_DEFAULT, dcpl, H5P_DEFAULT);</p> | ||
| <p> status = H5Pclose (dcpl); | ||
| There are several other APIs introduced with Virtual Datasets, including query functions. For details see the complete list of HDF5 library APIs that support Virtual Datasets</p> | ||
| <p>Limitations | ||
| This feature requires HDF5-1.10. | ||
| The number of source datasets is unlimited. However, there is a limit on the size of each source dataset.</p> | ||
| <p>Programming Examples | ||
| Example 1 | ||
| This example creates three HDF5 files, each with a one-dimensional dataset of 6 elements. The datasets in these files are the source datasets that are then used to create a 4 x 6 Virtual Dataset with a fill value of -1. The first three rows of the VDS are mapped to the data from the three source datasets as shown below:</p> | ||
| <p><img src="tutrvds-ex.png" alt="tutrvds-ex.png" width=500></p> | ||
| <p>In this example the three source datasets are mapped to the VDS with this code:</p> | ||
| <pre><code>src\_space = H5Screate\_simple (RANK1, dims, NULL); | ||
| for (i = 0; i < 3; i++) { | ||
| start[0] = (hsize\_t)i; | ||
| /* Select i-th row in the virtual dataset; selection in the source datasets is the same. */ | ||
| status = H5Sselect\_hyperslab (space, H5S\_SELECT\_SET, start, NULL, count, block); | ||
| status = H5Pset\_virtual (dcpl, space, SRC\_FILE[i], SRC\_DATASET[i], src\_space); | ||
| } | ||
| </code></pre> | ||
| <p>After the VDS is created and closed, it is reopened. The property list is then queried to determine the layout of the dataset and its mappings, and the data in the VDS is read and printed.</p> | ||
| <p>This example is in the HDF5 source code and can be obtained from here:</p> | ||
| <p>C Example</p> | ||
| <p>For details on compiling an HDF5 application: [ Compiling HDF5 Applications ]</p> | ||
| <p>Example 2 | ||
| This example shows how to use a C-style printf statement for specifying multiple source datasets as one virtual dataset. Only one mapping is required. In other words only one H5P_SET_VIRTUAL call is needed to map multiple datasets. It creates a 2-dimensional unlimited VDS. Then it re-opens the file, makes queries, and reads the virtual dataset.</p> | ||
| <p>The source datasets are specified as A-0, A-1, A-2, and A-3. These are mapped to the virtual dataset with one call:</p> | ||
| <pre><code>status = H5Pset\_virtual (dcpl, vspace, SRCFILE, "/A-%b", src\_space); | ||
| </code></pre> | ||
| <p>The %b indicates that the block count of the selection in the dimension should be used.</p> | ||
| <p>C Example</p> | ||
| <p>For details on compiling an HDF5 application: [ Compiling HDF5 Applications ]</p> | ||
| <p>Using h5dump with a VDS | ||
| The h5dump utility can be used to view a VDS. The h5dump output for a VDS looks exactly like that for any other dataset. If h5dump cannot find a source dataset then the fill value will be displayed.</p> | ||
| <p>You can determine that a dataset is a VDS by looking at its properties with h5dump -p. It will display each source dataset mapping, beginning with Mapping 0. Below is an excerpt of the output of h5dump -p on the vds.h5 file created in Example 1.You can see that the entire source file a.h5 is mapped to the first row of the /VDS dataset:</p> | ||
|
|
||
| <p><img src="tutrvds-map.png" alt="tutrvds-map.png" width=650></p> | ||
| </body></html> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| /** \page HTML_IMGS Images for html files | ||
|
|
||
| <img src=tutrvds-map.png> | ||
| <img src=tutrvds-ex.png> | ||
| <img src=tutr-swmr3.png> | ||
| <img src=tutr-swmr2.png> | ||
| <img src=tutr-swmr1.png> | ||
| <img src=tutrvds-snglimg.png> | ||
| <img src=tutrvds-multimgs.png> | ||
|
|
||
| */ |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.