From fbeddf2c9c6141f4ed6e5638711ce8aa2b58b7c1 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 NameDriver IdentifierDescriptionRelated Function
POSIX#H5FD_SEC2This 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_DIRECTThis 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_LOGThis is the #H5FD_SEC2 driver with logging capabilities.H5Pset_fapl_log()
Windows#H5FD_WINDOWSThis 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_STDIOThis 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_COREWith 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_FAMILYWith 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_MULTIWith 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_MPIOThis 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 POSIXH5FD_MPIPOSIXThis driver is no longer available.
StreamH5FD_STREAMThis 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.