From 9650e6733e955e1c1cc3e90aca41d5a8ccb907bc Mon Sep 17 00:00:00 2001
From: Peter Johnson <johnson.peter@gmail.com>
Date: Tue, 29 Mar 2022 12:28:59 -0700
Subject: [PATCH] [wpiutil] DataLog: Document finish and thread safety (NFC)
 (#4140)

---
 .../java/edu/wpi/first/util/datalog/DataLog.java | 11 +++++++++++
 wpiutil/src/main/native/include/wpi/DataLog.h    | 16 ++++++++++++++++
 2 files changed, 27 insertions(+)

diff --git a/wpiutil/src/main/java/edu/wpi/first/util/datalog/DataLog.java b/wpiutil/src/main/java/edu/wpi/first/util/datalog/DataLog.java
index 246a3b1db9..af2027c274 100644
--- a/wpiutil/src/main/java/edu/wpi/first/util/datalog/DataLog.java
+++ b/wpiutil/src/main/java/edu/wpi/first/util/datalog/DataLog.java
@@ -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 {
diff --git a/wpiutil/src/main/native/include/wpi/DataLog.h b/wpiutil/src/main/native/include/wpi/DataLog.h
index 46382b18c1..c66cd10cc6 100644
--- a/wpiutil/src/main/native/include/wpi/DataLog.h
+++ b/wpiutil/src/main/native/include/wpi/DataLog.h
@@ -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: