A Snapshot object can be used to send the data from a state snapshot, i.e. More...

#include <Snapshot.hxx>

Inheritance diagram for dueca::Snapshot:

Collaboration diagram for dueca::Snapshot:

[legend]

Public Types
enum	SnapCoding { UnSpecified , Base64 , JSON , XML , Floats , Doubles , BinaryFile , FloatFile , DoubleFile , JSONFile , XMLFile , Base64File }
	Enumerated type for an automatically generated object class. More...

typedef Snapshot	__ThisDCOType__
	typedef for internal reference

Public Member Functions
	Snapshot ()
	default constructor.

	Snapshot (const dueca::smartstring &data, const NameSet &originator, const SnapCoding &coding)
	Constructor with arguments.

	Snapshot (const Snapshot &o)
	copy constructor.

	Snapshot (::dueca::AmorphReStore &r)
	constructor to restore an Snapshot from amorphous storage.

	~Snapshot ()
	destructor.

void	packData (::dueca::AmorphStore &s) const
	packs the Snapshot into amorphous storage.

void	packDataDiff (::dueca::AmorphStore &s, const Snapshot &ref) const
	packs the Snapshot into amorphous storage.

void	unPackData (::dueca::AmorphReStore &s)
	unpacks the Snapshot from an amorphous storage.

void	unPackDataDiff (::dueca::AmorphReStore &s)
	unpacks the differences for Snapshot from an amorphous storage.

bool	operator== (const Snapshot &o) const
	Test for equality.

bool	operator!= (const Snapshot &o) const
	Test for inequality.

Snapshot &	operator= (const Snapshot &o)
	Assignment operator.

std::ostream &	print (std::ostream &s) const
	prints the Snapshot to a stream.

	Snapshot (size_t data_size, SnapCoding coding=UnSpecified)
	Constructor.

	Snapshot (dueca::DataWriterArraySize data_size, SnapCoding coding=UnSpecified)
	Constructor.

	Snapshot (size_t data_size, const NameSet &originator, SnapCoding coding=UnSpecified)
	Constructor.

	Snapshot (const toml::value &coded)
	Constructor from a toml-parsed object.

toml::value	tomlCode (const std::string &fname=std::string()) const
	Create a toml object.

bool	saveExternal () const
	return true if the snapshot is to be saved in an external file

const char *	fileExtension () const
	Return an appropriate extension for an external file.

const char *	accessData () const
	This directly accesses the data area of the snapshot.

char *	accessData ()
	This directly accesses the data area of the snapshot.

char *	AllocAndAccessData (uint32_t dsize)
	This initializes, and subsequently accesses the data area of the snapshot.

uint32_t	getDataSize () const
	Read back the maximum size of the data.

std::string	getSample (unsigned size=20) const
	Return the complete snapshot, or a sample.

Static Public Member Functions
static void *	operator new (size_t size)
	new operator "new", which places objects not on a heap, but in one of the memory arenas.

static void *	operator new (size_t size, void *mem)
	accompanying placement operator "new"

static void	operator delete (void *p)
	new operator "delete", to go with the new version of operator new.

static void *	operator new (size_t size, Snapshot *&o)
	placement "new", needed for stl.

Public Attributes
dueca::smartstring	data
	A place for the data, variable size.

NameSet	originator
	Identifies the object that sent the snapshot.

SnapCoding	coding
	Snapshot encoding, if specified.

size_t	data_size
	For convenience, additional data_size member.

Static Public Attributes
static const char *const	classname
	The name of this class.

static const uint32_t	magic_check_number
	a "magic" number, hashed out of the class definition, that will be used to check consistency of the sent objects across the dueca nodes.

Detailed Description

A Snapshot object can be used to send the data from a state snapshot, i.e.

the data describing a (piece of) your model state in time, to a repository for snapshot, and conversely, for sending this data back to a SimulationModule, for restoration of an old state.

The Snapshot object allocates a data buffer for you. It is possible to use an AmorphStore object to pack the data in this buffer, like:

// make a snapshot to send later
// note that "DoubleFile" is just one of the options for storage,
// Binary and Base64 would also work here
Snapshot *snap = new Snapshot(5 * sizeof(double), getNameSet(),
                              Snapshot::DoubleFile);
// and an AmorphStore to pack the data in there
AmorphStore s(snap->accessData(), snap->getDataSize());
 
// pack the state
for (int ii = 5; ii--; ) {
  packData(s, my_x_copy[ii]);
}
 
// done, can now send off the snapshot.

Alternatively, the snapshot can be packed with JSON or XML data. The "data" member in the snapshot is a smart string that can be easily fed with data, first a JSON example, using rapidjson:

// somewhere appropriate, include json
#include "rapidjson/writer.h"
using namespace rapidjson;
 
// make a snapshot, initially empty string
Snapshot *snap = new Snapshot("", getNameSet(), Snapshot::JSON);
// the data object in the snapshot can be used in combination with
// a json writer, the following gives an appropriate standard writer:
smartstring::json_string_writer writer(snap->data);
 
