DataLog.h File Reference

#include <stdint.h>
#include <concepts>
#include <functional>
#include <initializer_list>
#include <memory>
#include <ranges>
#include <span>
#include <string>
#include <string_view>
#include <thread>
#include <tuple>
#include <utility>
#include <vector>
#include <version>
#include "wpi/DenseMap.h"
#include "wpi/SmallVector.h"
#include "wpi/StringMap.h"
#include "wpi/condition_variable.h"
#include "wpi/mutex.h"
#include "wpi/protobuf/Protobuf.h"
#include "wpi/struct/Struct.h"
#include "wpi/timestamp.h"

Go to the source code of this file.

Classes
struct	WPI_DataLog_String
	A datalog string (for use with string array). More...
class	wpi::log::DataLog
	A data log. More...
class	wpi::log::DataLogEntry
	Log entry base class. More...
class	wpi::log::RawLogEntry
	Log arbitrary byte data. More...
class	wpi::log::BooleanLogEntry
	Log boolean values. More...
class	wpi::log::IntegerLogEntry
	Log integer values. More...
class	wpi::log::FloatLogEntry
	Log float values. More...
class	wpi::log::DoubleLogEntry
	Log double values. More...
class	wpi::log::StringLogEntry
	Log string values. More...
class	wpi::log::BooleanArrayLogEntry
	Log array of boolean values. More...
class	wpi::log::IntegerArrayLogEntry
	Log array of integer values. More...
class	wpi::log::FloatArrayLogEntry
	Log array of float values. More...
class	wpi::log::DoubleArrayLogEntry
	Log array of double values. More...
class	wpi::log::StringArrayLogEntry
	Log array of string values. More...
class	wpi::log::StructLogEntry< T, I >
	Log raw struct serializable objects. More...
class	wpi::log::StructArrayLogEntry< T, I >
	Log raw struct serializable array of objects. More...
class	wpi::log::ProtobufLogEntry< T >
	Log protobuf serializable objects. More...

Namespaces
namespace	wpi
namespace	wpi::log
namespace	wpi::log::impl

Enumerations
enum	wpi::log::impl::ControlRecordType { wpi::log::impl::kControlStart = 0 , wpi::log::impl::kControlFinish , wpi::log::impl::kControlSetMetadata }

Functions
struct WPI_DataLog *	WPI_DataLog_Create (const char *dir, const char *filename, double period, const char *extraHeader)
	Construct a new Data Log. More...
struct WPI_DataLog *	WPI_DataLog_Create_Func (void(*write)(void *ptr, const uint8_t *data, size_t len), void *ptr, double period, const char *extraHeader)
	Construct a new Data Log that passes its output to the provided function rather than a file. More...
void	WPI_DataLog_Release (struct WPI_DataLog *datalog)
	Releases a data log object. More...
void	WPI_DataLog_SetFilename (struct WPI_DataLog *datalog, const char *filename)
	Change log filename. More...
void	WPI_DataLog_Flush (struct WPI_DataLog *datalog)
	Explicitly flushes the log data to disk. More...
void	WPI_DataLog_Pause (struct WPI_DataLog *datalog)
	Pauses appending of data records to the log. More...
void	WPI_DataLog_Resume (struct WPI_DataLog *datalog)
	Resumes appending of data records to the log. More...
void	WPI_DataLog_Stop (struct WPI_DataLog *datalog)
	Stops appending all records to the log, and closes the log file. More...
int	WPI_DataLog_Start (struct WPI_DataLog *datalog, const char *name, const char *type, const char *metadata, int64_t timestamp)
	Start an entry. More...
void	WPI_DataLog_Finish (struct WPI_DataLog *datalog, int entry, int64_t timestamp)
	Finish an entry. More...
void	WPI_DataLog_SetMetadata (struct WPI_DataLog *datalog, int entry, const char *metadata, int64_t timestamp)
	Updates the metadata for an entry. More...
void	WPI_DataLog_AppendRaw (struct WPI_DataLog *datalog, int entry, const uint8_t *data, size_t len, int64_t timestamp)
	Appends a raw record to the log. More...
void	WPI_DataLog_AppendBoolean (struct WPI_DataLog *datalog, int entry, int value, int64_t timestamp)
	Appends a boolean record to the log. More...
