DDFFDataRecorder Class Reference

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

Inheritance diagram for DDFFDataRecorder:

Collaboration diagram for DDFFDataRecorder:

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. More...
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. More...
template<typename DCO >
bool	replay (const DataTimeSpec &ts, DCO &object, DataTimeSpec &object_ts)
	Replay "stream" data into a DCO object. More...
template<typename DCO >
bool	replay (const DataTimeSpec &ts, DCO &object)
	Replay "stream" data into a DCO object. More...
template<typename DCO >
void	record (const DataTimeSpec &ts, const DCO &object)
	Record data from a DCO object. More...
void	channelRecord (const DataTimeSpec &ts, const CommObjectWriter &writer)
	Record data from a generic data writer. More...
unsigned	channelReplay (const DataTimeSpec &ts, ChannelWriteToken &w_token)
	Replay previously recorded data into a write channel. More...
void	markRecord (const DataTimeSpec &ts)
	Mark until where data recording is complete. More...
	~DDFFDataRecorder ()
	Destructor.
bool	isValid ()
	Is connected, valid, etc.
unsigned	getStreamId () const
	Get the associated stream id.
void	startReplay (TimeTickType tick) final
	Starting a new replay; provide offset for the replayed data.
void	spoolReplay (ddff::FileHandler::pos_type offset, ddff::FileHandler::pos_type end_offset, TimeTickType replay_record_tick, unsigned inblock_offset) final
	Control spooling replay position. More...

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, my_dco);

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

DataWriter<MyObject> dw(w_mytoken, ts);
// write the data to dw.data() as normal ...
 
// only when in advance, use the written data for the recording
if (getCurrentState() == SimulationState::Advance) {
  my_recorder.record(ts, dw.data());
}

If you need to record the data from an event (which you will normally only now and then write, or even repeatedly in a single time span), make sure that the time span you specify when recording is 0, and use the markRecord() function in each cycle to indicate that you passed the given time:

while (writing_my_event) {
  DataWriter<MyObject> dw(w_mytoken, ts);
  // write the data to dw.data(), etc. ...
  if (getCurrentState() == SimulationState::Advance) {
    my_recorder.record(ts.getValidityStart(), dw.data());
  }
}
 
// make sure that the recording is marked as complete for this
// update
if (getCurrentState() == SimulationState::Advance) {
  my_recorder.markRecord(ts);
}

When in the "Replay" mode, the recorder's "replay" method can be used to explicitly retrieve the previously stored data. In the following example, we assume an event object, when there is an event for the given time span, the replay call returns true.

if (getCurrentState() == SimulationState::Replay) {
  MyObject obj;
  DataTimeSpec ts2;
  while (my_recorder.replay(ts, obj, ts2)) {
 
    // an event was sent in the recording, resend it in the replay
    DataWriter<MyObject> dw(w_mytoken, ts2);
    dw.data() = obj;
 
    // and do whatever else you want with obj, flashing lights
    // auditory feedback, or whatever you did during the recording
    ....
  }
}

Of course, if you wrote and recorded a stream channel, you may assume that the data is there during replay, ignore the returned boolean, and call replay only once.

If you only want to write the data to the channel again, and you don't need to access the data in the module, you can use the channelReplay method. This handles event or stream channels in the proper fashion, and simplifies your work:

if (getCurrentState() == SimulationState::Replay) {
  my_recorder.channelReplay(ts, w_mytoken);
}

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. If you are recording event data, and want that read back as event data, use a span of 0, and call markRecord in each cycle.
object	DCO object to save.

channelRecord()

void DDFFDataRecorder::channelRecord	(	const DataTimeSpec &	ts,
		const 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, TimeTickType  replay_record_tick, unsigned  inblock_offset  )

final

Control spooling replay position.

Parameters

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

---

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

• /usr/src/packages/BUILD/ddff/DDFFDataRecorder.hxx