API Documentation

Logfile

PolySync uses a distributed Record and Replay system to handle system-level data logging/replay. All participating nodes use the Logfile API to facilitate the RnR functionality.

The API uses the term “session” to refer to the collection of files associated with a given logging session (across the entire PolySync Runtime). Sessions are identified by their “session timestamp,” which corresponds to the UTC microsecond time the session was started.

Users can use arbitrary session time values, they are used to create directory names on each host that stores the actual files.

Sessions are strongly bound to the System Design File (SDF) they were produced with. The actual files are identified by the node that produced them.

Logfiles are a binary file type, and use the naming convention:

<node_name>.<node_guid>.plog

In the above example, if the user wanted to instruct all five nodes to replay the session they would use the RnR API to send commands to the nodes. These commands are provided to the Logfile API, and are handled by each node independently. Each node would receive the set mode command, with a session_id value of 123, causing them to load the actual plog file that matches their SDF key and session time.

Usage #include <PolySyncLogfile.hpp>

LogfileModule

This class wraps the ps_rnr_log_module struct, as well as version data and name for a given polysync::datamodel module, e.g. sensor.idl, and core.idl.

The LogFileHeader class contains a list of these modules.

LogfileModule::LogfileModule ( … )

The default constructor.

LogfileModule::LogfileModule ( … )

The copy constructor.

Parameters
in/out type name description
in LogfileModule & moduleToCopy Copy content of argument into new instance.

LogfileModule::operator = ( … )

The copy assignment operator.

Parameters
in/out type name description
in const LogfileModule & moduleToCopy Copy content of argument into new instance.
Returns

LogfileModule::LogfileModule ( … )

This will move the constructor.

Parameters
in/out type name description
in LogfileModule && moduleToMove Move contents of argument to this instance.

LogfileModule::operator = ( … )

This will move the assignment operator.

Parameters
in/out type name description
in LogfileModule && moduleToMove Move contents of argument to new object.
Returns

LogfileModule::LogfileModule ( … )

This will copy the constructor for internal C struct.

Parameters
in/out type name description
in const ps_rnr_log_module & structToCopy Copy contents of argument too this->_rnrLogModule.

virtual LogfileModule::~LogfileModule ( )

The LogfileModule destructor.

LogfileModule::getVersion ( ) const

This will get the module’s version data.

Returns
  • Version - Module’s version data

LogfileModule::getName ( ) const

This will get the name of the module.

Returns
  • std::string - Module’s string name

LogfileModule::get_ps_rnr_log_module ( ) const

This will access the internal C data structure.

Returns
  • ps_rnr_log_module * - Pointer to the internal C struct

LogfileModule::setVersion ( … )

This will set the Version data for the module.

Parameters
in/out type name description
in polysync::Version version The version data to set.
Returns
  • void

LogfileModule::setName ( … )

This will set the module name.

Parameters
in/out type name description
in const std::string & name Name to set.

LogfileTypeSupport

The LogfileTypeSupport class is a wrapper for PolySync type information. The LogfileHeader contains a list of these, representing the message types supported in the model.

LogfileTypeSupport::LogfileTypeSupport ( … )

The default constructor.

LogfileTypeSupport::LogfileTypeSupport ( … )

The copy constructor.

Parameters
in/out type name description
in const LogfileTypeSupport & typeSupportToCopy Copy content of argument into a new instance.

LogfileTypeSupport::operator = ( … )

The copy assignment operator.

Parameters
in/out type name description
in const LogfileTypeSupport & typeSupportToCopy Copy content of argument into a new instance.
Returns

LogfileTypeSupport::LogfileTypeSupport ( … )

The move constructor.

Parameters
in/out type name description
in LogfileTypeSupport && typeSupportToMove Move contents of argument to this.

LogfileTypeSupport::operator = ( … )

The move assignment operator.

Parameters
in/out type name description
in LogfileTypeSupport && typeSupportToMove Move contents of argument to new object.
Returns

LogfileTypeSupport::LogfileTypeSupport ( … )

The copy constructor for the internal C struct.

Parameters
in/out type name description
in const ps_rnr_type_support & typeSupportToCopy Copy contents of argument too internal C struct.

virtual LogfileTypeSupport::~LogfileTypeSupport ( )

The destructor.

LogfileTypeSupport::getMessageType ( )

This will get the value for a given message type assigned by PolySync at runtime.

Returns

LogfileTypeSupport::getMessageTypeString ( )

This will get the string representation for a message type. This is bound to the datamodel.

Returns
  • std::string - Human readable message type string

LogfileTypeSupport::get_ps_rnr_type_support ( … ) const

This will get the internal C struct.

