wpi::log::DataLog Class Reference

A data log. More...

#include <wpi/DataLog.h>

Public Member Functions
	DataLog (std::string_view dir="", std::string_view filename="", double period=0.25, std::string_view extraHeader="")
	Construct a new Data Log. More...
	DataLog (wpi::Logger &msglog, std::string_view dir="", std::string_view filename="", double period=0.25, std::string_view extraHeader="")
	Construct a new Data Log. More...
	DataLog (std::function< void(std::span< const uint8_t > data)> write, double period=0.25, std::string_view extraHeader="")
	Construct a new Data Log that passes its output to the provided function rather than a file. More...
	DataLog (wpi::Logger &msglog, std::function< void(std::span< const uint8_t > data)> write, double period=0.25, std::string_view extraHeader="")
	Construct a new Data Log that passes its output to the provided function rather than a file. More...
	~DataLog ()
	DataLog (const DataLog &)=delete
DataLog &	operator= (const DataLog &)=delete
	DataLog (DataLog &&)=delete
DataLog &	operator= (const DataLog &&)=delete
void	SetFilename (std::string_view filename)
	Change log filename. More...
void	Flush ()
	Explicitly flushes the log data to disk. More...
void	Pause ()
	Pauses appending of data records to the log. More...
void	Resume ()
	Resumes appending of data records to the log. More...
int	Start (std::string_view name, std::string_view type, std::string_view metadata={}, int64_t timestamp=0)
	Start an entry. More...
void	Finish (int entry, int64_t timestamp=0)
	Finish an entry. More...
void	SetMetadata (int entry, std::string_view metadata, int64_t timestamp=0)
	Updates the metadata for an entry. More...
void	AppendRaw (int entry, std::span< const uint8_t > data, int64_t timestamp)
	Appends a record to the log. More...
void	AppendRaw2 (int entry, std::span< const std::span< const uint8_t > > data, int64_t timestamp)
	Appends a record to the log. More...
void	AppendBoolean (int entry, bool value, int64_t timestamp)
void	AppendInteger (int entry, int64_t value, int64_t timestamp)
void	AppendFloat (int entry, float value, int64_t timestamp)
void	AppendDouble (int entry, double value, int64_t timestamp)
void	AppendString (int entry, std::string_view value, int64_t timestamp)
void	AppendBooleanArray (int entry, std::span< const bool > arr, int64_t timestamp)
void	AppendBooleanArray (int entry, std::span< const int > arr, int64_t timestamp)
void	AppendBooleanArray (int entry, std::span< const uint8_t > arr, int64_t timestamp)
void	AppendIntegerArray (int entry, std::span< const int64_t > arr, int64_t timestamp)
void	AppendFloatArray (int entry, std::span< const float > arr, int64_t timestamp)
void	AppendDoubleArray (int entry, std::span< const double > arr, int64_t timestamp)
void	AppendStringArray (int entry, std::span< const std::string > arr, int64_t timestamp)
void	AppendStringArray (int entry, std::span< const std::string_view > arr, int64_t timestamp)

Detailed Description

A data log.

The log file is created immediately upon construction with a temporary filename. The file may be renamed at any time using the SetFilename() function.

The lifetime of the data log object must be longer than any data log entry objects that refer to it.

The data log is periodically flushed to disk. It can also be explicitly flushed to disk by using the Flush() function.

Finish() is needed only to indicate in the log that a particular entry is no longer being used (it releases the name to ID mapping). Finish() is not required to be called for data to be flushed to disk; entries in the log are written as Append() calls are being made. In fact, Finish() does not need to be called at all; this is helpful to avoid shutdown races where the DataLog object might be destroyed before other objects. It's often not a good idea to call Finish() from destructors for this reason.

DataLog calls are thread safe. DataLog uses a typical multiple-supplier, single-consumer setup. Writes to the log are atomic, but there is no guaranteed order in the log when multiple threads are writing to it; whichever thread grabs the write mutex first will get written first. For this reason (as well as the fact that timestamps can be set to arbitrary values), records in the log are not guaranteed to be sorted by timestamp.

Constructor & Destructor Documentation

DataLog() [1/6]

wpi::log::DataLog::DataLog ( std::string_view  dir = "", std::string_view  filename = "", double  period = 0.25, std::string_view  extraHeader = ""  )

explicit

Construct a new Data Log.

The log will be initially created with a temporary filename.

Parameters

dir	directory to store the log
filename	filename to use; if none provided, a random filename is generated of the form "wpilog_{}.wpilog"
period	time between automatic flushes to disk, in seconds; this is a time/storage tradeoff
extraHeader	extra header data

DataLog() [2/6]

wpi::log::DataLog::DataLog ( wpi::Logger &  msglog, std::string_view  dir = "", std::string_view  filename = "", double  period = 0.25, std::string_view  extraHeader = ""  )

explicit

Construct a new Data Log.

The log will be initially created with a temporary filename.

Parameters

msglog	message logger (will be called from separate thread)
dir	directory to store the log
filename	filename to use; if none provided, a random filename is generated of the form "wpilog_{}.wpilog"
period	time between automatic flushes to disk, in seconds; this is a time/storage tradeoff
extraHeader	extra header data

DataLog() [3/6]

wpi::log::DataLog::DataLog ( std::function< void(std::span< const uint8_t > data)>  write, double  period = 0.25, std::string_view  extraHeader = ""  )

explicit

Construct a new Data Log that passes its output to the provided function rather than a file.

The write function will be called on a separate background thread and may block. The write function is called with an empty data array when the thread is terminating.

Parameters

write	write function
period	time between automatic calls to write, in seconds; this is a time/storage tradeoff
extraHeader	extra header data

DataLog() [4/6]

wpi::log::DataLog::DataLog ( wpi::Logger &  msglog, std::function< void(std::span< const uint8_t > data)>  write, double  period = 0.25, std::string_view  extraHeader = ""  )

explicit

Construct a new Data Log that passes its output to the provided function rather than a file.

The write function will be called on a separate background thread and may block. The write function is called with an empty data array when the thread is terminating.

Parameters

msglog	message logger (will be called from separate thread)
write	write function
period	time between automatic calls to write, in seconds; this is a time/storage tradeoff
extraHeader	extra header data

~DataLog()

wpi::log::DataLog::~DataLog

(

)

DataLog() [5/6]

wpi::log::DataLog::DataLog ( const DataLog &  )

delete

DataLog() [6/6]

wpi::log::DataLog::DataLog ( DataLog &&  )

delete

Member Function Documentation

AppendBoolean()

void wpi::log::DataLog::AppendBoolean	(	int	entry,
		bool	value,
		int64_t	timestamp
	)

AppendBooleanArray() [1/3]

void wpi::log::DataLog::AppendBooleanArray	(	int	entry,
		std::span< const bool >	arr,
		int64_t	timestamp
	)

AppendBooleanArray() [2/3]

void wpi::log::DataLog::AppendBooleanArray	(	int	entry,
		std::span< const int >	arr,
		int64_t	timestamp
	)

AppendBooleanArray() [3/3]

void wpi::log::DataLog::AppendBooleanArray	(	int	entry,
		std::span< const uint8_t >	arr,
		int64_t	timestamp
	)

AppendDouble()

void wpi::log::DataLog::AppendDouble	(	int	entry,
		double	value,
		int64_t	timestamp
	)

AppendDoubleArray()

void wpi::log::DataLog::AppendDoubleArray	(	int	entry,
		std::span< const double >	arr,
		int64_t	timestamp
	)

AppendFloat()

void wpi::log::DataLog::AppendFloat	(	int	entry,
		float	value,
		int64_t	timestamp
	)

AppendFloatArray()

void wpi::log::DataLog::AppendFloatArray	(	int	entry,
		std::span< const float >	arr,
		int64_t	timestamp
	)

AppendInteger()

void wpi::log::DataLog::AppendInteger	(	int	entry,
		int64_t	value,
		int64_t	timestamp
	)

AppendIntegerArray()

void wpi::log::DataLog::AppendIntegerArray	(	int	entry,
		std::span< const int64_t >	arr,
		int64_t	timestamp
	)

AppendRaw()

void wpi::log::DataLog::AppendRaw	(	int	entry,
		std::span< const uint8_t >	data,
		int64_t	timestamp
	)

Appends a record to the log.

Parameters

entry	Entry index, as returned by Start()
data	Data to record
timestamp	Time stamp (may be 0 to indicate now)

AppendRaw2()

void wpi::log::DataLog::AppendRaw2	(	int	entry,
		std::span< const std::span< const uint8_t > >	data,
		int64_t	timestamp
	)

Appends a record to the log.

Parameters

entry	Entry index, as returned by Start()
data	Data to record
timestamp	Time stamp (may be 0 to indicate now)

AppendString()

void wpi::log::DataLog::AppendString	(	int	entry,
		std::string_view	value,
		int64_t	timestamp
	)

AppendStringArray() [1/2]

void wpi::log::DataLog::AppendStringArray	(	int	entry,
		std::span< const std::string >	arr,
		int64_t	timestamp
	)

AppendStringArray() [2/2]

void wpi::log::DataLog::AppendStringArray	(	int	entry,
		std::span< const std::string_view >	arr,
		int64_t	timestamp
	)

Finish()

void wpi::log::DataLog::Finish	(	int	entry,
		int64_t	timestamp = 0
	)

Finish an entry.

Parameters

entry	Entry index
timestamp	Time stamp (may be 0 to indicate now)

Flush()

void wpi::log::DataLog::Flush

(

)

Explicitly flushes the log data to disk.

operator=() [1/2]

DataLog & wpi::log::DataLog::operator= ( const DataLog &&  )

delete

operator=() [2/2]

DataLog & wpi::log::DataLog::operator= ( const DataLog &  )

delete

Pause()

void wpi::log::DataLog::Pause

(

)

Pauses appending of data records to the log.

While paused, no data records are saved (e.g. AppendX is a no-op). Has no effect on entry starts / finishes / metadata changes.

Resume()

void wpi::log::DataLog::Resume

(

)

Resumes appending of data records to the log.

SetFilename()

void wpi::log::DataLog::SetFilename

(

std::string_view

filename

)

Change log filename.

Parameters

filename

filename

SetMetadata()

void wpi::log::DataLog::SetMetadata	(	int	entry,
		std::string_view	metadata,
		int64_t	timestamp = 0
	)

Updates the metadata for an entry.

Parameters

entry	Entry index
metadata	New metadata for the entry
timestamp	Time stamp (may be 0 to indicate now)

Start()

int wpi::log::DataLog::Start	(	std::string_view	name,
		std::string_view	type,
		std::string_view	metadata = {},
		int64_t	timestamp = 0
	)

Start an entry.

Duplicate names are allowed (with the same type), and result in the same index being returned (Start/Finish are reference counted). A duplicate name with a different type will result in an error message being printed to the console and 0 being returned (which will be ignored by the Append functions).

Parameters

name	Name
type	Data type
metadata	Initial metadata (e.g. data properties)
timestamp	Time stamp (may be 0 to indicate now)

Returns

Entry index

---

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

• wpi/DataLog.h