Team2890/allwpilib
4
0
Fork 0
mirror of https://github.com/wpilibsuite/allwpilib synced 2026-06-28 02:11:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

[wpiutil] DataLog: Document finish and thread safety (NFC) (#4140)

Browse Source
This commit is contained in:
Peter Johnson
2022-03-29 12:28:59 -07:00
committed by GitHub
parent c8905ec29a
commit 9650e6733e
2 changed files with 27 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
wpiutil/src/main/java/edu/wpi/first/util/datalog/DataLog.java
View File

@@ -10,6 +10,17 @@ package edu.wpi.first.util.datalog;
*
* <p>The data log is periodically flushed to disk. It can also be explicitly flushed to disk by
* using the flush() function.
*
* <p>The finish() function is needed only to indicate in the log that a particular entry is no
* longer being used (it releases the name to ID mapping). The finish() function 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.
*
* <p>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.
*/
@SuppressWarnings({"PMD.TooManyMethods", "PMD.ExcessivePublicCount"})
public final class DataLog implements AutoCloseable {

16
wpiutil/src/main/native/include/wpi/DataLog.h
View File

@@ -46,6 +46,22 @@ enum ControlRecordType {
*
* 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.
*/
class DataLog final {
public: