SERIALBOX_API serialboxSerializer_t *	serialboxSerializerCreate (int mode, const char directory, const char prefix, const char *archive)
	Create a new Serializer. More...

SERIALBOX_API void	serialboxSerializerDestroy (serialboxSerializer_t *serializer)
	Destroy the serializer and deallocate all memory. More...

SERIALBOX_API int	serialboxSerializerGetMode (const serialboxSerializer_t *serializer)
	Return mode of the Serializer. More...

SERIALBOX_API char *	serialboxSerializerGetDirectory (const serialboxSerializer_t *serializer)
	Return the directory of the Serializer. More...

SERIALBOX_API char *	serialboxSerializerGetPrefix (const serialboxSerializer_t *serializer)
	Return the prefix of all filenames. More...

SERIALBOX_API void	serialboxSerializerUpdateMetaData (serialboxSerializer_t *serializer)
	Write meta-data to disk. More...

SERIALBOX_API int	serialboxSerializationStatus (void)
	Indicate whether serialization is enabled [default: enabled]. More...

SERIALBOX_API void	serialboxEnableSerialization (void)
	Enabled serialization.

SERIALBOX_API void	serialboxDisableSerialization (void)
	Disable serialization.

SERIALBOX_API char *	serialboxSerializerToString (const serialboxSerializer_t *serializer)
	Convert serializer to string.

SERIALBOX_API serialboxMetainfo_t *	serialboxSerializerGetGlobalMetainfo (serialboxSerializer_t *serializer)
	Allocate a new `serialboxMetainfo_t` which maps to the global meta-information of the Serializer. More...

SERIALBOX_API int	serialboxSerializerAddSavepoint (serialboxSerializer_t serializer, const serialboxSavepoint_t savepoint)
	Register `savepoint` within the serializer. More...

SERIALBOX_API int	serialboxSerializerHasSavepoint (const serialboxSerializer_t serializer, const serialboxSavepoint_t savepoint)
	Check if `savepoint` exists within the serializer. More...

SERIALBOX_API int	serialboxSerializerGetNumSavepoints (const serialboxSerializer_t *serializer)
	Get number of registered savepoints. More...

SERIALBOX_API serialboxSavepoint_t **	serialboxSerializerGetSavepointVector (const serialboxSerializer_t *serializer)
	Get an array of refrences to the registered savepoints. More...

SERIALBOX_API void	serialboxSerializerDestroySavepointVector (serialboxSavepoint_t **savepointVector, int len)
	Deallocate a savepoint vector retrieved via serialboxSerializerGetSavepointVector. More...

SERIALBOX_API serialboxArrayOfString_t *	serialboxSerializerGetFieldnamesAtSavepoint (const serialboxSerializer_t serializer, const serialboxSavepoint_t savepoint)
	Get an array of C-strings of the field names registered at `savepoint` More...

SERIALBOX_API int	serialboxSerializerAddField (serialboxSerializer_t serializer, const char name, const serialboxFieldMetainfo_t *fieldMetainfo)
	Register field given as `fieldMetainfo` within the serializer. More...

SERIALBOX_API int	serialboxSerializerHasField (serialboxSerializer_t serializer, const char field)
	Check if `field` is registered within the serializer. More...

SERIALBOX_API int	serialboxSerializerAddField2 (serialboxSerializer_t serializer, const char name, int type, int bytesPerElement, int iSize, int jSize, int kSize, int lSize, int iMinusHalo, int iPlusHalo, int jMinusHalo, int jPlusHalo, int kMinusHalo, int kPlusHalo, int lMinusHalo, int lPlusHalo)
	Register `field` within the serializer. More...

SERIALBOX_API serialboxArrayOfString_t *	serialboxSerializerGetFieldnames (const serialboxSerializer_t *serializer)
	Get an array of C-strings of all names of the registered fields. More...

SERIALBOX_API serialboxFieldMetainfo_t *	serialboxSerializerGetFieldMetainfo (const serialboxSerializer_t serializer, const char name)
	Get FieldMetainfoImpl of field with name `name` More...

SERIALBOX_API void	serialboxSerializerGetFieldMetainfo2 (const serialboxSerializer_t serializer, const char name, char storedName, char elementType, int rank, int bytesPerElement, int iSize, int jSize, int kSize, int lSize, int iMinusHalo, int iPlusHalo, int jMinusHalo, int jPlusHalo, int kMinusHalo, int kPlusHalo, int lMinusHalo, int lPlusHalo)
	Get values of standard meta info pairs of field with name `name` More...

SERIALBOX_API void	serialboxSerializerWrite (serialboxSerializer_t serializer, const char name, const serialboxSavepoint_t savepoint, void originPtr, const int *strides, int numStrides)
	Serialize field `name` (given by `originPtr` and `strides`) at `savepoint` to disk. More...

SERIALBOX_API void	serialboxSerializerRead (serialboxSerializer_t serializer, const char name, const serialboxSavepoint_t savepoint, void originPtr, const int *strides, int numStrides)
	Deserialize field `name` (given by `originPtr` and `strides`) at `savepoint` from disk. More...

SERIALBOX_API void	serialboxSerializerReadSliced (serialboxSerializer_t serializer, const char name, const serialboxSavepoint_t savepoint, void originPtr, const int strides, int numStrides, const int slice)
	Deserialize sliced field `name` (given by `originPtr`, `strides` and `slice`) at `savepoint` from disk. More...

SERIALBOX_API void	serialboxSerializerReadAsync (serialboxSerializer_t serializer, const char name, const serialboxSavepoint_t savepoint, void originPtr, const int *strides, int numStrides)
	Asynchronously deserialize field `name` (given as `storageView`) at `savepoint` from disk using std::async. More...

SERIALBOX_API void	serialboxSerializerWaitForAll (serialboxSerializer_t *serializer)
	Wait for all pending asynchronous read operations and reset the internal queue.

SERIALBOX_API void	serialboxWriteToFile (const char filename, void originPtr, int typeID, const int dims, int numDims, const int strides, const char fieldname, const char archivename)
	Serialize field `name` (given by `originPtr` and `strides`) directly to file. More...

SERIALBOX_API void	serialboxReadFromFile (const char filename, void originPtr, int typeID, const int dims, int numDims, const int strides, const char fieldname, const char archivename)
	Deserialize field `name` (given by `originPtr` and `strides`) directly from file. More...

Detailed Description

Function Documentation

◆ serialboxReadFromFile()

SERIALBOX_API void serialboxReadFromFile	(	const char *	filename,
		void *	originPtr,
		int	typeID,
		const int *	dims,
		int	numDims,
		const int *	strides,
		const char *	fieldname,
		const char *	archivename
	)

Deserialize field name (given by originPtr and strides) directly from file.

The origingPtr represent the memory location of the first element in the array i.e skipping all initial padding. The file should only contain the requested field.

Attention: This method performs no consistency checks you have to know what you are doing!

Parameters

filename	Name of the file
originPtr	Pointer to the origin of the data
typeID	TypeID of the data
dims	Array of dimensions of length `numDims`
numDims	Number of dimensions
strides	Array of strides of length `numDims` (in unit-strides)
fieldname	Name of the field
archivename	Name of the archive used for serialization (e.g "Binary")

Definition at line 483 of file Serializer.cpp.

◆ serialboxSerializationStatus()

SERIALBOX_API int serialboxSerializationStatus ( void )

Indicate whether serialization is enabled [default: enabled].

The return value can be:

0: the variable is not yet initialized -> the serialization is enabled if the environment variable STELLA_SERIALIZATION_DISABLE or 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

Definition at line 127 of file Serializer.cpp.

◆ serialboxSerializerAddField()

SERIALBOX_API int serialboxSerializerAddField	(	serialboxSerializer_t *	serializer,
		const char *	name,
		const serialboxFieldMetainfo_t *	fieldMetainfo
	)

Register field given as fieldMetainfo within the serializer.

Parameters

serializer	Serializer to use
name	Name of the field to register
field	Field meta-information

Returns: 1 if field was added successfully, 0 otherwise

Definition at line 226 of file Serializer.cpp.

◆ serialboxSerializerAddField2()

SERIALBOX_API int serialboxSerializerAddField2	(	serialboxSerializer_t *	serializer,
		const char *	name,
		int	type,
		int	bytesPerElement,
		int	iSize,
		int	jSize,
		int	kSize,
		int	lSize,
		int	iMinusHalo,
		int	iPlusHalo,
		int	jMinusHalo,
		int	jPlusHalo,
		int	kMinusHalo,
		int	kPlusHalo,
		int	lMinusHalo,
		int	lPlusHalo
	)

Register field within the serializer.

This function behaves the same as in older versions of serialbox.

Parameters

