Skip to main content

chronon::observe::ObservationBackend

Background worker that drains observability queues and writes output files. More...

#include <ObservationBackend.hpp>

Public Classes​

Name
structConfig

Public Types​

Name
using std::function< void(ObservationQueue::EventType type, const std::byte *data, size_t size)>EventHandler

Public Functions​

Name
~ObservationBackend()
voidwakeUp()
Set the wake flag; the spin-wait loop picks it up. Safe from any producer.
booltimelineEnabled() const
voidsubmitTimeline(TimelineStreamData && data)
Submit recorded timeline streams for inclusion in timeline.pftrace.
voidstop()
Drains remaining events before stopping.
voidstart()
voidsetTraceHandler(EventHandler handler)
voidsetStopToken(stdexec::inplace_stop_token token)
Hook a stop token for unified stop propagation.
voidsetSourceNameLookup(std::function< std::string_view(uint16_t)> lookup)
voidsetLogHandler(EventHandler handler)
voidsetDerivedCounterDefs(std::vector< DerivedCounterDef > defs)
const std::filesystem::path &outputDir() const
ObservationBackend &operator=(const ObservationBackend & ) =delete
boolisRunning() const
uint64_teventsProcessed() const
uint64_tbytesWritten() const
ObservationBackend(ObservationQueue & queue)
ObservationBackend(ObservationQueue & queue, const Config & config)
ObservationBackend(const ObservationBackend & ) =delete

Friends​

Name
structObservationBackendTestAccess

Detailed Description​

class chronon::observe::ObservationBackend;

Background worker that drains observability queues and writes output files.

Drains per-thread SPSC queues (traces/logs) and the shared queue (counter snapshots, lookahead commits), then routes each event to the text and/or Perfetto timeline sinks.

Output files:

  • events.log — text output (debug/info/warn/error, optional trace mirror).
  • timeline.pftrace — Perfetto timeline (trace events, counter tracks, and the scheduler execution timeline submitted at shutdown).
  • counters.csv — performance counter snapshots.

Public Types Documentation​

using EventHandler​

using chronon::observe::ObservationBackend::EventHandler = 
        std::function<void(ObservationQueue::EventType type, const std::byte* data, size_t size)>;

Public Functions Documentation​

function ~ObservationBackend​

~ObservationBackend()

function wakeUp​

void wakeUp()

Set the wake flag; the spin-wait loop picks it up. Safe from any producer.

function timelineEnabled​

inline bool timelineEnabled() const

True when this backend has an open Perfetto timeline sink. Reports false when the timeline is disabled by config or the file failed to open, so callers (scheduler timeline handoff) can fall back to standalone output.

function submitTimeline​

void submitTimeline(
    TimelineStreamData && data
)

Submit recorded timeline streams for inclusion in timeline.pftrace.

Thread-safe; intended for end-of-run handoff (e.g. the scheduler execution timeline). The data is written by the worker thread during stop(), after the final event drain, so callers must submit before stopping the backend.

function stop​

void stop()

Drains remaining events before stopping.

function start​

void start()

function setTraceHandler​

inline void setTraceHandler(
    EventHandler handler
)

function setStopToken​

inline void setStopToken(
    stdexec::inplace_stop_token token
)

Hook a stop token for unified stop propagation.

The backend installs a stop_callback that sets should_stop_ and wakes the worker when stop is requested externally (simulation termination, exception). PRECONDITION: must be called before start().

function setSourceNameLookup​

inline void setSourceNameLookup(
    std::function< std::string_view(uint16_t)> lookup
)

function setLogHandler​

inline void setLogHandler(
    EventHandler handler
)

function setDerivedCounterDefs​

void setDerivedCounterDefs(
    std::vector< DerivedCounterDef > defs
)

Called by ObservationManager before start(). Definitions are resolved to column indices once raw counter columns are finalized.

function outputDir​

inline const std::filesystem::path & outputDir() const

function operator=​

ObservationBackend & operator=(
    const ObservationBackend & 
) =delete

function isRunning​

inline bool isRunning() const

function eventsProcessed​

inline uint64_t eventsProcessed() const

function bytesWritten​

inline uint64_t bytesWritten() const

function ObservationBackend​

explicit ObservationBackend(
    ObservationQueue & queue
)

function ObservationBackend​

explicit ObservationBackend(
    ObservationQueue & queue,
    const Config & config
)

function ObservationBackend​

ObservationBackend(
    const ObservationBackend & 
) =delete

Friends​

friend ObservationBackendTestAccess​

friend struct ObservationBackendTestAccess(
    ObservationBackendTestAccess 
);

Updated on 2026-07-06 at 09:03:34 +0000