Skip to main content

chronon::observe::ObservationContext

Per-unit central context for counters, tracing, logging, and epochs. More...

#include <ObservationContext.hpp>

Public Classes​

Name
structLookaheadSyncNode

Public Types​

Name
enum class uint8_tLookaheadTransition { Rollback, None, Commit}
using std::function< uint64_t()>CycleProvider

Public Functions​

Name
~ObservationContext()
voidunregisterLookaheadSyncNode(LookaheadSyncNode & node)
const std::string &unitName() const
voidtrace(CategoryMask category, FormatId fmt_id)
template <typename... Args>
void		trace(CategoryMask category, FormatId fmt_id, Args &&... args)
Arguments are packed raw; backend reconstructs the message from the format ID.
booltimelineEventsEnabled() const
booltimelineEvent(CategoryMask category, TimelineEventKind kind, uint32_t track_id, uint16_t slot, uint16_t name_id, uint64_t payload, const TimelineArgValue * args, size_t arg_count, uint8_t flags =0)
Emit a timeline event (span begin/end, lane instant, counter sample).
uint32_tthreadId() const
uint16_tsourceId() const
boolshouldTrace(CategoryMask category) const
template <LogLevel Level>
bool		shouldLog() const
boolshouldEmitTimelineEvent(CategoryMask category, TimelineEventKind kind) const
voidsetTimelineEventsEnabled(bool enabled)
voidsetThreadId(uint32_t id)
voidsetQueue(ObservationQueue * queue)
voidsetLookaheadMode(bool enabled)
When enabled, events buffer locally rather than going to the global queue.
voidsetCycleProvider(CycleProvider provider)
voidsetCurrentCycleValue(uint64_t cycle)
Override the current-cycle value on this thread.
voidsetCountersEnabled(bool enabled)
voidrollbackEpoch()
Discards a speculative epoch: rolls back counters, drops buffered events.
voidrestorePendingTimelineStrings(size_t checkpoint)
voidregisterLookaheadSyncNode(LookaheadSyncNode & node)
voidregisterAllCounters(class CounterRegistry * registry)
Registers counter addresses with the registry for the pull-model snapshot.
ObservationQueue *queue()
const ObservationStats &observationStats() const
template <typename T >
TimelineArgValue		normalizeTimelineArgForEmit(const TypedArg< T > & arg)
uint64_tlookaheadEpochGeneration() const
template <LogLevel Level>
void		log(FormatId fmt_id)
template <LogLevel Level,typename... Args>
void		log(FormatId fmt_id, Args &&... args)
boolisLookaheadMode() const
LookaheadTransitionfirstLookaheadTransitionAfter(uint64_t generation) const
ObservationFilter &filter()
const ObservationFilter &filter() const
voidenableCategory(CategoryMask mask)
voiddisableCategory(CategoryMask mask)
const std::vector< DerivedCounterDef > &derivedCounterDefs() const
uint64_tcurrentCycle() const
boolcountersEnabled() const
FixedCounterStorage &counters()
const FixedCounterStorage &counters() const
voidcount(CounterId id, uint64_t delta =1)
Increment a counter.
voidcommitEpoch()
Confirms a speculative epoch: commits counters and flushes buffered events.
voidclearCycleOverride()
size_tcheckpointPendingTimelineStrings() const
voidaddDerivedCounterDef(DerivedCounterDef def)
Called by DerivedCounter::onContextAttached() during unit initialization.
ObservationContext(ObservationQueue * queue, CycleProvider cycle_provider, uint32_t thread_id =0, std::string unit_name ="", uint16_t source_id =0)

Detailed Description​

class chronon::observe::ObservationContext;

Per-unit central context for counters, tracing, logging, and epochs.

Hot paths are inline and allocation-free. Format strings are pre-registered: only IDs and args traverse the queue. Filtering uses bitmasks for O(1) checks; events flow into lock-free SPSC queues, one per producer thread.

Public Types Documentation​

enum LookaheadTransition​

EnumeratorValueDescription
Rollback
None
Commit

using CycleProvider​

using chronon::observe::ObservationContext::CycleProvider =  std::function<uint64_t()>;

Public Functions Documentation​

function ~ObservationContext​

inline ~ObservationContext()

function unregisterLookaheadSyncNode​

inline void unregisterLookaheadSyncNode(
    LookaheadSyncNode & node
)

function unitName​

inline const std::string & unitName() const

function trace​

inline void trace(
    CategoryMask category,
    FormatId fmt_id
)

function trace​

template <typename... Args>
inline void trace(
    CategoryMask category,
    FormatId fmt_id,
    Args &&... args
)

Arguments are packed raw; backend reconstructs the message from the format ID.

function timelineEventsEnabled​

inline bool timelineEventsEnabled() const

function timelineEvent​

inline bool timelineEvent(
    CategoryMask category,
    TimelineEventKind kind,
    uint32_t track_id,
    uint16_t slot,
    uint16_t name_id,
    uint64_t payload,
    const TimelineArgValue * args,
    size_t arg_count,
    uint8_t flags =0
)

Emit a timeline event (span begin/end, lane instant, counter sample).

Producer-side cost matches the instant trace path: one filter check, a fixed-size record fill, and a bounded arg memcpy into the SPSC queue. SpanEnd events skip temporal filtering: a span begun inside an observation window must still close when its end falls outside it. Ends without a preserved category are allowed when observation is enabled at all; unmatched ends are dropped by the backend's open-span table.

< Flag 1 = structured format.

function threadId​

inline uint32_t threadId() const

function sourceId​

inline uint16_t sourceId() const

function shouldTrace​

inline bool shouldTrace(
    CategoryMask category
) const

function shouldLog​

template <LogLevel Level>
inline bool shouldLog() const

function shouldEmitTimelineEvent​

inline bool shouldEmitTimelineEvent(
    CategoryMask category,
    TimelineEventKind kind
) const

function setTimelineEventsEnabled​

inline void setTimelineEventsEnabled(
    bool enabled
)

function setThreadId​

inline void setThreadId(
    uint32_t id
)

function setQueue​

inline void setQueue(
    ObservationQueue * queue
)

function setLookaheadMode​

inline void setLookaheadMode(
    bool enabled
)

When enabled, events buffer locally rather than going to the global queue.

function setCycleProvider​

inline void setCycleProvider(
    CycleProvider provider
)

function setCurrentCycleValue​

inline void setCurrentCycleValue(
    uint64_t cycle
)

Override the current-cycle value on this thread.

Used in parallel execution so each worker can stamp events with its own local cycle without races on the shared cycle_provider_.

function setCountersEnabled​

inline void setCountersEnabled(
    bool enabled
)

function rollbackEpoch​

inline void rollbackEpoch()

Discards a speculative epoch: rolls back counters, drops buffered events.

function restorePendingTimelineStrings​

inline void restorePendingTimelineStrings(
    size_t checkpoint
)

function registerLookaheadSyncNode​

inline void registerLookaheadSyncNode(
    LookaheadSyncNode & node
)

function registerAllCounters​

void registerAllCounters(
    class CounterRegistry * registry
)

Registers counter addresses with the registry for the pull-model snapshot.

function queue​

inline ObservationQueue * queue()

function observationStats​

inline const ObservationStats & observationStats() const

function normalizeTimelineArgForEmit​

template <typename T >
inline TimelineArgValue normalizeTimelineArgForEmit(
    const TypedArg< T > & arg
)

function lookaheadEpochGeneration​

inline uint64_t lookaheadEpochGeneration() const

function log​

template <LogLevel Level>
inline void log(
    FormatId fmt_id
)

function log​

template <LogLevel Level,
typename... Args>
inline void log(
    FormatId fmt_id,
    Args &&... args
)

function isLookaheadMode​

inline bool isLookaheadMode() const

function firstLookaheadTransitionAfter​

inline LookaheadTransition firstLookaheadTransitionAfter(
    uint64_t generation
) const

function filter​

inline ObservationFilter & filter()

function filter​

inline const ObservationFilter & filter() const

function enableCategory​

inline void enableCategory(
    CategoryMask mask
)

function disableCategory​

inline void disableCategory(
    CategoryMask mask
)

function derivedCounterDefs​

inline const std::vector< DerivedCounterDef > & derivedCounterDefs() const

function currentCycle​

inline uint64_t currentCycle() const

function countersEnabled​

inline bool countersEnabled() const

function counters​

inline FixedCounterStorage & counters()

function counters​

inline const FixedCounterStorage & counters() const

function count​

inline void count(
    CounterId id,
    uint64_t delta =1
)

Increment a counter.

PRECONDITION: Counter must have been added via addCounter() (no bounds check).

function commitEpoch​

inline void commitEpoch()

Confirms a speculative epoch: commits counters and flushes buffered events.

function clearCycleOverride​

inline void clearCycleOverride()

function checkpointPendingTimelineStrings​

inline size_t checkpointPendingTimelineStrings() const

function addDerivedCounterDef​

inline void addDerivedCounterDef(
    DerivedCounterDef def
)

Called by DerivedCounter::onContextAttached() during unit initialization.

function ObservationContext​

inline ObservationContext(
    ObservationQueue * queue,
    CycleProvider cycle_provider,
    uint32_t thread_id =0,
    std::string unit_name ="",
    uint16_t source_id =0
)

Parameters:

  • queue Shared observation queue (owned by simulation).
  • cycle_provider Returns current cycle when no per-thread override is set.
  • thread_id Thread ID (0..MAX_THREADS-1).
  • unit_name Name of the unit this context belongs to.
  • source_id Unique unit ID in the source-name registry.

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