serializer	Serializer to use
name	The name of the field
type	TypeID of the field (serialboxTypeID)
bytesPerElement	The size in bytes of a scalar value (e.g. 8 for doubles)
iSize	The size of the first dimension
jSize	The size of the second dimension
kSize	The size of the third dimension
lsize	The size of the fourth dimension
iMinusHalo	The dimension of the halo in negative i-direction
iPlusHalo	The dimension of the halo in positive i-direction
jMinusHalo	The dimension of the halo in negative j-direction
jPlusHalo	The dimension of the halo in positive j-direction
kMinusHalo	The dimension of the halo in negative k-direction
kPlusHalo	The dimension of the halo in positive k-direction
lMinusHalo	The dimension of the halo in negative l-direction
lPlusHalo	The dimension of the halo in positive l-direction

Returns: 1 if field was added successfully, 0 otherwise

Definition at line 245 of file Serializer.cpp.

◆ serialboxSerializerAddSavepoint()

SERIALBOX_API int serialboxSerializerAddSavepoint	(	serialboxSerializer_t *	serializer,
		const serialboxSavepoint_t *	savepoint
	)

Register savepoint within the serializer.

Parameters

serializer	Serializer to use
savepoint	Savepoint to add

Returns: 1 if savepoint was added successfully, 0 otherwise

Definition at line 156 of file Serializer.cpp.

◆ serialboxSerializerCreate()

SERIALBOX_API serialboxSerializer_t* serialboxSerializerCreate	(	int	mode,
		const char *	directory,
		const char *	prefix,
		const char *	archive
	)

Create a new Serializer.

This will read MetaData-prefix.json to initialize the Serializer and construct the Archive by reading the ArchiveMetaData-prefix.json.

Parameters

mode	Mode of the Serializer
directory	Directory of the Archive and Serializer meta-data
prefix	Prefix of all filenames
archiveName	Name of Archive (e.g "BinaryArchive")

Returns: refrence to the newly constructed Serializer or NULL if an error occurred

Definition at line 62 of file Serializer.cpp.

◆ serialboxSerializerDestroy()

SERIALBOX_API void serialboxSerializerDestroy ( serialboxSerializer_t * serializer )

Destroy the serializer and deallocate all memory.

Parameters

serializer Serializer to use

Definition at line 90 of file Serializer.cpp.

◆ serialboxSerializerDestroySavepointVector()

SERIALBOX_API void serialboxSerializerDestroySavepointVector	(	serialboxSavepoint_t **	savepointVector,
		int	len
	)

Deallocate a savepoint vector retrieved via serialboxSerializerGetSavepointVector.

Parameters

savepointVector	Savepoint vector to deallocate
len	Length of the savepoint vector (usually obtained at the time of allocation via `serialboxSerializerGetNumSavepoints`)

Definition at line 195 of file Serializer.cpp.

◆ serialboxSerializerGetDirectory()

SERIALBOX_API char* serialboxSerializerGetDirectory ( const serialboxSerializer_t * serializer )

Return the directory of the Serializer.

Parameters

serializer Serializer to use

Returns: newly allocated null-terminated string of the directory of the Serializer

Definition at line 108 of file Serializer.cpp.

◆ serialboxSerializerGetFieldMetainfo()

SERIALBOX_API serialboxFieldMetainfo_t* serialboxSerializerGetFieldMetainfo	(	const serialboxSerializer_t *	serializer,
		const char *	name
	)

Get FieldMetainfoImpl of field with name name

Parameters

serializer	Serializer to use
name	Name of the field to search for

Returns: Refrence to the FieldMetainfoImpl if field exists, NULL otherwise

Definition at line 315 of file Serializer.cpp.

◆ serialboxSerializerGetFieldMetainfo2()

SERIALBOX_API void serialboxSerializerGetFieldMetainfo2	(	const serialboxSerializer_t *	serializer,
		const char *	name,
		char **	storedName,
		char **	elementType,
		int *	rank,
		int *	bytesPerElement,
		int *	iSize,
		int *	jSize,
		int *	kSize,
		int *	lSize,
		int *	iMinusHalo,
		int *	iPlusHalo,
		int *	jMinusHalo,
		int *	jPlusHalo,
		int *	kMinusHalo,
		int *	kPlusHalo,
		int *	lMinusHalo,
		int *	lPlusHalo
	)

Get values of standard meta info pairs of field with name name

This function returns all the meta info as set in serialboxSerializerAddField2.

Parameters

