Shared implementation of the Serializer. More...

#include <SerializerImpl.h>

Public Member Functions
	SerializerImpl (const SerializerImpl &)=delete
	Copy constructor [deleted].

	SerializerImpl (SerializerImpl &&)=default
	Move constructor.

SerializerImpl &	operator= (const SerializerImpl &)=delete
	Copy assignment [deleted].

SerializerImpl &	operator= (SerializerImpl &&)=default
	Move assignment.

	SerializerImpl (OpenModeKind mode, const std::string &directory, const std::string &prefix, const std::string &archiveName)
	Construct Serializer. More...

OpenModeKind	mode () const noexcept
	Access the mode of the serializer.

const filesystem::path &	directory () const noexcept
	Access the directory in which the Serializer and Archive are opened.

std::string	prefix () const noexcept
	Access prefix of all filenames.

std::string	archiveName () const noexcept
	Name of the archive in use.

const filesystem::path &	metaDataFile () const noexcept
	Access the path to the meta-data file.

void	clear () noexcept
	Drop all field and savepoint meta-data. More...

template<class StringType , class ValueType >
void	addGlobalMetainfo (StringType &&key, ValueType &&value)
	Add a new key-value pair to the global meta-information of the Serializer. More...

template<class T , class StringType >
T	getGlobalMetainfoAs (StringType &&key) const
	Query globalMetainfo map for key `key` and retrieve value as type `T` More...

MetainfoMapImpl &	globalMetainfo () noexcept
	Get a refrence to the global meta information.

const MetainfoMapImpl &	globalMetainfo () const noexcept

std::shared_ptr< MetainfoMapImpl > &	globalMetainfoPtr () noexcept
	Get pointer to the global meta information.

const std::shared_ptr< MetainfoMapImpl > &	globalMetainfoPtr () const noexcept

template<class StringType , typename... Args>
void	registerField (StringType &&name, Args &&... args)
	Register a new field within the Serializer. More...

template<class StringType >
bool	hasField (StringType &&name) const noexcept
	Check if field `name` has been registred within the Serializer. More...

template<class StringType , class KeyType , class ValueType >
bool	addFieldMetainfoImpl (StringType &&name, KeyType &&key, ValueType &&value)
	Add `key = value` or `key = {value1, ..., valueN}` meta-information to field `name` More...

template<class StringType >
const FieldMetainfoImpl &	getFieldMetainfoImplOf (StringType &&name) const
	Query FieldMap for field with `name` and return a refrence to FieldMetainfoImpl. More...

std::vector< std::string >	fieldnames () const
	Get a vector of all registered fields. More...

FieldMap &	fieldMap () noexcept
	Get refrence to the field map.

const FieldMap &	fieldMap () const noexcept

std::shared_ptr< FieldMap > &	fieldMapPtr () noexcept
	Get pointer to the field map.

const std::shared_ptr< FieldMap > &	fieldMapPtr () const noexcept

template<typename... Args>
bool	registerSavepoint (Args &&... args) noexcept
	Register a savepoint. More...

bool	addFieldToSavepoint (const SavepointImpl &savepoint, const FieldID &fieldID) noexcept
	Add a field to the savepoint. More...

FieldID	getFieldIDAtSavepoint (const SavepointImpl &savepoint, const std::string &field) const
	Get the FielID of field `field` at savepoint `savepoint` More...

const SavepointVector::savepoint_vector_type &	savepoints () const noexcept
	Get refrence to savepoint vector.

SavepointVector::savepoint_vector_type &	savepoints () noexcept

const SavepointVector &	savepointVector () const noexcept
	Get refrence to SavepointVector.

SavepointVector &	savepointVector () noexcept

const std::shared_ptr< SavepointVector > &	savepointVectorPtr () const noexcept
	Get pointer to SavepointVector.

std::shared_ptr< SavepointVector > &	savepointVectorPtr () noexcept

void	write (const std::string &name, const SavepointImpl &savepoint, const StorageView &storageView)
	Serialize field `name` (given as `storageView`) at `savepoint` to disk. More...

void	read (const std::string &name, const SavepointImpl &savepoint, StorageView &storageView, bool alsoPrevious=false)
	Deserialize field `name` (given as `storageView`) at `savepoint` from disk. More...

void	readSliced (const std::string &name, const SavepointImpl &savepoint, StorageView &storageView, Slice slice)
	Deserialize sliced field `name` (given as `storageView` and `slice`) at `savepoint` from disk. More...

void	readAsync (const std::string &name, const SavepointImpl &savepoint, StorageView &storageView)
	Asynchronously deserialize field `name` (given as `storageView`) at `savepoint` from disk using std::async. More...

void	waitForAll ()
	Wait for all pending asynchronous read operations and reset the internal queue.

