Skip to content

Commit

Permalink
Fix dead links cont. (HDFGroup#4349)
Browse files Browse the repository at this point in the history
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
bmribler authored and qkoziol committed Apr 9, 2024
1 parent a5b3a2f commit cac7429
Show file tree
Hide file tree
Showing 5 changed files with 23 additions and 5 deletions.
2 changes: 1 addition & 1 deletion doxygen/aliases
Original file line number Diff line number Diff line change
Expand Up @@ -243,7 +243,7 @@ ALIASES += ref_mdc_in_hdf5="<a href=\"https://portal.hdfgroup.org/display/HDF5/M
ALIASES += ref_mdc_logging="<a href=\"https://portal.hdfgroup.org/display/HDF5/H5F_START_MDC_LOGGING\">Metadata Cache Logging</a>"
ALIASES += ref_news_112="<a href=\"https://portal.hdfgroup.org/documentation/hdf5-docs/release_specifics/new_features_1_12.html\">New Features in HDF5 Release 1.12</a>"
ALIASES += ref_h5ocopy="<a href=\"https://portal.hdfgroup.org/display/HDF5/Copying+Committed+Datatypes+with+H5Ocopy\">Copying Committed Datatypes with H5Ocopy()</a>"
ALIASES += ref_sencode_fmt_change="<a href=\"https://portal.hdfgroup.org/pages/viewpage.action?pageId=58100093&preview=/58100093/58100094/encode_format_RFC.pdf\">RFC H5Secnode() / H5Sdecode() Format Change</a>"
ALIASES += ref_sencode_fmt_change="<a href=\"https://docs.hdfgroup.org/hdf5/rfc/H5Sencode_format.docx.pdf">RFC H5Secnode() / H5Sdecode() Format Change</a>"
ALIASES += ref_vlen_strings="\Emph{Creating variable-length string datatypes}"
ALIASES += ref_vol_doc="VOL documentation"

Expand Down
6 changes: 5 additions & 1 deletion doxygen/examples/intro_SWMR.html
Original file line number Diff line number Diff line change
Expand Up @@ -4,10 +4,13 @@

<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>
Expand Down Expand Up @@ -46,7 +49,8 @@ <h3 id="swmr-writer">SWMR Writer:</h3>
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);
<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>
Expand Down
6 changes: 4 additions & 2 deletions doxygen/examples/intro_VDS.html
Original file line number Diff line number Diff line change
Expand Up @@ -5,11 +5,11 @@
<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" ></center>
<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" ></center>
<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>
Expand Down Expand Up @@ -42,6 +42,7 @@
<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 &lt; 3; i++) {
Expand All @@ -67,4 +68,5 @@
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>
11 changes: 11 additions & 0 deletions doxygen/img/images_to_copy.dox
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>

*/
3 changes: 2 additions & 1 deletion src/H5Fmodule.h
Original file line number Diff line number Diff line change
Expand Up @@ -891,7 +891,8 @@
* @see <a href="https://portal.hdfgroup.org/documentation/hdf5-docs/advanced_topics/file_image_ops.html">
* HDF5 File Image Operations</a>
* section for information on more advanced usage of the Memory file driver, and
* @see <a href="http://www.hdfgroup.org/HDF5/doc/Advanced/ModifiedRegionWrites/ModifiedRegionWrites.pdf">
* @see <a
* href="https://docs.hdfgroup.org/archive/support/HDF5/doc/Advanced/ModifiedRegionWrites/ModifiedRegionWrites.pdf">
* Modified Region Writes</a>
* section for information on how to set write operations so that only modified regions are written
* to storage.
Expand Down

0 comments on commit cac7429

Please sign in to comment.