serializer	Serializer to use
name	The name of the field
type	TypeID of the field (serialboxTypeID)
bytesPerElement	The size in bytes of a scalar value (e.g. 8 for doubles)
iSize	The size of the first dimension
jSize	The size of the second dimension
kSize	The size of the third dimension
lsize	The size of the fourth dimension
iMinusHalo	The dimension of the halo in negative i-direction
iPlusHalo	The dimension of the halo in positive i-direction
jMinusHalo	The dimension of the halo in negative j-direction
jPlusHalo	The dimension of the halo in positive j-direction
kMinusHalo	The dimension of the halo in negative k-direction
kPlusHalo	The dimension of the halo in positive k-direction
lMinusHalo	The dimension of the halo in negative l-direction
lPlusHalo	The dimension of the halo in positive l-direction

Returns: 1 if field was added successfully, 0 otherwise

Definition at line 328 of file Serializer.cpp.

◆ serialboxSerializerGetFieldnames()

SERIALBOX_API serialboxArrayOfString_t* serialboxSerializerGetFieldnames ( const serialboxSerializer_t * serializer )

Get an array of C-strings of all names of the registered fields.

Parameters

serializer Serializer to use

Returns: Array of C-strings of the names of all registered fields

Definition at line 295 of file Serializer.cpp.

◆ serialboxSerializerGetFieldnamesAtSavepoint()

SERIALBOX_API serialboxArrayOfString_t* serialboxSerializerGetFieldnamesAtSavepoint	(	const serialboxSerializer_t *	serializer,
		const serialboxSavepoint_t *	savepoint
	)

Get an array of C-strings of the field names registered at savepoint

Parameters

serializer	Serializer to use
savepoint	Savepoint of intrest

Returns: Array of C-strings of the names of all registered fields at savepoint

Definition at line 202 of file Serializer.cpp.

◆ serialboxSerializerGetGlobalMetainfo()

SERIALBOX_API serialboxMetainfo_t* serialboxSerializerGetGlobalMetainfo ( serialboxSerializer_t * serializer )

Allocate a new serialboxMetainfo_t which maps to the global meta-information of the Serializer.

Parameters

serializer Serializer to use

Returns: global meta-information of the serializer

Definition at line 144 of file Serializer.cpp.

◆ serialboxSerializerGetMode()

SERIALBOX_API int serialboxSerializerGetMode ( const serialboxSerializer_t * serializer )

Return mode of the Serializer.

Parameters

serializer Serializer to use

Returns: mode of the Serializer

Definition at line 103 of file Serializer.cpp.

◆ serialboxSerializerGetNumSavepoints()

SERIALBOX_API int serialboxSerializerGetNumSavepoints ( const serialboxSerializer_t * serializer )

Get number of registered savepoints.

Parameters

serializer Serializer to use

Returns: Number of registered savepoints

Definition at line 170 of file Serializer.cpp.

◆ serialboxSerializerGetPrefix()

SERIALBOX_API char* serialboxSerializerGetPrefix ( const serialboxSerializer_t * serializer )

Return the prefix of all filenames.

Parameters

serializer Serializer to use

Returns: newly allocated null-terminated string of the prefix of the Serializer

Definition at line 113 of file Serializer.cpp.

◆ serialboxSerializerGetSavepointVector()

SERIALBOX_API serialboxSavepoint_t** serialboxSerializerGetSavepointVector ( const serialboxSerializer_t * serializer )

Get an array of refrences to the registered savepoints.

To deallocate the vector use serialboxSerializerDestroySavepointVector.

Parameters

serializer	Serializer to use
name	Name of the Savepoint(s)

Returns: Newly allocated array of savepoints of length serialboxSerializerGetNumSavepoints

Definition at line 176 of file Serializer.cpp.

◆ serialboxSerializerHasField()

SERIALBOX_API int serialboxSerializerHasField	(	serialboxSerializer_t *	serializer,
		const char *	field
	)

Check if field is registered within the serializer.

Parameters

serializer	Serializer to use
field	Name of the field to search for

Returns: 1 if field exists, 0 otherwise

Definition at line 240 of file Serializer.cpp.

◆ serialboxSerializerHasSavepoint()

SERIALBOX_API int serialboxSerializerHasSavepoint	(	const serialboxSerializer_t *	serializer,
		const serialboxSavepoint_t *	savepoint
	)

Check if savepoint exists within the serializer.

Parameters

serializer	Serializer to use
savepoint	Savepoint to search for