void	updateMetaData ()
	Convert meta-data to JSON and serialize to MetaData-prefix.json and ArchiveMetaData-prefix.json. More...

json::json	toJSON () const
	Convert all members of the Serializer to JSON.

std::string	toString () const
	Convert to string.

Static Public Member Functions
static int	serializationStatus () noexcept
	Get the status of serialization. More...

static void	enableSerialization () noexcept
	Enable serialization. More...

static void	disableSerialization () noexcept
	Disable serialization. More...

Protected Member Functions
void	constructMetaDataFromJson ()
	Construct meta-data from JSON. More...

void	constructArchive (const std::string &archiveName)
	Construct Archive from JSON. More...

std::shared_ptr< FieldMetainfoImpl >	checkStorageView (const std::string &name, const StorageView &storageView) const
	Check if `storageView` is consistent with the field `name` More...

bool	upgradeMetaData ()
	Check if the current directory contains meta-information of an older version of serialbox and upgrade it if necessary. More...

void	readAsyncImpl (const std::string name, const SavepointImpl savepoint, StorageView storageView)
	Implementation of SerializerImpl::readAsync.

Protected Attributes
OpenModeKind	mode_

filesystem::path	directory_

filesystem::path	metaDataFile_

std::string	prefix_

std::shared_ptr< SavepointVector >	savepointVector_

std::shared_ptr< FieldMap >	fieldMap_

std::shared_ptr< MetainfoMapImpl >	globalMetainfo_

std::unique_ptr< Archive >	archive_

Static Protected Attributes
static int	enabled_ = 0

Friends
std::ostream &	operator<< (std::ostream &stream, const SerializerImpl &s)
	Convert to stream.

Detailed Description

Shared implementation of the Serializer.

Direct usage of this class is discouraged, use the Serializer classes provided by the Frontends instead.

Definition at line 36 of file SerializerImpl.h.

Constructor & Destructor Documentation

◆ SerializerImpl()

serialbox::SerializerImpl::SerializerImpl	(	OpenModeKind	mode,
		const std::string &	directory,
		const std::string &	prefix,
		const std::string &	archiveName
	)

Construct Serializer.

Parameters

mode	Mode of the Serializer
directory	Directory of the Archive and Serializer meta-data
prefix	Prefix of all filenames
archiveName	String passed to the ArchiveFactory to construct the Archive

This will read MetaData-prefix.json to initialize the savepoint vector, the fieldMap and globalMetainfo. Further, it will construct the Archive by reading the ArchiveMetaData-prefix.json.

Exceptions

Exception Invalid directory or corrupted meta-data files

Definition at line 39 of file SerializerImpl.cpp.

Member Function Documentation

◆ addFieldMetainfoImpl()

template<class StringType , class KeyType , class ValueType >

bool serialbox::SerializerImpl::addFieldMetainfoImpl	(	StringType &&	name,
		KeyType &&	key,
		ValueType &&	value
	)

inline

Add key = value or key = {value1, ..., valueN} meta-information to field name

Parameters

name	Name of the field
key	Key of the new element
value	Object to be copied to (or moved as) the value of the new element

Returns: Value indicating whether the element was successfully inserted or not

Exceptions

Exception Field with name name does not exist in FieldMap

Definition at line 197 of file SerializerImpl.h.

◆ addFieldToSavepoint()

bool serialbox::SerializerImpl::addFieldToSavepoint	(	const SavepointImpl &	savepoint,
		const FieldID &	fieldID
	)

inlinenoexcept

Add a field to the savepoint.

Returns: True iff the field was successfully addeed to the savepoint

Definition at line 239 of file SerializerImpl.h.

◆ addGlobalMetainfo()

template<class StringType , class ValueType >

void serialbox::SerializerImpl::addGlobalMetainfo	(	StringType &&	key,
		ValueType &&	value
	)

inline

Add a new key-value pair to the global meta-information of the Serializer.

Parameters

key	Key of the new element
value	Object to be copied to (or moved as) the value of the new element

Exceptions

Exception Value cannot be inserted as it already exists

Definition at line 132 of file SerializerImpl.h.

◆ checkStorageView()

std::shared_ptr< FieldMetainfoImpl > serialbox::SerializerImpl::checkStorageView	(	const std::string &	name,
		const StorageView &	storageView
	)		const

protected

Check if storageView is consistent with the field name

Returns: FieldMetainfoImpl of field name

Exceptions

Exception Inconsistency is detected

Definition at line 106 of file SerializerImpl.cpp.

◆ clear()

void serialbox::SerializerImpl::clear ( )

noexcept

Drop all field and savepoint meta-data.

This will also call Archive::clear() which may remove all related files on the disk.

Definition at line 78 of file SerializerImpl.cpp.

◆ constructArchive()

void serialbox::SerializerImpl::constructArchive ( const std::string & archiveName )

protected

Construct Archive from JSON.