// now code the data; using an array here. Of course you can use
// other formats as well, e.g., Object. See the rapidjson documentation
writer.StartArray()
for (int ii = 5; ii--; ) {
  writer.Double(my_x_copy[ii]);
}
writer.EndArray();
 
// done, can now send off the snapshot.

The same can be done with XML, using pugixml. Of course, you might encounter code with the "old" XMLSnapshot approach, that produces equally valid XML

// somewhere appropriate, include pugixml
#include <pugixml.hpp>
using namespace pugi;   // or prefix variables with pugi
 
// make a snapshot, initially empty string
Snapshot *snap = new Snapshot("", getNameSet(), Snapshot::XML);
 
// the data object in the snapshot can be used in combination with
// an xml writer, the following gives an appropriate standard writer:
smartstring::xml_string_writer writer(snap->data);
 
// now code the data; the convention/layout of the XML is your choice.
// See also the pugixml documentation
xml_document doc;
xml_node root = doc.child("state")
for (int ii = 5; ii--; ) {
  xml_node element = root.child("value");
  xml_attribute idx = element.attribute("idx");
  idx.set_value(ii);
  element.set_value(my_x_copy[ii]);
}
 
// this saves the created XML document to the smartstring in the
// snapshot object.
doc.save(writer);
 
// done, can now send off the snapshot.

Member Enumeration Documentation

◆ SnapCoding

enum dueca::Snapshot::SnapCoding

Enumerated type for an automatically generated object class.

Enumerator
UnSpecified	old-style, no indication about coding. Treated as Base64
Base64	probably AmorphStore coded binary, stored in Base64 in toml
JSON	data directly encoded and stored as JSON string in inco toml
XML	data directly encoded and stored as XML string in inco toml
Floats	data encoded in AmorphStore, all floats, stored in toml
Doubles	data encoded in AmorphStore, all doubles, stored in toml
BinaryFile	External binary file, binary storage, no information on format.
FloatFile	External ASCII formatted file, data AmorphStore packed as floats.
DoubleFile	External ASCII formatted file, data AmorphStore packed as double.
JSONFile	data directly encoded and stored as JSON string in external file
XMLFile	data directly encoded and stored as XML string in external file
Base64File	data stored in Base64 in external file

Constructor & Destructor Documentation

◆ Snapshot() [1/3]

dueca::Snapshot::Snapshot	(	size_t	data_size,
		SnapCoding	coding = UnSpecified )

Constructor.

The Snapshot constructor at this point allocates room for the data you want to send. Use the accessData() method to access this room. Careful! There is no protection here, please don't mis-use or your application might fail.

◆ Snapshot() [2/3]

dueca::Snapshot::Snapshot	(	dueca::DataWriterArraySize	data_size,
		SnapCoding	coding = UnSpecified )

Constructor.

The Snapshot constructor at this point allocates room for the data you want to send. Use the accessData() method to access this room. Careful! There is no protection here, please don't mis-use or your application might fail.

◆ Snapshot() [3/3]

dueca::Snapshot::Snapshot	(	size_t	data_size,
		const NameSet &	originator,
		SnapCoding	coding = UnSpecified )

Constructor.

The Snapshot constructor at this point allocates room for the data you want to send. Use the accessData() method to access this room. Careful! There is no protection here, please don't mis-use or your application might fail.

Member Function Documentation

◆ operator new()

static void * dueca::Snapshot::operator new ( size_t size )

static

new operator "new", which places objects not on a heap, but in one of the memory arenas.

This to speed up memory management.

◆ packDataDiff()

void dueca::Snapshot::packDataDiff	(	::dueca::AmorphStore &	s,
		const Snapshot &	ref ) const

packs the Snapshot into amorphous storage.

only differences with a previous object are packed.

◆ accessData() [1/2]

const char * dueca::Snapshot::accessData ( ) const

inline

This directly accesses the data area of the snapshot.

Please be careful, there is no protection here.

◆ accessData() [2/2]

char * dueca::Snapshot::accessData ( )

inline

This directly accesses the data area of the snapshot.

Please be careful, there is no protection here.

◆ AllocAndAccessData()

char * dueca::Snapshot::AllocAndAccessData ( uint32_t dsize )

inline

This initializes, and subsequently accesses the data area of the snapshot.

Please be careful, there is no protection here.

Member Data Documentation

◆ data

dueca::smartstring dueca::Snapshot::data

A place for the data, variable size.

Use this with ASCII converted data (XML, JSON), or use an AmorphStore to pack as binary data.

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

/home/abuild/rpmbuild/BUILD/dueca-4.2.1-build/dueca-4.2.1/redhat-linux-build/dusime/Snapshot.hxx

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Detailed Description

Member Enumeration Documentation

◆ SnapCoding

Constructor & Destructor Documentation

◆ Snapshot() [1/3]

◆ Snapshot() [2/3]

◆ Snapshot() [3/3]

Member Function Documentation

◆ operator new()

◆ packDataDiff()

◆ accessData() [1/2]

◆ accessData() [2/2]

◆ AllocAndAccessData()

Member Data Documentation

◆ data