H5::File Class Reference

Inheritance diagram for H5::File:

Classes
struct	ProcessInfo
	Information about a process accessing the shared memory (a process means here an instance of a File class) More...
struct	SharedMemObject

Public Types
enum	FileAccess { read , write , writeWithRename }

Public Member Functions
	File (const boost::filesystem::path &filename_, FileAccess type_, const std::function< void()> &closeRequestCallback_={}, const std::function< void()> &refreshCallback_={}, const std::function< void()> &renameAtomicFunc_={})
	~File () override
	Closes the HDF5 file.
void	enableSWMR () override
void	refresh () override
	Refresh the dataset of a reader. More...
void	requestFlush ()
void	flushIfRequested ()
FileAccess	getType (bool originalType=false)
Public Member Functions inherited from H5::GroupBase
template<class T >
Container< Object, GroupBase >::Creator< T >	createChildObject (const std::string &path)
template<class T >
T *	openChildObject (const std::string &path)
Object *	openChildObject (const std::string &name_, ElementType *objectType=nullptr, hid_t *type=nullptr)
std::list< std::string >	getChildObjectNames ()
Public Member Functions inherited from H5::Object
template<class T >
Creator< T >	createChildAttribute (const std::string &path)
template<class T >
T *	openChildAttribute (const std::string &path)
Attribute *	openChildAttribute (const std::string &name_, ElementType *attributeType=nullptr, hid_t *type=nullptr)
std::set< std::string >	getChildAttributeNames ()
bool	hasChildAttribute (const std::string &name_)
GroupBase *	getParent ()
File *	getFile ()
std::string	getPath ()
Public Member Functions inherited from H5::Element
hid_t	getID ()
	Note: use the returned hid_t only temporarily since it may get invalid, at least when File::enableSWMR is called.
std::string	getName ()

Static Public Member Functions
static int	getDefaultCompression ()
static void	setDefaultCompression (int comp)
static int	getDefaultChunkSize ()
static void	setDefaultChunkSize (int chunk)
static int	getDefaultCacheSize ()
static void	setDefaultCacheSize (int cache)
static void	dumpSharedMemory (const boost::filesystem::path &filename)
static void	removeSharedMemory (const boost::filesystem::path &filename)
	Internal helper function which removes the shared memory associated with filename, !!!EVEN if other process still use it!!!

Private Types
enum class	WriterState { none , writeRequest , active , swmr }
	A writer can be in the following state:

Private Member Functions
void	close () override
boost::filesystem::path	getFilename (bool originalFilename=false)
void	preOpenReader ()
	Helper function to prepare for openReader.
void	openReader ()
	Helper function to open the file as a reader. preOpenReader must be called before.
void	closeReader ()
	Helper function to close the file as a reader.
void	postCloseReader ()
void	preOpenWriter ()
	Helper function to prepare for openWriter.
void	openWriter ()
	Helper function to open the file as a writer. preOpenWriter must be called before.
void	closeWriter ()
	Helper function to close the file as a writer.
void	postCloseWriter ()
void	wait (Internal::ScopedLock &lock, const std::chrono::milliseconds &relTime, std::string_view blockingMsg, const std::function< bool()> &pred)
void	stillAlivePing ()
void	listenForRequest ()
	The worker function for the thread listenForRequestThread.
void	initProcessInfo ()
	Write process information of this process to the shared memory.
void	deinitProcessInfo ()
	Remove process information of this process from the shared memory.

Static Private Member Functions
static std::string	createShmName (const boost::filesystem::path &filename)
	transform filename to a valid boost interprocess name.
static void	openOrCreateShm (const boost::filesystem::path &filename, File *self, std::string &shmName, Internal::SharedMemory &shm, boost::interprocess::mapped_region &region, SharedMemObject *&sharedData)
	open or create the shared memory atomically (guarded by a global named mutex)
static void	deinitShm (SharedMemObject *sharedData, const boost::filesystem::path &filename, File *self, const std::string &shmName)