This will read ArchiveMetaData-prefix.json and initialize the archive.

Parameters

archiveName String passed to the ArchiveFactory to construct the Archive

Definition at line 412 of file SerializerImpl.cpp.

◆ constructMetaDataFromJson()

void serialbox::SerializerImpl::constructMetaDataFromJson ( )

protected

Construct meta-data from JSON.

This will read MetaData-prefix.json to initialize the savepoint vector, the fieldMap and globalMetainfo.

Definition at line 292 of file SerializerImpl.cpp.

◆ disableSerialization()

static void serialbox::SerializerImpl::disableSerialization ( )

inlinestaticnoexcept

Disable serialization.

Serialization is enabled by default, but it can be disabled either by setting the environment variable SERIALBOX_SERIALIZATION_DISABLE to a positive value or by calling the funtcion disableSerialization. With this function you disable the serialization independently of the current environment.

The serialization can only be globally enabled or disabled. There is no way to enable or disable only a specific serializer.

Definition at line 72 of file SerializerImpl.h.

◆ enableSerialization()

static void serialbox::SerializerImpl::enableSerialization ( )

inlinestaticnoexcept

Enable serialization.

Serialization is enabled by default, but it can be disabled either by setting the environment variable SERIALBOX_SERIALIZATION_DISABLE to a positive value or by calling the function disableSerialization. With this function you enable the serialization independently of the current environment.

The serialization can only globally enabled or disabled. There is no way to enable or disable only a specific serializer.

Definition at line 61 of file SerializerImpl.h.

◆ fieldnames()

std::vector< std::string > serialbox::SerializerImpl::fieldnames ( ) const

Get a vector of all registered fields.

Returns: Vector with the names of the registered fields

Definition at line 85 of file SerializerImpl.cpp.

◆ getFieldIDAtSavepoint()

FieldID serialbox::SerializerImpl::getFieldIDAtSavepoint	(	const SavepointImpl &	savepoint,
		const std::string &	field
	)		const

inline

Get the FielID of field field at savepoint savepoint

Exceptions

Exception Savepoint or field at savepoint do not exist

Definition at line 246 of file SerializerImpl.h.

◆ getFieldMetainfoImplOf()

template<class StringType >

const FieldMetainfoImpl& serialbox::SerializerImpl::getFieldMetainfoImplOf ( StringType && name ) const

inline

Query FieldMap for field with name and return a refrence to FieldMetainfoImpl.

Parameters

name	Name of the field

Exceptions

Exception Field name does not exist in FieldMap

Definition at line 208 of file SerializerImpl.h.

◆ getGlobalMetainfoAs()

template<class T , class StringType >

T serialbox::SerializerImpl::getGlobalMetainfoAs ( StringType && key ) const

inline

Query globalMetainfo map for key key and retrieve value as type T

Parameters

key	Key of the requested element

Exceptions

Exception Key key does not exist in the globalMetainfo map or value cannot be converted to type T

Definition at line 145 of file SerializerImpl.h.

◆ hasField()

template<class StringType >

bool serialbox::SerializerImpl::hasField ( StringType && name ) const

inlinenoexcept

Check if field name has been registred within the Serializer.

Parameters

name	Name of the the new field

Returns: True iff the field is present

Definition at line 184 of file SerializerImpl.h.

◆ read()

void serialbox::SerializerImpl::read	(	const std::string &	name,
		const SavepointImpl &	savepoint,
		StorageView &	storageView,
		bool	alsoPrevious = `false`
	)

Deserialize field name (given as storageView) at savepoint from disk.

The method perfoms the following steps:

Check if field name is registred within the Serializer and perform a consistency check concering the data-type and dimensions of the StorageView compared to to the registered field.
Check if savepoint exists and has a field name.
Pass the StorageView to the backend Archive and perform actual data-deserialization.

Parameters

name	Name of the field
savepoint	Savepoint at which the field will be deserialized
storageView	StorageView of the field

Exceptions

Exception

See also: Archive::read

Definition at line 189 of file SerializerImpl.cpp.

◆ readAsync()

void serialbox::SerializerImpl::readAsync	(	const std::string &	name,
		const SavepointImpl &	savepoint,
		StorageView &	storageView
	)

Asynchronously deserialize field name (given as storageView) at savepoint from disk using std::async.

This method runs the read function (SerializerImpl::read) asynchronously (potentially in a separate thread which may be part of a thread pool) meaning this function immediately returns. To synchronize all threads, use SerializerImpl::waitForAll.

If the archive is not thread-safe or if the library was not configured with SERIALBOX_ASYNC_API the method falls back to synchronous execution.

Parameters

name	Name of the field
savepoint	Savepoint at which the field will be deserialized
storageView	StorageView of the field

Exceptions

Exception

See also: SerializerImpl::read; http://en.cppreference.com/w/cpp/thread/async

