The GmStateDump class presents a higher level of abstraction over GmMemoryDump, storing accessor data, vector data or user buffers. More...

#include <gmStateDump.h>

Collaboration diagram for GmStateDump:

[legend]

Public Member Functions
	GmStateDump (const GmSimulationData *simulation)
	Constructor. Initializes the object with user options defined on the simulation object. More...

virtual	~GmStateDump ()
	Destructor.

void	setMode (GmMemoryDumpMode mode)
	Updates the dump mode. Must be called before the first call to addStateItem().

void	setSaveAndRestoreSupport (bool mode)
	Updates whether save and restore support is enabled or not. Must be called before the first call to addStateItem().

void	setDumpFile (QString file)
	Updates the name of the dump file (the given name is subjected to path translation). Must be called before the first call to addStateItem().

void	setCompression (int level, int minSize)
	Updates the compression level and the minimum size for which compression is desirable. Must be called before the first call to addStateItem().

void	setGrowFactors (double a, int b)
	Updates the grow factors applied for dump items expected to grow. Must be called before the first call to addStateItem().

void	setPrintStructure (bool mode)
	Updates the print structure mode. Must be called before the first call to addStateItem().

bool	loadUserDefinitions (LuaTable &table, QString &err)
	Parses from the given Lua table the user options for the dump object. Empty table fields do not change options. Must be called before the first call to addStateItem(). More...

int	addStateItem (GmValueAccessor ac, const GmMesh mesh, bool fixedHint, bool ownership=false, int groupId=-1, QString prefix="")
	Adds a standard node value accessor to the dump state. The fixed hint should determine if it is likely or not that the number of values in the accessor will change in the future or not. More...

int	addStateItem (GmCellAccessor ac, const GmMesh mesh, bool fixedHint, bool ownership=false, int groupId=-1, QString prefix="")
	addStateItem() overload for cell accessors

int	addStateItem (GmGaussAccessor ac, const GmMesh mesh, bool fixedHint, bool ownership=false, int groupId=-1, QString prefix="")
	addStateItem() overload for Gauss accessors

int	addStateItem (GmBoundaryConditionAccessor ac, const GmBoundaryCondition bc, bool fixedHint, bool ownership=false, int groupId=-1, QString prefix="")
	addStateItem() overload for Boundary condition accessors

int	addStateItem (GmVector *data, bool fixedHint, int groupId=-1, QString prefix="")
	Adds a GmVector to the dump state. The fixed hint should determine if it is likely or not that the number of values in the vector will change in the future or not. More...

int	addStateItem (GmMatrix *data, bool fixedHint, int groupId=-1, QString prefix="")
	Adds a GmMatrix to the dump state. The fixed hint should determine if it is likely or not that the matrix dimension will change in the future or not. More...

int	addStateItem (QVariantMap *data, bool fixedHint, int groupId=-1, QString prefix="")
	Adds to the dump state the contents of the given QVariantMap. More...

int	addStateItem (char *data, int size, int sizeMultiplier, bool fixedHint, int groupId=-1, QString prefix="")
	Adds a user data buffer to the dump state. More...

int	addStateItem (lua_State *L, const QStringList &globals, const QStringList &locals, QString localTabName, int groupId=-1, QString prefix="")
	Adds to the dump state the given Lua global and local variables. More...

int	addStateItem (FILE *fhandle, QString fileName, QString tempName, int groupId=-1, QString prefix="")
	Adds to the dump state the given file handle / file name with an optional temporary file name. See the description on GmStateDumpFileItem for an explanation of the saved data. Works only for files that are appended over time. More...

int	addStateItem (GmStateDumpBaseDataItem *item, int groupId=-1)
	Adds to the dump state the given dump item. More...

int	addGroupItem (GmGroupDumpItem *obj, int groupId=-1)
	Adds to the dump state the needed info from the given plugin (process, mesh, etc) returned handle. All the added items are combined into the same item group. More...

int	addGroupItem (GmBoundaryCondition *bc, int groupId=-1)
	Adds to the dump state the given boundary condition object. This includes any BC attributes. More...

int	addGroupItem (GmContactBoundaryCondition *cbc, int groupId=-1)

GmStateDumpBaseDataItem *	stateItem (int itemId) const
	Returns the state dump item associated with the given index.

int	stateItemGroup (int itemId) const
	Returns the group id of the given item.

int	numStateItems () const
	Returns the number of dump items added (can be greater than the number of addStateItem() calls)

int	findStateItem (QString name, int typeMask=0, int typeValue=0, int groupId=-1, int start=0)
	Finds the index of a state item identified by its name. See the GmMemoryDump::findItem() method documentation for more details.

void	setGroupActive (int groupId, bool active)
	Marks all items belonging to the given group as active / inactive. If groupId is -1, sets all items with the given mode. For use with saveActiveGroups() / loadActiveGroups(). More...

bool	init ()
	Completes the state dump object initialization after all calls to addStateItem()

bool	save ()
	Saves all the state dump items.

bool	load ()
	Loads all the state dump items.

bool	saveItem (int itemId, qint64 size=0, qint64 offset=0)
	Saves the data for a single dump item. Returns false on error. More...

bool	loadItem (int itemId, qint64 size=0, qint64 offset=0)
	Loads the data for a single dump item. Returns false on error. More...

bool	saveActiveGroups ()
	Saves the data from all the active groups.

bool	loadActiveGroups ()
	Loads the data from all the active items.

void	flush ()
	Ensure that the dump file (if any) is flushed. Meaningfull after individual saves.

void	clear ()
	Releases dump memory when dumping to memory.

const GmLogCategory &	logger () const
	Returns the logger used by the state dump object.

int	nextIdInGroup (int groupId)
	Returns the id for the next dump item to be added to the state for the given group. This method updates the id counter, so it should be called only once for each object effectively created. The given groupId follows the conventions for the addStateItem() calls. The first id for each group is 1.

Private Member Functions
int	addAcStateItem (GmValueAccessor ac, const GmMesh mesh, QString mapId, bool fixedHint, bool ownership, int groupId, QString prefix, bool *added)
	Work horse for adding accessor state items to the dump state. More...

void	newmd ()
	Aux function that, on its first call, creates the _md object.

bool	notifyGroupObjects (bool load, bool done, bool activeOnly)
	Notifies every object in _groupItems of the start / end of load / save operations. If any object returns false, aborts the notifications and returns false. Otherwise, returns true. If activeOnly is true, only items marked as active will be notified.

Private Attributes
GmMemoryDumpMode	_mode
	The dump mode.

bool	_saveAndRestoreSupport
	Does the state needs to support a saving and later restore pattern?

QString	_dumpFile
	The dump file.

int	_compression
	The desired compression level (0 = no, 9 = maz, -1 = zlib default)

int	_compressionMinSize
	The minimum size for which compression makes sense (must be > 0)

double	_growAFactor
	'a' grow factor in ax + b

int	_growBFactor
	'b' grow factor in ax + b

bool	_printStructure
	Should the dump items structure be printed on init()?

const GmSimulationData *	_simulation
	The simulation object.

GmLogCategory	_logger
	Basic logger object for state dump messages.

GmMemoryDump *	_md
	The memory dump object responsible for the actual dumping.

bool	_init
	Has this object been initialized (init() was called?)

QMap< int, int >	_currIdInGroup
	Map storing, per group id, the index of its last added item.

QVector< int >	_funcItems
	The set of function dump item ids.

QMap< QString, int >	_acMap
	Map keeping track of the already added accessors to the state dump.

QVector< GmValueAccessor * >	_ownedValueAccessors
	A set of value accessors owned by the state dump object.

QVector< GmAccessorProxy * >	_ownedProxyAccessors
	A set of cell, Gauss and BC accessors owned by the state dump object.

QVector< GmGroupDumpItem * >	_ownedGroupItems
	A set of group items owned by the state dump object.

QMap< int, QPair< GmGroupDumpItem *, bool > >	_groupItems
	A map, indexed by group index storing the associated group dump item and a flag stating if this group is active or not.

Detailed Description