void	WPI_DataLog_AppendInteger (struct WPI_DataLog *datalog, int entry, int64_t value, int64_t timestamp)
	Appends an integer record to the log. More...
void	WPI_DataLog_AppendFloat (struct WPI_DataLog *datalog, int entry, float value, int64_t timestamp)
	Appends a float record to the log. More...
void	WPI_DataLog_AppendDouble (struct WPI_DataLog *datalog, int entry, double value, int64_t timestamp)
	Appends a double record to the log. More...
void	WPI_DataLog_AppendString (struct WPI_DataLog *datalog, int entry, const char *value, size_t len, int64_t timestamp)
	Appends a string record to the log. More...
void	WPI_DataLog_AppendBooleanArray (struct WPI_DataLog *datalog, int entry, const int *arr, size_t len, int64_t timestamp)
	Appends a boolean array record to the log. More...
void	WPI_DataLog_AppendBooleanArrayByte (struct WPI_DataLog *datalog, int entry, const uint8_t *arr, size_t len, int64_t timestamp)
	Appends a boolean array record to the log. More...
void	WPI_DataLog_AppendIntegerArray (struct WPI_DataLog *datalog, int entry, const int64_t *arr, size_t len, int64_t timestamp)
	Appends an integer array record to the log. More...
void	WPI_DataLog_AppendFloatArray (struct WPI_DataLog *datalog, int entry, const float *arr, size_t len, int64_t timestamp)
	Appends a float array record to the log. More...
void	WPI_DataLog_AppendDoubleArray (struct WPI_DataLog *datalog, int entry, const double *arr, size_t len, int64_t timestamp)
	Appends a double array record to the log. More...
void	WPI_DataLog_AppendStringArray (struct WPI_DataLog *datalog, int entry, const WPI_DataLog_String *arr, size_t len, int64_t timestamp)
	Appends a string array record to the log. More...
void	WPI_DataLog_AddSchemaString (struct WPI_DataLog *datalog, const char *name, const char *type, const char *schema, int64_t timestamp)
void	WPI_DataLog_AddSchema (struct WPI_DataLog *datalog, const char *name, const char *type, const uint8_t *schema, size_t schema_len, int64_t timestamp)

Function Documentation

WPI_DataLog_AddSchema()

void WPI_DataLog_AddSchema	(	struct WPI_DataLog *	datalog,
		const char *	name,
		const char *	type,
		const uint8_t *	schema,
		size_t	schema_len,
		int64_t	timestamp
	)

WPI_DataLog_AddSchemaString()

void WPI_DataLog_AddSchemaString	(	struct WPI_DataLog *	datalog,
		const char *	name,
		const char *	type,
		const char *	schema,
		int64_t	timestamp
	)

WPI_DataLog_AppendBoolean()

void WPI_DataLog_AppendBoolean	(	struct WPI_DataLog *	datalog,
		int	entry,
		int	value,
		int64_t	timestamp
	)

Appends a boolean record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
value	Boolean value to record
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_AppendBooleanArray()

void WPI_DataLog_AppendBooleanArray	(	struct WPI_DataLog *	datalog,
		int	entry,
		const int *	arr,
		size_t	len,
		int64_t	timestamp
	)

Appends a boolean array record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
arr	Boolean array to record
len	Number of elements in array
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_AppendBooleanArrayByte()

void WPI_DataLog_AppendBooleanArrayByte	(	struct WPI_DataLog *	datalog,
		int	entry,
		const uint8_t *	arr,
		size_t	len,
		int64_t	timestamp
	)

Appends a boolean array record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
arr	Boolean array to record
len	Number of elements in array
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_AppendDouble()

void WPI_DataLog_AppendDouble	(	struct WPI_DataLog *	datalog,
		int	entry,
		double	value,
		int64_t	timestamp
	)

Appends a double record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
value	Double value to record
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_AppendDoubleArray()

void WPI_DataLog_AppendDoubleArray	(	struct WPI_DataLog *	datalog,
		int	entry,
		const double *	arr,
		size_t	len,
		int64_t	timestamp
	)

Appends a double array record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
arr	Double array to record
len	Number of elements in array
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_AppendFloat()

void WPI_DataLog_AppendFloat	(	struct WPI_DataLog *	datalog,
		int	entry,
		float	value,
		int64_t	timestamp
	)

Appends a float record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
value	Float value to record
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_AppendFloatArray()