Definition at line 260 of file SerializerImpl.cpp.

◆ readSliced()

void serialbox::SerializerImpl::readSliced	(	const std::string &	name,
		const SavepointImpl &	savepoint,
		StorageView &	storageView,
		Slice	slice
	)

Deserialize sliced field name (given as storageView and slice) at savepoint from disk.

Parameters

name	Name of the field
savepoint	Savepoint at which the field will be deserialized
storageView	StorageView of the field
slice	Slice of the data to load

Exceptions

Exception

See also: SerializerImpl::read

Definition at line 236 of file SerializerImpl.cpp.

◆ registerField()

template<class StringType , typename... Args>

void serialbox::SerializerImpl::registerField	(	StringType &&	name,
		Args &&...	args
	)

inline

Register a new field within the Serializer.

Parameters

name	Name of the the new field
Args	Arguments forwarded to the constructor of FieldMetainfoImpl

Exceptions

Exception Field with same name already exists

Definition at line 174 of file SerializerImpl.h.

◆ registerSavepoint()

template<typename... Args>

bool serialbox::SerializerImpl::registerSavepoint ( Args &&... args )

inlinenoexcept

Register a savepoint.

Parameters

Args	Arguments forwarded to the constructor of Savepoint

Returns: True iff the savepoint was successfully inserted

Definition at line 233 of file SerializerImpl.h.

◆ serializationStatus()

static int serialbox::SerializerImpl::serializationStatus ( )

inlinestaticnoexcept

Get the status of serialization.

The status is represented as an integer which can take the following values:

0: the variable is not yet initialized -> the serialization is enabled if the environment variable SERIALBOX_SERIALIZATION_DISABLE is not set to a positive value. The first Serializer which is initialized has to set this value either to +1 or to -1 according to the environment.
+1: the serialization is enabled, independently of the environment
-1: the serialization is disabled, independently of the environment

Returns: serialization status

Definition at line 50 of file SerializerImpl.h.

◆ updateMetaData()

void serialbox::SerializerImpl::updateMetaData ( )

Convert meta-data to JSON and serialize to MetaData-prefix.json and ArchiveMetaData-prefix.json.

This will ensure MetaData-prefix.json is up-to-date with the in-memory versions of the savepointVector, fieldMap and globalMetainfo as well as the meta-data of the Archive.

Definition at line 395 of file SerializerImpl.cpp.

◆ upgradeMetaData()

bool serialbox::SerializerImpl::upgradeMetaData ( )

protected

Check if the current directory contains meta-information of an older version of serialbox and upgrade it if necessary.

The function will check if there is a prefix.json file which is newer than MetaData-prefix.json and, if ture, convert prefix.json to MetaData-prefix.json and ArchiveMetaData.json.

Older versions of serialbox can only be opened in OpenModeKind::Read and will use the BinaryArchive.

Returns: True iff the upgrade was successful

Exceptions

Exception

Definition at line 420 of file SerializerImpl.cpp.

◆ write()

void serialbox::SerializerImpl::write	(	const std::string &	name,
		const SavepointImpl &	savepoint,
		const StorageView &	storageView
	)

Serialize field name (given as storageView) at savepoint to disk.

The method perfoms the following steps:

Check if field name is registred within the Serializer and perform a consistency check concering the data-type and dimensions of the StorageView compared to to the registered field.
Locate the savepoint in the savepoint vector and, if the savepoint does not exist, register it within the Serializer.
Check if field name can be added to Savepoint.
Pass the StorageView to the backend Archive and perform actual data-serialization.
Register field name within the Savepoint.
Update meta-data on disk via SerializerImpl::updateMetaData()

Parameters

name	Name of the field
savepoint	Savepoint at which the field will be serialized
storageView	StorageView of the field

Exceptions

Exception

See also: Archive::write

Definition at line 135 of file SerializerImpl.cpp.

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

src/serialbox/core/SerializerImpl.h
src/serialbox/core/SerializerImpl.cpp

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Static Protected Attributes

Friends

Detailed Description

Constructor & Destructor Documentation

◆ SerializerImpl()

Member Function Documentation

◆ addFieldMetainfoImpl()

◆ addFieldToSavepoint()

◆ addGlobalMetainfo()

◆ checkStorageView()

◆ clear()

◆ constructArchive()

◆ constructMetaDataFromJson()

◆ disableSerialization()

◆ enableSerialization()

◆ fieldnames()

◆ getFieldIDAtSavepoint()

◆ getFieldMetainfoImplOf()

◆ getGlobalMetainfoAs()

◆ hasField()

◆ read()

◆ readAsync()

◆ readSliced()

◆ registerField()

◆ registerSavepoint()

◆ serializationStatus()

◆ updateMetaData()

◆ upgradeMetaData()

◆ write()