DDFFDataRecorder Class Reference

Recording/replay facility for storing data in simulation replay. More...

#include <DDFFDataRecorder.hxx>

Public Types
typedef DDFFDataRecorder *	pointer
	Pointer type.
typedef std::map< std::string, std::list< pointer > >	recordermap_t
	Type to organize all DataRecorder objects in a node.

Public Member Functions
	DDFFDataRecorder ()
	Constructor.
bool	complete (const std::string &entity, const ChannelWriteToken &w_token, const std::string &key=std::string(""))
	Complete; i.e., connect to the file storage.
bool	complete (const std::string &entity, const std::string &key, const std::string &data_class=std::string(""))
	Complete; i.e., connect to the file storage.
template<typename DCO >
bool	replay (const DataTimeSpec &ts, DCO &object, DataTimeSpec &object_ts)
	Replay "stream" data into a DCO object.
template<typename DCO >
bool	replay (const DataTimeSpec &ts, DCO &object)
	Replay "stream" data into a DCO object.
template<typename DCO >
void	record (const DataTimeSpec &ts, const DCO &object)
	Record data from a DCO object.
void	channelRecord (const DataTimeSpec &ts, CommObjectWriter &writer)
	Record data from a generic data writer.
unsigned	channelReplay (const DataTimeSpec &ts, ChannelWriteToken &w_token)
	Replay previously recorded data into a write channel.
void	markRecord (const DataTimeSpec &ts)
	Mark until where data recording is complete.
	~DDFFDataRecorder ()
	Destructor.
bool	isValid ()
	Is connected, valid, etc.
void	startStretch (TimeTickType tick)
	Starting a new stretch; will mark the first data written in this stretch (if any) for callback with the offset of that data.
unsigned	getStreamId () const
	Get the associated stream id.
void	startReplay (TimeTickType tick)
	Starting a new replay; provide offset for the replayed data.
void	spoolReplay (ddff::FileHandler::pos_type offset, ddff::FileHandler::pos_type end_offset)
	Control spooling replay position.
bool	checkWriteTick (TimeTickType tick)
	Check write status, before forcing a flush of the file.
void	syncRecorder ()
	Initiate syncing of the data to disk.
bool	checkAndMakeClean ()
	Check and possibly reset the dirty flag.

Static Public Member Functions
static recordermap_t &	allRecorders ()
	Get the map with recorders.

Friends
class	ddff::FileWithSegments
class	ReplayFiler
	The ReplayFiler needs access to its own recorders.

Detailed Description

Recording/replay facility for storing data in simulation replay.

To enable recording and replay, all DUECA modules that "generate" fresh data, e.g., a control loading module, or a module reading stick/ buttons/screens in a simulator etc., need to record the data generated and sent in a session, and be able to retrieve and replay that data in replay mode. Often it is enough to record the data sent over channels, but it may also be necessary, e.g., to have control loading devices mimic the previously generated motion, to record additional data. Decide what you need for full replay, and create one or more DDFFDataRecorder objects in your module to record the data and access the replay.

DDFFDataRecorder     my_recorder;

If your recorder directly records the data sent over a channel, the recorder needs to be "completed" in the isPrepared call for your module, after the channel has become valid, an example:

bool MyModule::isPrepared()
{
  bool res = true;
  // first check the token(s)
  CHECK_TOKEN(w_mytoken);
 
  // if token(s) OK, call the complete for the recorder(s)
  if (res) {
    my_recorder.complete(getEntity(), w_mytoken);
  }
 
  // now check recorders ok
  CHECK_RECORDER(my_recorder);
 
  // result
  return res;
}

If you need to record additional data, not sent over a channel, create a recorder directly for a DCO datatype, in that case, the complete call changes a little, and is not dependent on a channel state:

my_other_recorder.complete(getEntity(),
                           "some unique key for the recorder",
                           "SomeDCODataClass");
CHECK_RECORDER(my_other_recorder);

In the "Advance" mode of the simulation, use the record call to record the data of the DCO object you are about to write:

my_recorder.record(ts, dco_object);