void WPI_DataLog_AppendFloatArray	(	struct WPI_DataLog *	datalog,
		int	entry,
		const float *	arr,
		size_t	len,
		int64_t	timestamp
	)

Appends a float array record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
arr	Float array to record
len	Number of elements in array
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_AppendInteger()

void WPI_DataLog_AppendInteger	(	struct WPI_DataLog *	datalog,
		int	entry,
		int64_t	value,
		int64_t	timestamp
	)

Appends an integer record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
value	Integer value to record
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_AppendIntegerArray()

void WPI_DataLog_AppendIntegerArray	(	struct WPI_DataLog *	datalog,
		int	entry,
		const int64_t *	arr,
		size_t	len,
		int64_t	timestamp
	)

Appends an integer array record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
arr	Integer array to record
len	Number of elements in array
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_AppendRaw()

void WPI_DataLog_AppendRaw	(	struct WPI_DataLog *	datalog,
		int	entry,
		const uint8_t *	data,
		size_t	len,
		int64_t	timestamp
	)

Appends a raw record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
data	Byte array to record
len	Length of byte array
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_AppendString()

void WPI_DataLog_AppendString	(	struct WPI_DataLog *	datalog,
		int	entry,
		const char *	value,
		size_t	len,
		int64_t	timestamp
	)

Appends a string record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
value	String value to record
len	Length of string
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_AppendStringArray()

void WPI_DataLog_AppendStringArray	(	struct WPI_DataLog *	datalog,
		int	entry,
		const WPI_DataLog_String *	arr,
		size_t	len,
		int64_t	timestamp
	)

Appends a string array record to the log.

Parameters

datalog	data log
entry	Entry index, as returned by WPI_DataLog_Start()
arr	String array to record
len	Number of elements in array
timestamp	Time stamp (may be 0 to indicate now)

WPI_DataLog_Create()

struct WPI_DataLog * WPI_DataLog_Create	(	const char *	dir,
		const char *	filename,
		double	period,
		const char *	extraHeader
	)

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

WPI_DataLog_Create_Func()

struct WPI_DataLog * WPI_DataLog_Create_Func	(	void(*)(void *ptr, const uint8_t *data, size_t len)	write,
		void *	ptr,
		double	period,
		const char *	extraHeader
	)

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 (data=NULL, len=0) when the thread is terminating.

Parameters

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

WPI_DataLog_Finish()

void WPI_DataLog_Finish	(	struct WPI_DataLog *	datalog,
		int	entry,
		int64_t	timestamp
	)

Finish an entry.

Parameters

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

WPI_DataLog_Flush()

void WPI_DataLog_Flush

(

struct WPI_DataLog *

datalog

)

Explicitly flushes the log data to disk.

Parameters

datalog

data log

WPI_DataLog_Pause()

void WPI_DataLog_Pause

(

struct WPI_DataLog *

datalog

)

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.

Parameters

datalog

data log

WPI_DataLog_Release()

void WPI_DataLog_Release

(

struct WPI_DataLog *

datalog

)

Releases a data log object.

Closes the file and returns resources to the system.

Parameters

datalog

data log

WPI_DataLog_Resume()

void WPI_DataLog_Resume

(

struct WPI_DataLog *

datalog

)

Resumes appending of data records to the log.

If called after Stop(), opens a new file (with random name if SetFilename was not called after Stop()) and appends Start records and schema data values for all previously started entries and schemas.

Parameters

datalog

data log

WPI_DataLog_SetFilename()

void WPI_DataLog_SetFilename	(	struct WPI_DataLog *	datalog,
		const char *	filename
	)

Change log filename.

Parameters

datalog	data log
filename	filename

WPI_DataLog_SetMetadata()

void WPI_DataLog_SetMetadata	(	struct WPI_DataLog *	datalog,
		int	entry,
		const char *	metadata,
		int64_t	timestamp
	)

Updates the metadata for an entry.

Parameters

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

WPI_DataLog_Start()

int WPI_DataLog_Start	(	struct WPI_DataLog *	datalog,
		const char *	name,
		const char *	type,
		const char *	metadata,
		int64_t	timestamp
	)

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

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

Returns

Entry index

WPI_DataLog_Stop()

void WPI_DataLog_Stop

(

struct WPI_DataLog *

datalog

)

Stops appending all records to the log, and closes the log file.

Parameters

datalog

data log