The GmStateDump class presents a higher level of abstraction over GmMemoryDump, storing accessor data, vector data or user buffers.

Constructor & Destructor Documentation

◆ GmStateDump()

GmStateDump::GmStateDump ( const GmSimulationData * simulation )

Constructor. Initializes the object with user options defined on the simulation object.

After construction, object options can be changed by a call to loadUserDefinitions() or by calls to setXxxx() functions. Those must be done before calls to addStateItem() functions. After the last item is added, init() must be called.

Member Function Documentation

◆ addAcStateItem()

int GmStateDump::addAcStateItem	(	GmValueAccessor *	ac,
		const GmMesh *	mesh,
		QString	mapId,
		bool	fixedHint,
		bool	ownership,
		int	groupId,
		QString	prefix,
		bool *	added
	)

private

Work horse for adding accessor state items to the dump state.

The mesh parameter is required for ghost accessor handling only. The mapId is the prefix used to identify the object that contains this accessor (mesh or bc).

The added parameter, if given, is filled with true if this is a new accessor or false if it was a reused one.

See the addStateItem description for the other parameters.

◆ addGroupItem() [1/2]

int GmStateDump::addGroupItem	(	GmGroupDumpItem *	obj,
		int	groupId = `-1`
	)

Adds to the dump state the needed info from the given plugin (process, mesh, etc) returned handle. All the added items are combined into the same item group.

The returned value is the effective group Id (which can be different from the given parameter if -1 (next group) or -2 (corrent group) is given) used to combine the added items or -1 on error.

Please do not mistake the returned group id with item ids that are returned by addStateItem().

IMPORTANT: The target group Id can NOT be shared with another GmGroupDumpItem object.

◆ addGroupItem() [2/2]

int GmStateDump::addGroupItem	(	GmBoundaryCondition *	bc,
		int	groupId = `-1`
	)

Adds to the dump state the given boundary condition object. This includes any BC attributes.

The returned value is the effective group Id (which can be different from the given parameter if -1 (next group) or -2 (corrent group) is given) used to combine the added items or -1 on error.

Please do not mistake the returned group id with item ids that are returned by addStateItem().

IMPORTANT: The target group Id can NOT be shared with another GmGroupDumpItem object.

◆ addStateItem() [1/8]

int GmStateDump::addStateItem	(	GmValueAccessor *	ac,
		const GmMesh *	mesh,
		bool	fixedHint,
		bool	ownership = `false`,
		int	groupId = `-1`,
		QString	prefix = `""`
	)

Adds a standard node value accessor to the dump state. The fixed hint should determine if it is likely or not that the number of values in the accessor will change in the future or not.

The returned value is an id that can be used on calls saveItem() and loadItem() to identify the dump item associated with the given accessor. Returns -1 if the accessor could not be added. Currently, only accessor implementations based on a ValueSetData or Ghost node accessors are supported.

If the state already includes an equivalent accessor, no duplicates are created and this function returns the same id of the original added item.

If ownership is set to true, the accessor will be deleted together with the state dump object. If the state already included an equivalent accessor, the new one will be deleted imediately.

The groupId defines the group that this item will belong. A value of -1 means "next group" while -2 means "last added item group". If the accessor is broken into several items (ghost / function support), all the items will be in the same group. The prefix can be used to change the default item name prefix.

◆ addStateItem() [2/8]

int GmStateDump::addStateItem	(	GmVector *	data,
		bool	fixedHint,
		int	groupId = `-1`,
		QString	prefix = `""`
	)

Adds a GmVector to the dump state. The fixed hint should determine if it is likely or not that the number of values in the vector will change in the future or not.

The groupId defines the group that this item will belong. A value of -1 means "next group" while -2 means "last added item group". The prefix can be used to change the default item name prefix.

The returned value is an id that can be used on calls to saveItem() and loadItem() to identify the dump item associated with the given vector.

◆ addStateItem() [3/8]

int GmStateDump::addStateItem	(	GmMatrix *	data,
		bool	fixedHint,
		int	groupId = `-1`,
		QString	prefix = `""`
	)