or directly when writing (note, do not record in HoldCurrent:

DataWriter<MyObject> dw(w_mytoken, ts);
// write the data to dw.data() ...
if (getCurrentState() == SimulationState::Advance) {
  my_recorder.record(dw.data(), ts);
}

When in the "Replay" mode, the recorder's "replay" method can be used to retrieve the previously stored data.

Member Function Documentation

complete() [1/2]

bool DDFFDataRecorder::complete	(	const std::string &	entity,
		const ChannelWriteToken &	w_token,
		const std::string &	key = std::string("") )

Complete; i.e., connect to the file storage.

Use this version of the complete call when your have data to store that is written as-is such to a channel. The channelRecord and ChannelReplay functions will be operational, as well as the replay and record functions.

Parameters

entity	Entity name of the module requesting this connection.
w_token	Token for a channel of which the data is to be stored. The channel name and entry label will be used to create an identifying string for the data stream.
key	Optional, alternative key for the recording. The default key would be made from the channel name and entry label, separated with a semicolon (;). Note that recording keys must be unique, and persistent across simulation runs.

Returns

True, if connection correct.

complete() [2/2]

bool DDFFDataRecorder::complete	(	const std::string &	entity,
		const std::string &	key,
		const std::string &	data_class = std::string("") )

Complete; i.e., connect to the file storage.

Use this version of the complete call when the data you want to save and restore is not written as-is to a channel, e.g., because you store and save a composite object, part is re-written as replay, part is used for user feedback, for example in driving a control-loaded device. Only the replay and record functions will be available.

Parameters

entity	Entity name.
key	Identifying string for the data stream.
data_class	Class of data to be written/read

Returns

True, if connection correct.

replay() [1/2]

template<typename DCO >

bool DDFFDataRecorder::replay ( const DataTimeSpec & ts, DCO & object, DataTimeSpec & object_ts )

inline

Replay "stream" data into a DCO object.

Parameters

ts	Time specification of the writing process.
object	Filled with the object data
object_ts	Filled with the time specification for the object

Returns

True, if data returned for this time spec. Note that for event-type data, multiple events may be available for the same time; repeat reading until false is returned.

replay() [2/2]

template<typename DCO >

bool DDFFDataRecorder::replay ( const DataTimeSpec & ts, DCO & object )

inline

Replay "stream" data into a DCO object.

This variant has no interest in the effective timing of the data.

Parameters

ts	Time specification of the writing process.
object	Filled with the object data

Returns

True, if data returned for this time spec. Note that for event-type data, multiple events may be available for the same time; repeat reading until false is returned.

record()

template<typename DCO >

void DDFFDataRecorder::record ( const DataTimeSpec & ts, const DCO & object )

inline

Record data from a DCO object.

Template Parameters

DCO	A packable (with msgpack) object.

Parameters

ts	Time for which data is recorded; the end of the period is also used to mark until when recording is complete.
object	DCO object to save.

channelRecord()

void DDFFDataRecorder::channelRecord	(	const DataTimeSpec &	ts,
		CommObjectWriter &	writer )

Record data from a generic data writer.

Parameters

ts	Time for which data is recorded; the end of the period is also used to mark until when recording is complete.
writer	Communication object writer.

channelReplay()

unsigned DDFFDataRecorder::channelReplay	(	const DataTimeSpec &	ts,
		ChannelWriteToken &	w_token )

Replay previously recorded data into a write channel.

The replay considers the requested replay time, in combination with the offset (compared to recorded data), defined through the startReplay call.

Parameters

ts	Time for which data is to be replayed.
w_token	Channel write token.

Returns

Number of replayed data points; the replay looks at the given time specification and replays all data corresponding to this specification. In case of event replay, this can result in zero, one or multiple events replayed. For stream channels, you should keep the replay rate (ts) matching the recording, so typically one data point is replayed.

markRecord()

void DDFFDataRecorder::markRecord ( const DataTimeSpec & ts )

inline

Mark until where data recording is complete.

Use this for recording of event data. When recording stream data, the record or channelRecord functions will already do this.

Parameters

ts	Time for which recording is complete

spoolReplay()

void DDFFDataRecorder::spoolReplay	(	ddff::FileHandler::pos_type	offset,
		ddff::FileHandler::pos_type	end_offset )

Control spooling replay position.

Parameters

offset	Location in file where data starts
end_offset	Location in file where data ends.

checkWriteTick()

bool DDFFDataRecorder::checkWriteTick

(

TimeTickType

tick

)

Check write status, before forcing a flush of the file.

Parameters

tick	End time for which writing should be complete.

Returns

"true", if written until tick.

checkAndMakeClean()

bool DDFFDataRecorder::checkAndMakeClean

(

)

Check and possibly reset the dirty flag.

Returns

true if already clean (meaning that tag offset can stay 0), otherwise returns false, and tag offset should have a value.

---

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

• /home/abuild/rpmbuild/BUILD/dueca-4.1.3/ddff/DDFFDataRecorder.hxx