Skip to content

Old trgdataformats documentation, relevant here

John Freeman edited this page Aug 12, 2026 · 1 revision

JCF, Aug-12-2026: as part of my refactoring of trgdataformats, I removed some documentation from its README.md which relates more to code which currently exists in triggeralgs than in trgdataformats. It's presented as-is here; it looks largely correct but some details may be out of date

Design

The TriggerActivity and TriggerCandidate classes consist conceptually of two parts:

  1. The data fields of the class itself (time_start, algorithm, etc)
  2. The list of input objects (TriggerPrimitive for TriggerActivity, TriggerActivity for TriggerCandidate) that were used to create this TA/TC

An obvious implementation (and the one used previously in the triggeralgs package) has both items 1 and 2 as fields in the TA/TC object, eg:

struct TriggerActivity {
  timestamp_t time_start;
  timestamp_t time_end;
  // More fields...
  std::vector<TriggerPrimitive> inputs;
};

struct TriggerCandidate {
  timestamp_t time_start;
  timestamp_t time_end;
  // More fields...
  std::vector<TriggerActivity> inputs;
};

Here, TriggerCandidate contains a std::vector of TriggerActivity, which in turn contains a std::vector of TriggerPrimitive. Converting these nested vectors to a contiguous set of bytes that's representable as an overlay class is not straightforward (though probably possible). Instead, we split out the two conceptual parts of TA/TC like this:

struct TriggerCandidateData {
  timestamp_t time_start;
  timestamp_t time_end;
  // More fields...
};

struct TriggerCandidate : public TriggerCandidateData {
  // Data fields are inherited from TriggerCandidateData
  std::vector<TriggerActivityData> inputs;
};

// And similarly for TriggerActivity

The inputs member of TriggerCandidate now holds TriggerActivityData instead of TriggerActivity. Since TriggerActivityData is a "flat" class with no std::vector members, there are no nested vectors to unroll, and a simple overlay class implementation is possible:

struct TriggerCandidateOverlay {
  TriggerCandidateData data;
  uint64_t n_inputs; // Number of input objects
  TriggerActivityData inputs[];
};

(The last member is a "flexible array member", which is not standard C++, but is supported by GCC. An alternative would be to remove this data member and have member functions that get and set TriggerActivityData objects by index, stored contiguously in memory after the TriggerCandidateOverlay object itself. The flexible array member approach is more in keeping with the "overlay" style, but either way would work).

The implementation of the overlay type is in the file TriggerObjectOverlay.hpp. The actual implementation uses templates to allow TriggerActivityOverlay and TriggerCandidateOverlay to use common functions.

Clone this wiki locally