Adds a GmMatrix to the dump state. The fixed hint should determine if it is likely or not that the matrix dimension will change in the future or not.

The groupId defines the group that this item will belong. A value of -1 means "next group" while -2 means "last added item group". The prefix can be used to change the default item name prefix.

The returned value is an id that can be used on calls saveItem() and loadItem() to identify the dump item associated with the given vector.

◆ addStateItem() [4/8]

int GmStateDump::addStateItem	(	QVariantMap *	data,
		bool	fixedHint,
		int	groupId = `-1`,
		QString	prefix = `""`
	)

Adds to the dump state the contents of the given QVariantMap.

The contents to be saved is evaluated at save time. On loading, the map is filled with the recovered data. The data stored on the map must be serializable using a QDataStream.

The fixed hint should determine if it is likely or not that the map contents will change in the future or not. Keep in mind that it refers to the "serialized size" and not to the number of map items, so in general it should be set to false.

The groupId defines the group that this item will belong. A value of -1 means "next group" while -2 means "last added item group". The prefix can be used to change the default item name prefix.

The returned value is an id that can be used on calls saveItem() and loadItem() to identify the dump item associated with the given vector.

◆ addStateItem() [5/8]

int GmStateDump::addStateItem	(	char **	data,
		int *	size,
		int	sizeMultiplier,
		bool	fixedHint,
		int	groupId = `-1`,
		QString	prefix = `""`
	)

Adds a user data buffer to the dump state.

By storing a pointer to the buffer pointer and a pointer to the buffer size, allows for a dump item that can follow reallocated buffers. The size multiplier is used to transform the size value into bytes.

If you want to add another buffer to the same item, just get the added item using stateItem(), cast it to a GmStateDumpBufferDataItem* pointer and use addBuffer() or, better still, create your own GmStateDumpBufferDataItem object and add it through addStateItem(GmStateDumpBaseDataItem*).

The groupId defines the group that this item will belong. A value of -1 means "next group" while -2 means "last added item group". The prefix can be used to change the default item name prefix.

The returned value is an id that can be used on calls saveItem() and loadItem() to identify the dump item associated with the given user buffer.

◆ addStateItem() [6/8]

int GmStateDump::addStateItem	(	lua_State *	L,
		const QStringList &	globals,
		const QStringList &	locals,
		QString	localTabName,
		int	groupId = `-1`,
		QString	prefix = `""`
	)

Adds to the dump state the given Lua global and local variables.

Variables that can be stored must have values that can be properly serialized. That excludes functions and user data objects. Allowed values are: numbers, strings, boolean, nil and tables with number and string keys whose values are accepted. Can not have cycles.

When storing local values, the given variables MUST be in scope when the save operation is called. Upon loading, the values are stored in the global table indicated by localTabName, indexed by the local variable name. They are NOT restored to locals in scope when the load is done since they are usually not the same.

Parameters

L	The Lua state
globals	A list with the name of the global variables to be saved/loaded
locals	A list with the name of the local variables to be saved/loaded. Variables must be in scope when save() is called.
localTabName	The name of the global table that will be used to store the loaded local variables upon a load() operation. This table is also used as an auxiliary table during save() operations.
groupId	Defines the group that this item will belong. A value of -1 means "next group" while -2 means "last added item group". \prama prefix Optional parameter that can be used to change the default item name prefix.

Returns: The returned value is an id that can be used on calls saveItem() and loadItem() to identify the dump item associated with the given Lua values.

◆ addStateItem() [7/8]

int GmStateDump::addStateItem	(	FILE *	fhandle,
		QString	fileName,
		QString	tempName,
		int	groupId = `-1`,
		QString	prefix = `""`
	)

Adds to the dump state the given file handle / file name with an optional temporary file name. See the description on GmStateDumpFileItem for an explanation of the saved data. Works only for files that are appended over time.

Parameters

fhandle	The file handle
fileName	The main file anme
tempName	The name of the optional temporary file used instead of fileName
groupId	Defines the group that this item will belong. A value of -1 means "next group" while -2 means "last added item group". \prama prefix Optional parameter that can be used to change the default item name prefix.