Private Attributes
boost::filesystem::path	filename
	The name of the file.
FileAccess	type
	Flag if this instance is a writer or reader.
bool	preSWMR { false }
const std::function< void()>	closeRequestCallback
	This callback is called when a writer requested a close of all readers.
const std::function< void()>	refreshCallback
	This callback is called when a writer has flushed.
const std::function< void()>	renameAtomicFunc
std::string	shmName
	Name of the shared memory. More...
const boost::uuids::uuid	processUUID
Internal::SharedMemory	shm
boost::interprocess::mapped_region	region
SharedMemObject *	sharedData {nullptr}
	Pointer to the shared memory object.
bool	flushRequested { false }
	True if this reader has requested a flush.
WriterState	lastWriterState { WriterState::none }
	The last wrtierState known by this object.
boost::thread	stillAlivePingThread
std::thread	listenForRequestThread
bool	exitThread { false }
	Flag which is set to true to enforce the thread to exit (on the next condition notify signal)

Static Private Attributes
static int	defaultCompression =1
static int	defaultChunkSize =100
static int	defaultCacheSize =100
static constexpr size_t	MAXREADERS { 100 }
	the maximal number of readers which can access the file simultanously
static constexpr size_t	MAXWRITERS { 10 }
	the maximal number of writers. Just need since only a fixed amount of readers+writers can wait for the ConditionVariable

Friends
class	Internal::ScopedLock

Additional Inherited Members
Protected Member Functions inherited from H5::GroupBase
	GroupBase (int dummy, GroupBase *parent_, const std::string &name_)
	GroupBase (GroupBase *parent_, const std::string &name_)
void	close () override
void	refresh () override
void	flush () override
void	enableSWMR () override
Dataset *	openChildDataset (const std::string &name_, ElementType *objectType, hid_t *type)
GroupBase *	getFileAsGroup ()
Protected Member Functions inherited from H5::Object
	Object (GroupBase *parent_, const std::string &name_)
void	close () override
void	refresh () override
void	flush () override
void	enableSWMR () override
Object *	getFileAsObject ()
Object *	getAttrParent (const std::string &path, size_t pos)
Protected Member Functions inherited from H5::Element
	Element (std::string name_)
virtual void	close ()
virtual void	refresh ()
virtual void	flush ()
virtual void	enableSWMR ()
Protected Member Functions inherited from H5::Container< Attribute, Object >
void	close ()
void	refresh ()
void	flush ()
void	enableSWMR ()
Creator< T >	createChild (const std::string &name_)
T *	openChild (const std::string &name_)
Protected Member Functions inherited from H5::Container< Object, GroupBase >
void	close ()
void	refresh ()
void	flush ()
void	enableSWMR ()
Creator< T >	createChild (const std::string &name_)
T *	openChild (const std::string &name_)
Protected Attributes inherited from H5::Object
GroupBase *	parent
File *	file
Protected Attributes inherited from H5::Element
ScopedHID	id
std::string	name
Protected Attributes inherited from H5::Container< Attribute, Object >
std::map< std::string, Attribute * >	childs
Protected Attributes inherited from H5::Container< Object, GroupBase >
std::map< std::string, Object * >	childs

Member Enumeration Documentation

FileAccess

enum H5::File::FileAccess

Enumerator
read	Open file for reading with SWMR reading mode enabled.
write	Open file for writing. Calling enableSWMR will switch to SWMR writing mode. Note that enableSWMR will close all attributes.
writeWithRename	Open file for writing with a modified filename (<path>/<basename>.preSWMR.<ext>). Calling enableSWMR will close the file, rename it to the normal filename (<path>/<basename>.<ext>), reopen it in SWMR writing mode while all Elements of the file, except Attributes which are closed, are still available (but there hid_t will change, call getID() gain if needed). This is useful to avoid locking the normal filename during the none SWMR mode write tasks. This way the time the file is exclusively locked (in none SWMR mode) is minimized.

