Package edu.wpi.first.util.datalog

Class DataLog

java.lang.Object
edu.wpi.first.util.datalog.DataLog
All Implemented Interfaces:
AutoCloseable
public final class DataLog
extends Object
implements AutoCloseable
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 data log is periodically flushed to disk. It can also be explicitly flushed to disk by using the flush() function.

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.

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 Details

    • DataLog

      public DataLog​(String dir, String filename, double period, String 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

    • DataLog

      public DataLog​(String dir, String filename, double period)
      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

    • DataLog

      public DataLog​(String dir, String filename)
      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"

    • DataLog

      public DataLog​(String dir)
      Construct a new Data Log. The log will be initially created with a temporary filename.
      Parameters:
      dir - directory to store the log

    • DataLog

      public DataLog()
      Construct a new Data Log. The log will be initially created with a temporary filename.

  • Method Details

    • setFilename

      public void setFilename​(String filename)
      Change log filename.
      Parameters:
      filename - filename

    • flush

      public void flush()
      Explicitly flushes the log data to disk.

    • pause

      public void 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

      public void resume()
      Resumes appending of data records to the log.

    • start

      public int start​(String name, String type, String metadata, long 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:
      name - Name
      type - Data type
      metadata - Initial metadata (e.g. data properties)
      timestamp - Time stamp (may be 0 to indicate now)
      Returns:
      Entry index

    • start

      public int start​(String name, String type, String metadata)
      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)
      Returns:
      Entry index

    • start

      public int start​(String name, String type)
      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
      Returns:
      Entry index

    • finish

      public void finish​(int entry, long timestamp)
      Finish an entry.
      Parameters:
      entry - Entry index
      timestamp - Time stamp (may be 0 to indicate now)

    • finish

      public void finish​(int entry)
      Finish an entry.
      Parameters:
      entry - Entry index

    • setMetadata

      public void setMetadata​(int entry, String metadata, long timestamp)
      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)

    • setMetadata

      public void setMetadata​(int entry, String metadata)
      Updates the metadata for an entry.
      Parameters:
      entry - Entry index
      metadata - New metadata for the entry

    • appendRaw

      public void appendRaw​(int entry, byte[] data, long 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)

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • appendBoolean

      public void appendBoolean​(int entry, boolean value, long timestamp)

    • appendInteger

      public void appendInteger​(int entry, long value, long timestamp)

    • appendFloat

      public void appendFloat​(int entry, float value, long timestamp)

    • appendDouble

      public void appendDouble​(int entry, double value, long timestamp)

    • appendString

      public void appendString​(int entry, String value, long timestamp)

    • appendBooleanArray

      public void appendBooleanArray​(int entry, boolean[] arr, long timestamp)

    • appendIntegerArray

      public void appendIntegerArray​(int entry, long[] arr, long timestamp)

    • appendFloatArray

      public void appendFloatArray​(int entry, float[] arr, long timestamp)

    • appendDoubleArray

      public void appendDoubleArray​(int entry, double[] arr, long timestamp)

    • appendStringArray

      public void appendStringArray​(int entry, String[] arr, long timestamp)

    • getImpl

      public long getImpl()