DataStorageBase

DataStorageBase is the abstract root of Blackchirp’s experiment data-storage tree. Every object that persists experiment data to disk inherits from it. An instance is identified by a non-negative experiment number (d_number) and an optional base path (d_path); passing -1 for the number creates a transient (peak-up or dummy) instance for which all disk I/O is silently skipped.

The four pure-virtual methods define the acquisition lifecycle contract:

  • start() — called when acquisition begins; subclasses arm internal state.

  • advance() — called at each segment boundary; subclasses flush the current in-progress accumulation and prepare for the next segment.

  • save() — called to persist the current in-memory state.

  • finish() — called when acquisition ends; subclasses clear their acquiring flag.

The protected pu_mutex guards mutable state accessed from the acquisition and UI threads concurrently. The protected pu_csv owns a BlackchirpCSV helper scoped to the experiment directory. The writeMetadata and readMetadata helpers let subclasses persist a key-value map to a named CSV file within (an optional subdirectory of) the experiment directory; both delegate to pu_csv for the actual I/O.

The direct subclasses are:

AuxDataStorage, which collects time-series auxiliary hardware readings, has a similar role but does not inherit from DataStorageBase; it is owned and driven directly by Experiment.

The on-disk layout is described in Data Storage.

API Reference

class DataStorageBase

Abstract base class for all experiment data storage objects.

Every node in the experiment data-storage tree derives from DataStorageBase. The four pure-virtual methods (start, advance, save, finish) form the acquisition lifecycle interface that subclasses implement.

Subclassed by FidStorageBase, LifStorage, OverlayStorage

Public Functions

DataStorageBase(int number = -1, const QString &path = {})

Construct a storage object for the given experiment.

Parameters:

  • number – Experiment number; pass -1 for a transient (peak-up) instance.

  • path – Base path under which the experiment directory is located.

virtual ~DataStorageBase()

Destructor.

virtual void advance() = 0

Called at each segment boundary; flush the current segment and prepare for the next.

virtual void save() = 0

Persist the current in-memory state to disk.

virtual void start() = 0

Called when acquisition begins; implementations set the acquiring flag and initialize state.

virtual void finish() = 0

Called when acquisition ends; implementations clear the acquiring flag.

Public Members

const int d_number

Experiment number; -1 indicates a transient instance with no disk I/O.

const QString d_path

Base path of the experiment data directory.

Protected Functions

void writeMetadata(const QString &file, const std::map<QString, QVariant, std::less<>> &dat, const QString &dir = {})

Write a key-value map to a named CSV file within the experiment directory.

Parameters:

  • file – Filename (relative to the experiment directory, or to dir if given).

  • dat – Map of string keys to QVariant values to serialize.

  • dir – Optional subdirectory relative to the experiment directory.

void readMetadata(const QString &file, std::map<QString, QVariant, std::less<>> &out, const QString &dir = {})

Read a previously written metadata CSV back into a key-value map.

Parameters:

  • file – Filename (relative to the experiment directory, or to dir if given).

  • out – Map to populate with the deserialized key-value pairs.

  • dir – Optional subdirectory relative to the experiment directory.

Protected Attributes

std::unique_ptr<QMutex> pu_mutex

Mutex guarding mutable state shared across threads.

std::unique_ptr<BlackchirpCSV> pu_csv

CSV helper scoped to this experiment’s directory.