From 9182ac35a75bdc1ddb8b948feb761740e41182de Mon Sep 17 00:00:00 2001
From: Allen Byrne <50328838+byrnHDF@users.noreply.github.com>
Date: Mon, 11 Sep 2023 07:48:13 -0500
Subject: [PATCH] Add missing row for the ROS3 VFD in table #3415 (#3517)
---
doxygen/examples/tables/fileDriverLists.dox | 144 ++++++++++++++------
doxygen/examples/tables/propertyLists.dox | 13 +-
src/H5Fmodule.h | 2 +-
src/H5Fpublic.h | 2 +-
src/H5Ppublic.h | 97 +------------
5 files changed, 120 insertions(+), 138 deletions(-)
diff --git a/doxygen/examples/tables/fileDriverLists.dox b/doxygen/examples/tables/fileDriverLists.dox
index 125df635da3..b1f873f063d 100644
--- a/doxygen/examples/tables/fileDriverLists.dox
+++ b/doxygen/examples/tables/fileDriverLists.dox
@@ -8,32 +8,64 @@
Description |
+#H5FD_SEC2 |
+Serial I/O to file using Unix “section 2” functions. |
+
+
#H5FD_CORE |
Store in memory (optional backing store to disk file). |
+#H5FD_LOG |
+Store in logging file. |
+
+
#H5FD_FAMILY |
Store in a set of files. |
-#H5FD_LOG |
-Store in logging file. |
+#H5FD_MULTI |
+Store in multiple files. There are several options to control layout. |
+
+
+#H5FD_STDIO |
+Serial I/O to file using Unix “stdio” functions. |
+
+
+#H5FD_SPLITTER |
+Relays VFD calls to one VFD, and write calls to another VFD. Maintains two files. |
#H5FD_MPIO |
Store using MPI/IO. |
-#H5FD_MULTI |
-Store in multiple files. There are several options to control layout. |
+#H5FD_DIRECT |
+Forces data writes to the file directly without using the system kernel buffer. |
-#H5FD_SEC2 |
-Serial I/O to file using Unix “section 2” functions. |
+#H5FD_MIRROR |
+Serial I/O to file using Unix “stdio” functions. |
-#H5FD_STDIO |
-Serial I/O to file using Unix “stdio” functions. |
+#H5FD_HDFS |
+Read-Only access to Hadoop Distributed File System (HDFS). |
+
+
+#H5FD_ROS3 |
+Read-Only access to Amazon's S3 service. |
+
+
+#H5FD_SUBFILING |
+Derived from other "stacked" VFDs such as the splitter, mirror, and family VFDs. |
+
+
+#H5FD_IOC |
+Relays VFD calls to one VFD, and write calls to another VFD. Maintains two files. |
+
+
+#H5FD_ONION |
+Provide in-file provenance and revision/version control. |
//! [file_driver_table]
@@ -57,33 +89,6 @@ the default file driver for all systems.
#H5Pset_fapl_sec2 |
-Direct |
-#H5FD_DIRECT |
-This is the #H5FD_SEC2 driver except data is written to or read from the file
-synchronously without being cached by the system. |
-#H5Pset_fapl_direct |
-
-
-Log |
-#H5FD_LOG |
-This is the #H5FD_SEC2 driver with logging capabilities. |
-#H5Pset_fapl_log |
-
-
-Windows |
-#H5FD_WINDOWS |
-This driver was modified in HDF5-1.8.8 to be a wrapper of the POSIX driver,
-#H5FD_SEC2. This change should not affect user applications. |
-#H5Pset_fapl_windows |
-
-
-STDIO |
-#H5FD_STDIO |
-This driver uses functions from the standard C stdio.h to perform I/O
-to a single, permanent file on local disk with additional system buffering. |
-#H5Pset_fapl_stdio |
-
-
Memory |
#H5FD_CORE |
With this driver, an application can work with a file in memory for faster reads and
@@ -92,6 +97,12 @@ version of the file can be written back to disk or abandoned. |
#H5Pset_fapl_core |
+Log |
+#H5FD_LOG |
+This is the #H5FD_SEC2 driver with logging capabilities. |
+#H5Pset_fapl_log |
+
+
Family |
#H5FD_FAMILY |
With this driver, the HDF5 file's address space is partitioned into pieces and sent to
@@ -105,14 +116,21 @@ systems that do not support files larger than 2 gigabytes. |
With this driver, data can be stored in multiple files according to the type of the data.
I/O might work better if data is stored in separate files based on the type of data. The Split
driver is a special case of this driver. |
-#H5Pset_fapl_multi |
+#H5Pset_fapl_multi / #H5Pset_fapl_split |
+
+
+STDIO |
+#H5FD_STDIO |
+This driver uses functions from the standard C stdio.h to perform I/O
+to a single, permanent file on local disk with additional system buffering. |
+#H5Pset_fapl_stdio |
Split |
-H5FD_SPLIT |
+#H5FD_SPLITTER |
This file driver splits a file into two parts. One part stores metadata, and the other part
stores raw data. This splitting a file into two parts is a limited case of the Multi driver. |
-#H5Pset_fapl_split |
+#H5Pset_fapl_splitter |
Parallel |
@@ -122,6 +140,56 @@ standard for both communication and file I/O.
#H5Pset_fapl_mpio |
+Direct |
+#H5FD_DIRECT |
+This is the #H5FD_SEC2 driver except data is written to or read from the file
+synchronously without being cached by the system. |
+#H5Pset_fapl_direct |
+
+
+Mirror |
+#H5FD_MIRROR |
+Serial I/O to file using Unix “stdio” functions. |
+#H5Pset_fapl_mirror |
+
+
+HDFS |
+#H5FD_HDFS |
+Read-Only access to Hadoop Distributed File System (HDFS). |
+#H5Pset_fapl_hdfs |
+
+
+ros3 |
+#H5FD_ROS3 |
+Read-Only access to Amazon's S3 service. |
+#H5Pset_fapl_ros3 |
+
+
+Subfiling |
+#H5FD_SUBFILING |
+Derived from other "stacked" VFDs such as the splitter, mirror, and family VFDs. |
+#H5Pset_fapl_subfiling |
+
+
+IOC |
+#H5FD_IOC |
+Relays VFD calls to one VFD, and write calls to another VFD. Maintains two files. |
+#H5Pset_fapl_ioc |
+
+
+Onion |
+#H5FD_ONION |
+Provide in-file provenance and revision/version control. |
+#H5Pset_fapl_onion |
+
+
+Windows |
+#H5FD_WINDOWS |
+This driver was modified in HDF5-1.8.8 to be a wrapper of the POSIX driver,
+#H5FD_SEC2. This change should not affect user applications. |
+#H5Pset_fapl_windows |
+
+
Parallel POSIX |
H5FD_MPIPOSIX |
This driver is no longer available |
diff --git a/doxygen/examples/tables/propertyLists.dox b/doxygen/examples/tables/propertyLists.dox
index 01570fa2dbe..2f74c03770f 100644
--- a/doxygen/examples/tables/propertyLists.dox
+++ b/doxygen/examples/tables/propertyLists.dox
@@ -351,7 +351,8 @@ larger than 2 gigabytes, or retrieves information regarding driver.
#H5Pset_fapl_log |
-Sets logging driver. |
+The logging driver is a clone of the standard SEC2 (#H5FD_SEC2) driver with additional
+facilities for logging metrics and activity to a file. |
#H5Pset_fapl_mirror/#H5Pget_fapl_mirror |
@@ -376,15 +377,23 @@ or retrieves information regarding driver.
Modifies/queries the file driver properties of the onion driver. |
+#H5Pset_fapl_ros3/#H5Pget_fapl_ros3 |
+Modifies/queries the file driver properties of the ros3 driver. |
+
+
#H5Pset_fapl_sec2 |
Sets driver for unbuffered permanent files or retrieves information regarding driver. |
#H5Pset_fapl_split |
-Sets driver for split files, a limited case of multiple files with one metadata file
+ | Sets driver for split files, a limited case of multi driver with one metadata file
and one raw data file. |
+#H5Pset_fapl_splitter/#H5Pget_fapl_splitter |
+Modifies/queries the file driver properties of the splitter driver. |
+
+
#H5Pset_fapl_stdio |
Sets driver for buffered permanent files. |
diff --git a/src/H5Fmodule.h b/src/H5Fmodule.h
index 3e3be07bbe3..8a3f8df9520 100644
--- a/src/H5Fmodule.h
+++ b/src/H5Fmodule.h
@@ -998,7 +998,7 @@
* Additional parameters may be added to these functions in the future.
*
* \subsubsection subsubsec_file_alternate_drivers_split The Split Driver
- * The Split driver, H5FD_SPLIT, is a limited case of the Multi driver where only two files are
+ * The Split driver is a limited case of the Multi driver where only two files are
* created. One file holds metadata, and the other file holds raw data.
* The function #H5Pset_fapl_split is used to manage Split file access properties. See the example
* below.
diff --git a/src/H5Fpublic.h b/src/H5Fpublic.h
index f800b4ce302..34a92ac5178 100644
--- a/src/H5Fpublic.h
+++ b/src/H5Fpublic.h
@@ -1730,7 +1730,7 @@ H5_DLL herr_t H5Fset_dset_no_attrs_hint(hid_t file_id, hbool_t minimize);
* pass the same values for \p file_id and \p flag.
*
* This function is available only when the HDF5 library is configured with parallel support
- * (\Code{--enable-parallel}). It is useful only when used with the #H5FD_MPIO driver
+ * (\Code{--enable-parallel | HDF5_ENABLE_PARALLEL}). It is useful only when used with the #H5FD_MPIO driver
* (see H5Pset_fapl_mpio()).
* \endparblock
*
diff --git a/src/H5Ppublic.h b/src/H5Ppublic.h
index 9a455c7ae1f..a58d97ffd22 100644
--- a/src/H5Ppublic.h
+++ b/src/H5Ppublic.h
@@ -3354,102 +3354,7 @@ H5_DLL herr_t H5Pget_core_write_tracking(hid_t fapl_id, hbool_t *is_enabled, siz
* Valid driver identifiers distributed with HDF5 are listed and
* described in the following table.
*
- *
- *
- * Driver Name |
- * Driver Identifier |
- * Description |
- * Related Function |
- *
- *
- * POSIX |
- * #H5FD_SEC2 |
- * This driver uses POSIX file-system functions like read and
- * write to perform I/O to a single, permanent file on local disk
- * with no system buffering. This driver is POSIX-compliant and
- * is the default file driver for all systems. |
- * H5Pset_fapl_sec2() |
- *
- *
- * Direct |
- * #H5FD_DIRECT |
- * This is the #H5FD_SEC2 driver, except data is written to or
- * read from the file synchronously without being cached by the
- * system. |
- * H5Pset_fapl_direct() |
- *
- *
- * Log |
- * #H5FD_LOG |
- * This is the #H5FD_SEC2 driver with logging capabilities. |
- * H5Pset_fapl_log() |
- *
- *
- * Windows |
- * #H5FD_WINDOWS |
- * This driver was modified in HDF5-1.8.8 to be a wrapper of the
- * POSIX driver, #H5FD_SEC2. This change should not affect user
- * applications. |
- * H5Pset_fapl_windows() |
- *
- *
- * STDIO |
- * #H5FD_STDIO |
- * This driver uses functions from the standard C stdio.h to
- * perform I/O to a single, permanent file on local disk with
- * additional system buffering. |
- * H5Pset_fapl_stdio() |
- *
- *
- * Memory |
- * #H5FD_CORE |
- * With this driver, an application can work with a file in
- * memory for faster reads and writes. File contents are kept in
- * memory until the file is closed. At closing, the memory
- * version of the file can be written back to disk or abandoned.
- * |
- * H5Pset_fapl_core() |
- *
- *
- * Family |
- * #H5FD_FAMILY |
- * With this driver, the HDF5 file's address space is partitioned
- * into pieces and sent to separate storage files using an
- * underlying driver of the user's choice. This driver is for
- * systems that do not support files larger than 2 gigabytes.
- * |
- * H5Pset_fapl_family() |
- *
- *
- * Multi |
- * #H5FD_MULTI |
- * With this driver, data can be stored in multiple files
- * according to the type of data. I/O might work better if
- * data is stored in separate files based on the type of data.
- * The Split driver is a special case of this driver. |
- * H5Pset_fapl_multi() |
- *
- *
- * Parallel |
- * #H5FD_MPIO |
- * This is the standard HDF5 file driver for parallel file
- * systems. This driver uses the MPI standard for both
- * communication and file I/O. |
- * H5Pset_fapl_mpio() |
- *
- *
- * Parallel POSIX |
- * H5FD_MPIPOSIX |
- * This driver is no longer available. |
- * |
- *
- *
- * Stream |
- * H5FD_STREAM |
- * This driver is no longer available. |
- * |
- *
- *
+ * \snippet{doc} tables/fileDriverLists.dox supported_file_driver_table
*
* This list does not include custom drivers that might be
* defined and registered by a user.