Returns
  • ps_rnr_type_support *

LogfileTypeSupport::setMessageType ( … )

This will set the message type member.

Parameters
in/out type name description
in ps_msg_type type PolySync runtime type value.
Returns
  • void

LogfileTypeSupport::setMessageTypeString ( … )

This will set the internal C struct’s _typeSupport->name_data and _typeSupport->name_len members.

Parameters
in/out type name description
in const std::string & name Message type name.
Returns
  • void

LogfileHeader

The Logfile header class.

LogfileHeader::LogfileHeader ( … )

The default constructor.

LogfileHeader::LogfileHeader ( … )

The copy constructor.

Parameters
in/out type name description
in const LogfileHeader & headerToCopy Copy content of argument into new instance.

LogfileHeader::operator = ( … )

The copy assignment operator.

Parameters
in/out type name description
in const LogfileHeader & headerToCopy Copy content of argument into new instance.
Returns

LogfilefileHeader::LogfileHeader ( … )

The move constructor.

Parameters
in/out type name description
in LogfileHeader && headerToMove Move contents of argument to this.

LogfileHeader::operator = ( … )

The move assignment operator.

Parameters
in/out type name description
in LogfileHeader && headerToMove Move contents of argument to new object.
Returns

LogfileHeader::LogfileHeader ( … )

The copy constructor for the underlying C struct.

Parameters
in/out type name description
in const ps_rnr_log_header & headerToCopy C Struct to copy.

virtual LogfileHeader::~LogfileHeader ( )

The destructor.

LogfileHeader::getVersion ( ) const

Returns

LogfileHeader::getGuid ( ) const

Returns

LogfileHeader::get_ps_rnr_log_header ( ) const

This will access the underlying C data structure.

Returns
  • ps_rnr_log_header * - pointer.

LogfileHeader::getModules ( ) const

Returns
  • std::vector< LogfileModule > - List of PolySync data model modules associated with this logfile

LogfileHeader::getSupportedTypes ( … ) const

Returns

LogfileHeader::setVersion ( … )

This will set the version information in the internal C struct.

Parameters
in/out type name description
in const Version & version Version data to set.
Returns
  • void

LogfileHeader::setGuid ( … )

This will set the guid member.

Parameters
in/out type name description
in ps_guid guid The guid to set.
Returns
  • void

LogfileHeader::setModules ( … )

This will copy the argument data to the internal modules list.

Parameters
in/out type name description
in const std::vector< LogfileModule > & modules List of LogfileModule objects to set.
Returns
  • void

LogfileHeader::setSupportedTypes ( … )

This will set the supported types to a copy of the argument.

Parameters
in/out type name description
in const std::vector< LogfileTypeSupport > & supportedTypes List of supported types of objects to copy.
Returns
  • void

LogfileAttributes

This will wrap the C API struct ps_logfile_attributes.

LogfileAttributes::LogfileAttributes ( … )

The default constructor.

LogfileAttributes::LogfileAttributes ( … )

The copy constructor.

Parameters
in/out type name description
in const LogfileAttributes & attributesToCopy Copy content of argument into new instance.

LogfileAttributes::operator = ( … )

The copy assignment operator.

Parameters
in/out type name description
in const LogfileAttributes & attributesToCopy Copy content of argument into new instance.
Returns

LogfileAttributes::LogfileAttributes ( … )

The move constructor.

Parameters
in/out type name description
in LogfileAttributes && attributesToMove This will move contents of argument to *this.

LogfileAttributes::operator = ( … )

The move assignment operator.

Parameters
in/out type name description
in LogfileAttributes && attributesToMove Move contents of the argument to a new object.
Returns

LogfileAttributes::LogfileAttributes ( … )

The copy constructor for the underlying C struct.

Parameters
in/out type name description
in const ps_logfile_attributes & attributesToCopy Copy contents of argument to the internal C struct.

virtual LogfileAttributes::~LogfileAttributes ( … )

The destructor.

LogfileAttributes::setLogfileHeader ( … )

This will set the header information.

Parameters
in/out type name description
in const LogfileHeader & header Logfile header to set.
Returns
  • void

LogfileAttributes::setStartTime ( … )

This will set the logfile’s start time.

Parameters
in/out type name description
in ps_timestamp startTime The start time to set.
Returns
  • void

LogfileAttributes::setEndTime ( … )

This will set the logfile’s end time.

Parameters
in/out type name description
in ps_timestamp endTime The end time to set.
Returns
  • void

LogfileAttributes::setDuration ( … )

This will set the duration of the logfile.

Parameters
in/out type name description
in ps_timestamp duration The duration of the logfile.
Returns
  • void