Returns: 1 if savepoint exists, 0 otherwise

Definition at line 163 of file Serializer.cpp.

◆ serialboxSerializerRead()

SERIALBOX_API void serialboxSerializerRead	(	serialboxSerializer_t *	serializer,
		const char *	name,
		const serialboxSavepoint_t *	savepoint,
		void *	originPtr,
		const int *	strides,
		int	numStrides
	)

Deserialize field name (given by originPtr and strides) at savepoint from disk.

The origingPtr represent the memory location of the first element in the array i.e skipping all initial padding.

Parameters

name	Name of the field
savepoint	Savepoint to at which the field will be serialized
originPtr	Pointer to the origin of the data
strides	Array of strides of length `numStrides` (in unit-strides)
numStrides	Number of strides

Definition at line 404 of file Serializer.cpp.

◆ serialboxSerializerReadAsync()

SERIALBOX_API void serialboxSerializerReadAsync	(	serialboxSerializer_t *	serializer,
		const char *	name,
		const serialboxSavepoint_t *	savepoint,
		void *	originPtr,
		const int *	strides,
		int	numStrides
	)

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

The origingPtr represent the memory location of the first element in the array i.e skipping all initial padding. 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 serialboxSerializerWaitForAll.

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 to at which the field will be serialized
originPtr	Pointer to the origin of the data
strides	Array of strides of length `numStrides` (in unit-strides)
numStrides	Number of strides

See also: serialbox::SerializerImpl::readAsync

Definition at line 440 of file Serializer.cpp.

◆ serialboxSerializerReadSliced()

SERIALBOX_API void serialboxSerializerReadSliced	(	serialboxSerializer_t *	serializer,
		const char *	name,
		const serialboxSavepoint_t *	savepoint,
		void *	originPtr,
		const int *	strides,
		int	numStrides,
		const int *	slice
	)

Deserialize sliced field name (given by originPtr, strides and slice) at savepoint from disk.

The origingPtr represent the memory location of the first element in the array i.e skipping all initial padding. The slice is a N = 3 * numStrides array which contains the slice for each dimensions, meaning: {start1, stop1, step1, ... ,startN, stopN, stepN}.

Parameters

name	Name of the field
savepoint	Savepoint to at which the field will be serialized
originPtr	Pointer to the origin of the data
strides	Array of strides of length `numStrides` (in unit-strides)
numStrides	Number of strides
slice	Array of slices (i.e {start, stop, step}) of each dimension of length `3 * numStrides`

Definition at line 419 of file Serializer.cpp.

◆ serialboxSerializerUpdateMetaData()

SERIALBOX_API void serialboxSerializerUpdateMetaData ( serialboxSerializer_t * serializer )

Write meta-data to disk.

Parameters

serializer Serializer to use

Definition at line 118 of file Serializer.cpp.

◆ serialboxSerializerWrite()

SERIALBOX_API void serialboxSerializerWrite	(	serialboxSerializer_t *	serializer,
		const char *	name,
		const serialboxSavepoint_t *	savepoint,
		void *	originPtr,
		const int *	strides,
		int	numStrides
	)

Serialize field name (given by originPtr and strides) at savepoint to disk.

The savepoint will be registered at field name if not yet present. The origingPtr represent the memory location of the first element in the array i.e skipping all initial padding.

Parameters

name	Name of the field
savepoint	Savepoint to at which the field will be serialized
originPtr	Pointer to the origin of the data
strides	Array of strides of length `numStrides` (in unit-strides)
numStrides	Number of strides

Definition at line 389 of file Serializer.cpp.

◆ serialboxWriteToFile()

SERIALBOX_API void serialboxWriteToFile	(	const char *	filename,
		void *	originPtr,
		int	typeID,
		const int *	dims,
		int	numDims,
		const int *	strides,
		const char *	fieldname,
		const char *	archivename
	)

Serialize field name (given by originPtr and strides) directly to file.

If a file with filename already exists, it's contents will be discarded. The origingPtr represent the memory location of the first element in the array i.e skipping all initial padding.

Parameters

filename	Name of the file
originPtr	Pointer to the origin of the data
typeID	TypeID of the data
dims	Array of dimensions of length `numDims`
numDims	Number of dimensions
strides	Array of strides of length `numDims` (in unit-strides)
fieldname	Name of the field
archivename	Name of the archive used for serialization (e.g "Binary")

Definition at line 468 of file Serializer.cpp.