Constructor & Destructor Documentation

File()

H5::File::File	(	const boost::filesystem::path &	filename_,
		FileAccess	type_,
		const std::function< void()> &	closeRequestCallback_ = {},
		const std::function< void()> &	refreshCallback_ = {},
		const std::function< void()> &	renameAtomicFunc_ = {}
	)

Opens the HDF5 file filename_ as a writer or reader dependent on type_. For a reader closeRequestCallback_ should be set! This callback is called if any writer want to write the file this reader also holds. If this callback is called you should close (destruct) this File object in time. After close (destruct) you can immediately reopen the file by constructing a File object (with the same HDF5 file) again. The inter process communication will ensure the the requested writer does its job before you can reopen the file for reading again. For a reader refreshCallback_ should also be set if the reader will call requestFlush. This this callback is called the reader should call refresh(). Note that both callback functions will be called from of a thread created by this constructor. If the file was opened with writeWithRename then the function renameAtomicFunc is called immediately after the rename of the HDF5 file took place, at a time when both files are still locked. Hence, this function can be used if other actions a rename of additional files need to happen in a way being synchronous to the HDF5 rename

Member Function Documentation

close()

void H5::File::close ( )

overrideprivatevirtual

Reimplemented from H5::Element.

dumpSharedMemory()

void H5::File::dumpSharedMemory ( const boost::filesystem::path &  filename )

static

Internal helper function which dumps the content of the shared memory associated with filename. !!! Note that the shared memory mutex is NOT locked for this operation but the global named mutex to create/open and destroy lock is accquired.

enableSWMR()

void H5::File::enableSWMR ( )

overridevirtual

Switch a writer from dataset creation mode to SWMR. After this call no datasets, groups or attributes can be created anymore and attributes are closed! But readers are no longer blocked and can read the file.

Reimplemented from H5::Element.

flushIfRequested()

void H5::File::flushIfRequested

(

)

Flush the file (the dataset) of a writer if this is requested by a reader. Does nothing if no reader has requested a flush. If a flush happend the reades are notified about the flush.

refresh()

void H5::File::refresh ( )

overridevirtual

Refresh the dataset of a reader.

Reimplemented from H5::Element.

requestFlush()

void H5::File::requestFlush

(

)

Request a flush of the writer. This is not blocking. If the writer has flushed the refreshCallback is called, see constructor.

wait()

void H5::File::wait ( Internal::ScopedLock &  lock, const std::chrono::milliseconds &  relTime, std::string_view  blockingMsg, const std::function< bool()> &  pred  )

private

Helper function which waits until the condition pred is true. On entry the lock lock is released and re-aquired if waiting ends (the pred() == true). If this call blocks for more then relTime then then the message blockingMsg is printed but wait will not return (its blocking until pred is true) (use a empty string to avoid printing)

Member Data Documentation

listenForRequestThread

std::thread H5::File::listenForRequestThread

private

A thread created for a reader to listen when a new writer process requests a write of has flushed the file. boost thread interruption points does not help here since its not working with ConditionVariable -> hence we implement it ourself using the exitThread flag

preSWMR

bool H5::File::preSWMR { false }

private

This flag is set if the file was opened in writeWithRename mode and is currently in this mode (enableSWMR was not called yet) (note that type is reset to write in this case in the ctor, hence you need to used this flag)

region

boost::interprocess::mapped_region H5::File::region

private

Memory region holding the shared memory map Open/create and destroy of region must bu guarded by a mutex

shm

Internal::SharedMemory H5::File::shm

private

Shared memory object holding the shared memory Open/create and destroy of shm must bu guarded by a mutex

shmName

std::string H5::File::shmName

private

Name of the shared memory.

a globally unique identifier for this process

---

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

• /mbsim-env/hdf5serie/hdf5serie/hdf5serie/file.h
• /mbsim-env/hdf5serie/hdf5serie/hdf5serie/file.cc