LogfileAttributes::setFileSize ( … )

This will set the size of the logfile.

Parameters
in/out type name description
in ulong filesize The fileSize in bytes.
Returns
  • void

LogfileAttributes::setDataOffset ( … )

This will set the offset in bytes to the first record in the logfile.

Parameters
in/out type name description
in ulong dataOffset Offset in bytes.
Returns
  • void

LogfileAttributes::setDataCount ( … )

This will set the number of record entries in the logfile.

Parameters
in/out type name description
in ulong dataCount The number of records in the logfile.
Returns
  • void

LogfileAttributes::setAverageDataSize ( … )

This will set the average size of record entries in the logfile.

Parameters
in/out type name description
in ulong averageDataSize The data size to set.
Returns
  • void

LogfileAttributes::getLogfileHeader ( ) const

This will access the RnR Log header.

Returns

LogfileAttributes::getStartTime ( ) const

This will access the first timestamp in the file.

Returns

LogfileAttributes::getEndTime ( ) const

This will access the last timestamp in the file.

Returns

LogfileAttributes::getDuration ( ) const

This will access the duration of the file in microseconds.

Returns

LogfileAttributes::getFileSize ( ) const

This will get the file size in bytes.

Returns
  • ulong - Size of file in bytes

LogfileAttributes::getDataOffset ( ) const

This will get the data offset of the first record in the file.

Returns
  • ulong - Number of bytes to the first record in the file

LogfileAttributes::getDataCount ( ) const

This will get the number of record entries in the file.

Returns
  • ulong - Number of record entries in file

LogfileAttributes::getAvgDataSize ( ) const

This will get the average data size in bytes.

Returns
  • ulong - Average data size in bytes

LogfileAttributes::get_ps_logfile_attrubutes ( ) const

This will access the underlying C data structure.

Returns
  • ps_logfile_attributes *

LogfileRecord

The CPP API RnrLogRecord class will wrap the C API struct named ps_rnr_log_record.

LogfileRecord::LogfileRecord ( … )

The default constructor.

LogfileRecord::LogfileRecord ( … )

The copy constructor.

Parameters
in/out type name description
in const LogfileRecord & recordToCopy Copy content of argument into new instance.

LogfileRecord::operator = ( … )

The copy assignment operator.

Parameters
in/out type name description
in const LogfileRecord & recordToCopy Copy content of argument into new instance.
Returns

LogfileRecord::LogfileRecord ( … )

The move constructor.

Parameters
in/out type name description
in const LogfileRecord && recordToMove Move contents of argument to this.

LogfileRecord::operator = ( … )

The move assignment operator.

Parameters
in/out type name description
in LogfileRecord && recordToMove Move contents of argument to new object.
Returns

LogfileRecord::LogfileRecord ( … )

The copy constructor for the related C struct.

Parameters
in/out type name description
in const ps_rnr_log_record & recordToCopy The C struct to copy internally.

virtual LogfileRecord::~LogfileRecord ( )

The destructor.

LogfileRecord::getIndex ( ) const

This will get the logfile record index.

Returns
  • uint - Index of this record in the logfile

LogfileRecord::getSize() const

This will get the logfile record size.

Returns
  • uint - Size of ps_rnr_log_record data field

LogfileRecord::getPreviousSize ( ) const

This will get the size of the previous record in the logfile.

Returns
  • uint - Size of previous ps_rnr_log_record data field

LogfileRecord::getTimestamp ( ) const

This will get the timestamp.

Returns
  • uint - Copy of message timestamp that is contained in a data field

LogfileRecord::getRecordData ( ) const

This will get the logfile record data.

Returns

LogfileRecord::get_ps_rnr_log_record ( … )

This will access the underlying C data structure.

Returns
  • ps_rnr_log_record *

Logfile

This class will interact with PolySync *.plog files. It also enables a node to read and write to/from a logfile.

Logfile::Logfile ( … )

The default constructor.

Logfile::Logfile ( … )

The logfile class constructor.

Parameters
in/out type name description
in Node & node Node reference that stores the configuration.

Logfile::Logfile ( … )

The copy constructor.

Parameters
in/out type name description
in const Logfile & logfileToCopy Logfile instance to copy from.

virtual Logfile::~Logfile ( )

The destructor.

Logfile::setModeRead ( )

This is a convenience function that sets the logfile mode to LOGFILE_MODE_READ.

Returns
  • void

Logfile::setModeWrite ( )

This is a convenience function that sets the logfile mode to LOGFILE_MODE_WRITE.

Returns
  • void

Logfile::setModeOff ( )

This is a convenience function that sets the logfile mode to LOGFILE_MODE_OFF.

Returns
  • void

