SpECTRE
v2024.12.16
|
Opens an HDF5 file for access and allows manipulation of data. More...
#include <File.hpp>
Public Member Functions | |
H5File (std::string file_name, bool append_to_file=false, const std::string &input_source=""s, bool use_file_locking=false) | |
const std::string & | name () const |
Get name of the H5 file. | |
const std::vector< std::string > | groups () const |
Get a std::vector of the names of all immediate subgroups of the file. | |
template<typename ObjectType = void> | |
const std::vector< std::string > | all_files (const std::string &group_name) const |
Return a vector of all filenames in the H5 file. More... | |
std::string | input_source () const |
Get the InputSource.yaml string embedded in the file. | |
template<typename ObjectType , typename... Args> | |
ObjectType & | insert (const std::string &path, Args &&... args) |
Insert an object into an H5 file. More... | |
template<typename ObjectType , typename... Args> | |
ObjectType & | try_insert (const std::string &path, Args &&... args) |
Inserts an object like insert if it does not exist, returns the object if it does. | |
void | close_current_object () const |
void | close () const |
template<typename ObjectType > | |
bool | exists (const std::string &path) const |
H5File (const H5File &)=delete | |
It does not make sense to copy an object referring to a file, only to move it. | |
H5File & | operator= (const H5File &)=delete |
It does not make sense to copy an object referring to a file, only to move it. | |
template<typename ObjectType , typename... Args, typename std::enable_if_t<((void) sizeof(ObjectType), Access_t==AccessType::ReadWrite)> * = nullptr> | |
ObjectType & | get (const std::string &path, Args &&... args) |
template<typename ObjectType , typename... Args> | |
const ObjectType & | get (const std::string &path, Args &&... args) const |
Opens an HDF5 file for access and allows manipulation of data.
Opens an HDF5 file either in ReadOnly or ReadWrite mode depending on the template parameter Access_t
. In ReadWrite mode h5::Object's can be inserted into the file, and objects can be retrieved to have their data manipulated. Example objects are dat files, text files, and volume data files. A single H5File can contain many different objects so that the number of files stored during a simulation is reduced.
When an h5::object inside an H5File is opened or created the H5File object holds a copy of the h5::object.
To open a file for read-write access:
get
that takes a lambda. The lambda takes exactly one parameter of the type of the h5::Object it will be operating on. While this approach is likely to be syntactically strange for many users it will most likely be more performant than the shared_ptr
solution.Access_t | either h5::AccessType::ReadWrite or h5::AccessType::ReadOnly |
|
explicit |
Requires: file_name
is a valid path and ends in .h5
.
Effects: On object creation opens the HDF5 file at file_name
file_name | the path to the file to open or create |
append_to_file | if true allow appending to the file, otherwise abort the simulation if the file exists |
input_source | a string containing the input source options (yaml formatted). Defaults to an empty string; when writing, specify the provided yaml input options (if any) to write them to the output file's InputSource.yaml attribute. |
use_file_locking | Toggle file locking (default false). HDF5 file locking is explained here: https://github.com/HDFGroup/hdf5/blob/develop/doc/file-locking.md. This toggle only has an effect if the HDF5 library supports 'H5Pset_file_locking'. Otherwise, file locking is enabled if the HDF5 library was built with it, which it probably was. If file locking is enabled, simulations may crash when the file they try to access is being read by another process (like an analysis tool). We could make this more resilient in the future by waiting to acquire the file lock with a timeout, and/or retrying IO operations after progressively longer wait times (e.g. first try again right away, then also print to terminal after some retries, then eventually abort to avoid wasting compute time on a run that can't do IO). |
const std::vector< std::string > h5::H5File< Access_t >::all_files | ( | const std::string & | group_name | ) | const |
Return a vector of all filenames in the H5 file.
ObjectType | Only return a vector that contains this type of file. Default is void which returns all files. |
void h5::H5File< Access_t >::close | ( | ) | const |
Effects: Closes the H5 file. No H5 operations are permitted after this operation.
|
inline |
Effects: Closes the current object, if there is none then has no effect
ObjectType & h5::H5File< Access_t >::get | ( | const std::string & | path, |
Args &&... | args | ||
) |
Requires: ObjectType
is a valid h5::Object derived class, path
is a valid path in the HDF5 file
Returns: a reference to the object inside the HDF5 file.
ObjectType | the type of the h5::Object to be retrieved, e.g. Dat |
path | the path of the retrieved object |
args | arguments forwarded to the ObjectType constructor |
const ObjectType & h5::H5File< Access_t >::get | ( | const std::string & | path, |
Args &&... | args | ||
) | const |
Requires: ObjectType
is a valid h5::Object derived class, path
is a valid path in the HDF5 file
Returns: a reference to the object inside the HDF5 file.
ObjectType | the type of the h5::Object to be retrieved, e.g. Dat |
path | the path of the retrieved object |
args | arguments forwarded to the ObjectType constructor |
ObjectType & h5::H5File< Access_t >::insert | ( | const std::string & | path, |
Args &&... | args | ||
) |
Insert an object into an H5 file.
Requires: ObjectType
is a valid h5::Object derived class, path
is a valid path in the HDF5 file, and args
are valid arguments to be forwarded to the constructor of ObjectType
.
Effects: Creates a new H5 object of type ObjectType
at the location path
in the HDF5 file.
Returns: a reference the created object.
ObjectType | the type of the h5::Object to be inserted, e.g. Dat |
path | the path of the inserted object |
args | additional arguments to be passed to the constructor of the object |