mdf::MdfWriter Class Reference

Interface against an MDF writer object. More...

#include <mdfwriter.h>

Public Member Functions
	MdfWriter ()=default
	Default constructor.
virtual	~MdfWriter ()
	Default destructor.
	MdfWriter (const MdfWriter &writer)=delete
MdfWriter &	operator= (const MdfWriter &writer)=delete
std::string	Name () const
	Returns the filename without extension and path (stem).
bool	Init (const std::string &filename)
	Initiate the file.
bool	IsFileNew () const
	Returns true if this is a new file.
void	PreTrigTime (double pre_trig_time)
	Sets the pre-trig time (s) of the writer.
double	PreTrigTime () const
	Pre-trig time (s).
uint64_t	StartTime () const
	Returns start time in nano-seconds since 1970.
uint64_t	StopTime () const
	Returns stop time in nano-seconds since 1970.
MdfFile *	GetFile () const
	Returns the MDF file interface.
IHeader *	Header () const
	Returns the header block (HD).
bool	CreateBusLogConfiguration ()
	Creates all default DG, CG and CN blocks that bus loggers uses.
IDataGroup *	CreateDataGroup ()
	Create a new data group (DG) block.
virtual IChannelConversion *	CreateChannelConversion (IChannel *parent)=0
	Create a new channel conversion (CC) block.
virtual bool	InitMeasurement ()
	Initialize the sample queue and write any unwritten block to the file.
virtual void	SaveSample (const IChannelGroup &group, uint64_t time)
	Saves a sample record for a channel group.
void	SaveCanMessage (const IChannelGroup &group, uint64_t time, const CanMessage &msg)
	Saves a CAN message into a bus logger channel group.
virtual void	StartMeasurement (uint64_t start_time)
	Starts the measurement.
virtual void	StartMeasurement (ITimestamp &start_time)
	Starts the measurement.
virtual void	StopMeasurement (uint64_t stop_time)
	Stops the measurement.
virtual void	StopMeasurement (ITimestamp &start_time)
	Stops the measurement.
virtual bool	FinalizeMeasurement ()
	Stop the sample queue and write all unwritten blocks to the file.
void	BusType (MdfBusType type)
	Only used when doing bus logging. It defines the default channel and channel group names when doing bus logging.
MdfBusType	BusType () const
	Returns the type of bus the MDF file is associated with. Only used when doing bus logging.
std::string_view	BusTypeAsString () const
	Returns the bus type as text.
void	StorageType (MdfStorageType type)
	Only used when doing bus logging. It defines how raw data is stored.
MdfStorageType	StorageType () const
	Returns the type of data storage the MDF file is associated with. Only used when doing bus logging.
void	MaxLength (uint32_t max_length)
	Sets max number of payload data bytes.
uint32_t	MaxLength () const
	Returns maximum number of payload data bytes.
void	CompressData (bool compress)
	If set to true, the data block will be compressed.
bool	CompressData () const
	Returns true if the data block is compressed.

Static Public Member Functions
static IChannelGroup *	CreateChannelGroup (IDataGroup *parent)
	Create a new channel group (CG) block.
static IChannel *	CreateChannel (IChannelGroup *parent)
	Creates a new channel (CN) block.

Protected Types
enum class	WriteState : uint8_t {   Create , Init , StartMeas , StopMeas ,   Finalize }
	Internal state of the thread. More...
using	SampleQueue = std::deque<SampleRecord>
	Sample queue.

Protected Member Functions
virtual void	CreateMdfFile ()=0
	Creates an MDF file.
virtual bool	PrepareForWriting ()=0
	Prepare for writing.
virtual void	SetDataPosition (std::FILE *file)
	Set the data position.
virtual bool	WriteSignalData (std::FILE *file)
	Write an SD block.
void	StopWorkThread ()
	Stops the worker thread.
void	WorkThread ()
	Worker thread function.
virtual void	TrimQueue ()
	Trims the sample queue.
virtual void	SaveQueue (std::unique_lock< std::mutex > &lock)
	Saves the queue to file.
virtual void	CleanQueue (std::unique_lock< std::mutex > &lock)
	Flush the sample queue.
void	IncrementNofSamples (uint64_t record_id) const
	Increment the sample counter.
virtual void	SetLastPosition (std::FILE *file)=0
	Set the last file position.

Protected Attributes
std::atomic< WriteState >	write_state_
	Keeps track of the worker thread state.
std::unique_ptr< MdfFile >	mdf_file_
	Holds the actual file object.
std::string	filename_
	Full name of file with path and extension.
std::atomic< uint64_t >	pre_trig_time_ = 0
	Nanoseconds difference.
std::atomic< uint64_t >	start_time_ = 0
	Nanoseconds since 1970.
std::atomic< uint64_t >	stop_time_ = 0
	Nanoseconds since 1970.
std::thread	work_thread_
	Sample queue thread.
std::atomic_bool	stop_thread_ = false
	Set to true to stop the thread.
std::mutex	locker_
	Mutex for thread-safe handling of the sample queue.
std::condition_variable	sample_event_
	Used internally.
std::atomic< size_t >	sample_queue_size_ = 0
	Used to trig flushing to disc.
SampleQueue	sample_queue_
	Sample queue.

Detailed Description

The MDF writer purpose is to create MDF files. It simplifies the writing into some steps.

The first is to create type of writer. This is done by using the MdfFactory::CreateMdfWriter() function.

The next step is to call the Init() function with a filename with valid path. The Init function will create the actual MDF file object and check if it exist or not. If it exist, it reads in the existing file content so it can be appended.

The next step is to prepare the file for a new measurement. This is done by creating the DG/CG/CN/CC blocks that defines the measurement. Note that it is the last DG block that is the target.

Next step is to call the InitMeasurement() function. This create a thread that handle the queue of samples. The function also write the configuration to the file and closes it.

The user shall know starts adding samples to the queue by first setting the current channel value to each channel and then call the SaveSample() function for each channel group (CG). Note that no samples are saved to the file yet. The max queue size is set to the pre-trig time, see PreTrigTime().

At some point the user shall call the StartMeasurement() function. The sample queue is now saved onto the file. The save rate is actually dependent if CompressData() is enabled or not. If compression is used the data is saved at the 4MB size or a 10 minute max. If not using compression, the samples are saved each 10 second.

The user shall now call StopMeasurement() which flush out the remaining sample queue. After stopping the queue, the user may add some extra block as event (EV) and attachment (AT) blocks.

The FinalizeMeasurement() function. Stops the thread and write all unwritten blocks to the file.

Member Enumeration Documentation

WriteState

enum class mdf::MdfWriter::WriteState : uint8_t

strongprotected

Enumerator
Create	Only at first measurement.
Init	Start work thread and start collecting samples.
StartMeas	Start saving samples to file.
StopMeas	Stop saving samples. OK to.
Finalize	OK to add new DG and CG blocks.

Member Function Documentation

BusType() [1/2]

MdfBusType mdf::MdfWriter::BusType ( ) const

inlinenodiscard

Returns

Type of bus.

BusType() [2/2]

void mdf::MdfWriter::BusType ( MdfBusType type )

inline

When using the MDF writer as a bus logger, the naming of channel groups and channels are defined in an ASAM standard. The naming is depending on the basic low level protocol.

Parameters

type	Type of basic protocol on the bus.

CreateBusLogConfiguration()

bool mdf::MdfWriter::CreateBusLogConfiguration

(

)

This function create all data groups, channel groups and channels for a typical bus logger. Before calling this function, set the bus and storage types as this function uses these settings.

GetFile()

MdfFile * mdf::MdfWriter::GetFile ( ) const

inline

Returns the MDF file interface. The user may change the file version and the finalize status of the file. By default is the MDF 4.2 or 3.2 version of the file used.

Returns

Pointer to the MDF file interface.

Init()

bool mdf::MdfWriter::Init

(

const std::string &

filename

)

Initiate the writer by defining which file it shall work with. Note that appending an existing file is supported.

Parameters

filename

Filename with full path.

Returns

Returns true if the function was successful.

MaxLength()

void mdf::MdfWriter::MaxLength ( uint32_t max_length )

inline

Number of payload data bytes is default set to 8 bytes. Standard CAN may have max 8 byte of data while CAN FD can have up to 64 bytes data bytes. If you should store CAN FD data, you should set the max length to 64 bytes.

Parameters

max_length

Maximum number of payload data bytes.

PreTrigTime()

void mdf::MdfWriter::PreTrigTime

(

double

pre_trig_time

)

Sets the pre-trig time (note seconds). This defines the maximum number of samples the writer holds internally, before the measurement is started.

Parameters

pre_trig_time

Pre-trig time in seconds.

SaveCanMessage()

void mdf::MdfWriter::SaveCanMessage	(	const IChannelGroup &	group,
		uint64_t	time,
		const CanMessage &	msg )

This function replace the normal SaveSample() function. It shall be used when logging CAN/CAN-FD messages into a standard ASAM bus logger configuration.

As before the function creates a record byte array and puts it onto an internal sample buffer. The time shall be absolute time (ns since 1970).

Parameters

group	Reference to the channel group (CG).
time	Absolute time nano-seconds since 1970.
msg	The CAN message to store.

SaveSample()

virtual void mdf::MdfWriter::SaveSample ( const IChannelGroup & group, uint64_t time )

virtual

Call this function after all channel values have been updated with the latest value. The function creates the a record byte buffer and puts the buffer onto an internal sample buffer.

The time shall be absolute time (nano-seconds since 1970-01-01). Note that the function or actually the internal queue, assume that the samples are added in chronological order. The time will be converted to a relative time before it is stored onto the disc. The will be relative to the start time, see StartMeasurement() function.

StorageType() [1/2]

MdfStorageType mdf::MdfWriter::StorageType ( ) const

inlinenodiscard

Returns

Type of data storage.

StorageType() [2/2]

void mdf::MdfWriter::StorageType ( MdfStorageType type )

inline

Defines how the raw data (payload) is stored. Only used when doing bus logging.

By default the fixed length storage is used. This means that the data records have fixed length. This is the traditional way of storage. Variable length channels as strings, are stored in separate signal data blocks (SD).

The Variable Length Signal Data (VLSD) is stored in the data block. In practice this option is only used when doing bus logging.

The Maximum Length Signal Data is typicallay used when logging CAN bus traffic

Parameters

type	Type of storage.

Member Data Documentation

write_state_

std::atomic<WriteState> mdf::MdfWriter::write_state_

protected

Initial value:

=
      WriteState::Create

---

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

• include/mdf/mdfwriter.h