DataLog¶
- class wpiutil.log.DataLog(*args, **kwargs)¶
Bases:
pybind11_object
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.
Overloaded function.
__init__(self: wpiutil._wpiutil.log.DataLog, dir: str = ‘’, filename: str = ‘’, period: float = 0.25, extraHeader: str = ‘’) -> None
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
__init__(self: wpiutil._wpiutil.log.DataLog, write: Callable[[buffer], None], period: float = 0.25, extraHeader: str = ‘’) -> None
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
- appendBoolean(entry: int, value: bool, timestamp: int) None ¶
- appendBooleanArray(entry: int, arr: List[bool], timestamp: int) None ¶
- appendDouble(entry: int, value: float, timestamp: int) None ¶
- appendDoubleArray(entry: int, arr: List[float], timestamp: int) None ¶
- appendFloat(entry: int, value: float, timestamp: int) None ¶
- appendFloatArray(entry: int, arr: List[float], timestamp: int) None ¶
- appendInteger(entry: int, value: int, timestamp: int) None ¶
- appendIntegerArray(entry: int, arr: List[int], timestamp: int) None ¶
- appendRaw(entry: int, data: buffer, timestamp: int) None ¶
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(entry: int, data: List[buffer], timestamp: int) None ¶
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(entry: int, value: str, timestamp: int) None ¶
- appendStringArray(entry: int, arr: List[str], timestamp: int) None ¶
- finish(entry: int, timestamp: int = 0) None ¶
Finish an entry.
- Parameters
entry – Entry index
timestamp – Time stamp (may be 0 to indicate now)
- flush() None ¶
Explicitly flushes the log data to disk.
- pause() None ¶
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() None ¶
Resumes appending of data records to the log.
- setFilename(filename: str) None ¶
Change log filename.
- Parameters
filename – filename
- setMetadata(entry: int, metadata: str, timestamp: int = 0) None ¶
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(name: str, type: str, metadata: str = '', timestamp: int = 0) int ¶
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