Returns: The returned value is an id that can be used on calls saveItem() and loadItem() to identify the dump item associated with the given file.

◆ addStateItem() [8/8]

int GmStateDump::addStateItem	(	GmStateDumpBaseDataItem *	item,
		int	groupId = `-1`
	)

Adds to the dump state the given dump item.

Important: The dump item should have been created with an id returned by a call to nextIdInGroup(groupId).

The returned value is an id that can be used on calls saveItem() and loadItem() to identify the given dump item .

◆ loadItem()

bool GmStateDump::loadItem	(	int	itemId,
		qint64	size = `0`,
		qint64	offset = `0`
	)

Loads the data for a single dump item. Returns false on error.

The item id is the value returned by the call to addStateItem(). If size is diferent from zero, only part of the item data will be loaded (defined by the given size and offset).

If the dump item does not supports partial operation (partialOp() returns false) and size / offset are different from 0, the operation fails. Partial loads are supported for accessor and vector items, but not for user items.

The size and offset parameters are given as the number of entries, and NOT in bytes. When working with ghost accessors, offset must behave like a linear index.

◆ loadUserDefinitions()

bool GmStateDump::loadUserDefinitions	(	LuaTable &	table,
		QString &	err
	)

Parses from the given Lua table the user options for the dump object. Empty table fields do not change options. Must be called before the first call to addStateItem().

If the table contains invalid options, fills err with a message for each invalid option and returns false. Valid options are applied.

Parsed fields are:

mode: Defines if the dump will be done to file or memory. Accepted values are 'file', 'memory', 'restore' or 'auto' (file or memory depending on memory availability)
file: Dump file name. Can include macros.
saveAndRestore: meaningfull only for file dumps and should be set to true if this dump state will be used to save a simulation state that can be later loaded in another GeMA execution, false if that is not needed. Setting it to false makes the state simpler when the saved accessors support function values.
compression: Integer between -1 and 9 . 0 = no compression, 9 = maximum compression and -1 = zlib default compression level.
compressionMinSize: Minimum data size (in bytes) for compression to be applied. If given, it must be > 0.
growFactorA: A growing factor. See GmMemoryDump class description.
growFactorB: B growing factor. See GmMemoryDump class description.
printStructure: Should the dump item structure be printed on init()?

◆ saveItem()

bool GmStateDump::saveItem	(	int	itemId,
		qint64	size = `0`,
		qint64	offset = `0`
	)

Saves the data for a single dump item. Returns false on error.

The item id is the value returned by the call to addStateItem(). If size is diferent from zero, only part of the item data will be saved (defined by the given size and offset). Although an update, this can extend the item size, but in that case it MUST span all the new part of the data.

If the dump item does not supports partial operation (partialOp() returns false) and size / offset are different from 0, the operation fails. Partial updates are supported for accessor and vector items, but not for user items.

The size and offset parameters are given as the number of entries, and NOT in bytes. When working with ghost accessors, offset must behave like a linear index.

◆ setGroupActive()

void GmStateDump::setGroupActive	(	int	groupId,
		bool	active
	)

Marks all items belonging to the given group as active / inactive. If groupId is -1, sets all items with the given mode. For use with saveActiveGroups() / loadActiveGroups().

Important: The GmStateDump class does not exposes the setItemActive() interface due to the difficuty of notifying plugin objects in such scenario. By only allowing whole groups to be activated/deactivated, we can correctly notify the active plugin items on saveActiveGroups() / loadActiveGroups()

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

inc/gmStateDump.h
src/gmStateDump.cpp

Public Member Functions

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ GmStateDump()

Member Function Documentation

◆ addAcStateItem()

◆ addGroupItem() [1/2]

◆ addGroupItem() [2/2]

◆ addStateItem() [1/8]

◆ addStateItem() [2/8]

◆ addStateItem() [3/8]

◆ addStateItem() [4/8]

◆ addStateItem() [5/8]

◆ addStateItem() [6/8]

◆ addStateItem() [7/8]

◆ addStateItem() [8/8]

◆ loadItem()

◆ loadUserDefinitions()

◆ saveItem()

◆ setGroupActive()