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

Detailed Description

template<AccessType Access_t>
class h5::H5File< Access_t >

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.

Warning: Only one object can be open at a time, which means if a reference to the object is kept around after the H5File's current object is closed there is a dangling reference. Also, this means that after you insert an object, you must close that object before you can insert/open another.

Example

To open a file for read-write access:

h5::H5File<h5::AccessType::ReadWrite> my_file(file_name);

h5::H5File< h5::AccessType::ReadWrite >

Note: The dangling reference issue could be fixed by having a function in addition to 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.

Template Parameters

Access_t either h5::AccessType::ReadWrite or h5::AccessType::ReadOnly

Constructor & Destructor Documentation

◆ H5File()

template<AccessType Access_t>

h5::H5File< Access_t >::H5File	(	std::string	file_name,
		bool	append_to_file = `false`,
		const std::string &	input_source = `""s`,
		bool	use_file_locking = `false`
	)

explicit

Requires: file_name is a valid path and ends in .h5.

Effects: On object creation opens the HDF5 file at file_name

Parameters

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).

Member Function Documentation

◆ all_files()

template<AccessType Access_t>

template<typename ObjectType >

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.

Template Parameters

ObjectType Only return a vector that contains this type of file. Default is void which returns all files.

◆ close()

template<AccessType Access_t>

void h5::H5File< Access_t >::close ( ) const

Effects: Closes the H5 file. No H5 operations are permitted after this operation.

◆ close_current_object()

template<AccessType Access_t>

void h5::H5File< Access_t >::close_current_object ( ) const

inline

Effects: Closes the current object, if there is none then has no effect

◆ get() [1/2]

template<AccessType Access_t>

template<typename ObjectType , typename... Args, typename std::enable_if_t<((void) sizeof(ObjectType), Access_t==AccessType::ReadWrite)> * >

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.

Template Parameters

ObjectType the type of the h5::Object to be retrieved, e.g. Dat

Parameters

path	the path of the retrieved object
args	arguments forwarded to the ObjectType constructor

◆ get() [2/2]

template<AccessType Access_t>

template<typename ObjectType , typename... Args>

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.

Template Parameters

ObjectType the type of the h5::Object to be retrieved, e.g. Dat

Parameters

path	the path of the retrieved object
args	arguments forwarded to the ObjectType constructor

◆ insert()

template<AccessType Access_t>

template<typename ObjectType , typename... Args>

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.

Template Parameters

ObjectType the type of the h5::Object to be inserted, e.g. Dat

Parameters

path	the path of the inserted object
args	additional arguments to be passed to the constructor of the object

The documentation for this class was generated from the following file:

src/IO/H5/File.hpp

Public Member Functions

Detailed Description

Example

Constructor & Destructor Documentation

◆ H5File()

Member Function Documentation

◆ all_files()

◆ close()

◆ close_current_object()

◆ get() [1/2]

◆ get() [2/2]

◆ insert()