Logfile::setStateEnabled ( … )

This will set a node’s logfile state to LOGFILE_STATE_ENABLED in order to enable logfile reading or writing.

Parameters
in/out type name description
in ps_timestamp offset Default value of current time + 2 seconds. (2000000us)
Returns
  • void

Logfile::setStateDisabled ( )

This will set a node’s logfile state to LOGFILE_STATE_DISABLED.

Returns
  • void

Logfile::setStateInvalid ( )

This will set a node’s logfile state to LOGFILE_STATE_INVALID.

Returns
  • void

Logfile::setFilePath ( … )

This will manually set the logfile file path.

Parameters
in/out type name description
in const std::string & filePath Overridden file path to use for logfile files. If filePath is empty, override functionality is disabled.
Returns
  • void

Logfile::getFilePath ( … ) const

This will get the manually set logfile file path.

Returns
  • std::string - The manually specified file path to the logfile

Logfile::writeMessage ( … )

This will write data to a logfile.

Parameters
in/out type name description
in const Message & message Message reference to be written.
Returns
  • void

Logfile::enableOutputQueue ( … )

This will enable the use of the logfile replay message queue.

Parameters
in/out type name description
in uint enableReplayMessageQueue Flag indicating if enabled. Value zero means disabled.
Returns
  • void

Logfile::getThreadStatus ( )

This will check the logfile thread status.

Returns
  • void

Logfile::setReplayClockScaler ( … )

This will set the logfile replay clock scale on the current host.

Parameters
in/out type name description
in double scale Replay clock scaling multiplier.

Logfile::getReplayClockScaler ( … ) const

This will get the logfile replay clock scale on the current host.

Returns
  • double - Replay clock scale value

Logfile::setMessageTypeFilters ( … )

This will set the logfile write and reader message type filters.

Parameters
in/out type name description
in std::vector< ps_msg_type > writer_disabled_types A pointer to ps_msg_type that specifies the array of message types to filter in the writer.
in std::vector< ps_msg_type > reader_disabled_types A pointer to ps_msg_type that specifies the array of message types to filter in the reader.
Returns
  • void

Logfile::getReplayMessageQueue ( )

This will get the logfile replay output message queue.

Returns

  • GAsyncQueue *

Logfile::getMode ( )

This will get the logfile mode.

Possible modes:

Returns

Logfile::getState ( )

This will get the logfile state.

Possible states:

Returns
  • ps_logfile_state_kind

Logfile::getReplayClockOwner ( )

Returns
  • std::pair< ps_guid, ps_identifier > - Owning node guid and system process ID for the PolySync clock owner

Logfile::eofHasBeenReached ( )

This will determine if the logfile reader (replay) end-of-file has been reached.

Returns
  • bool - True if EOF was reached

Logfile::readerResetToBeginning ( … )

This will set the logfile state to LOGFILE_STATE_DISABLED and reset the reader to the beginning of the logfile.

Returns
  • void

Logfile::readerSeekTo ( … )

This will set the logfile state to LOGFILE_STATE_DISABLED and seek reader to timestamp in the logfile.

Parameters
in/out type name description
in ps_timestamp timestamp The seek target in the logfile. [microseconds]
Returns
  • void

Logfile::readerGetFileAttributes ( ) const

This will get the logfile reader file attributes.

Returns

Logfile::fillRnRStatusMessage ( )

This will get an RnrMessage with the current state of record and replay.

Returns

Logfile::handleRnRCommand ( … )

This will handle a PolySync Record and Replay message, possibly modifying the current logfile data.

Parameters
in/out type name description
out const RnrMessage & message The Record and Replay Message to handle.
Returns
  • void

Logfile::setSessionId ( … )

This will set the Sessions ID and directory name.

Parameters
in/out type name description
in ps_timestamp currentTimestamp The timestamp to use as the session ID.
Returns
  • void

Logfile::getSessionId ( … ) const

This will get the timestamp used as the session ID and directory name.

Returns
  • ps_timestamp - Returns session ID, which is also a directory name in rnr_logs

Logfile::readLogfile ( … )

Manually iterates through a logfile and passes each record to readLogfileHandler().

The base class implementation will simply print each message.

Parameters
in/out type name description
in const std::string & filePath Absolute path to logfile.
Returns
  • void

virtual Logfile::readLogfileHandler ( … )

This function is called for each record in a logfile being read by readLogfile().

The default behavior is to print each record to stdout.

Parameters
in/out type name description
in const std::string & filePath attributes Attribute information about the logfile being read from.
in ps_msg_type messageType Message type contained in the record argument.
in const LogfileRecord & record Object containing the message data.
Returns
  • void