Skip to main content

chronon::observe::ObservationQueue

Lock-free SPSC ring buffer for observability events. More...

#include <ObservationQueue.hpp>

Public Classes​

Name
structRecordHeader
Header prefixed to every event in the queue.

Public Types​

Name
enum class uint8_tEventType { TRACE_EVENT = 1, SHUTDOWN = 255, LOG_EVENT = 2, EPOCH_ROLLBACK = 4, EPOCH_COMMIT = 3, COUNTER_SNAPSHOT = 0}

Public Functions​

Name
std::byte *prepareWrite(size_t n)
Reserve n bytes and acquire the writer lock.
std::byte *prepareRead()
ObservationQueue &operator=(const ObservationQueue & ) =delete
ObservationQueue &operator=(ObservationQueue && ) =delete
voidincrementDropped()
boolhasSpace(size_t n) const
voidforceCommitRead()
voidfinishWrite(size_t n)
PRECONDITION: writer lock held (from prepareWrite).
voidfinishRead(size_t n)
voidfinishAndCommitWrite(size_t n)
boolempty() const
uint64_tdroppedCount() const
voidcommitWrite()
Publishes the write and releases the writer lock.
voidcommitRead()
size_tcapacity() const
size_tbytesWritten() const
size_tbytesRead() const
ObservationQueue(size_t capacity =256 *1024)
ObservationQueue(const ObservationQueue & ) =delete
ObservationQueue(ObservationQueue && ) =delete

Detailed Description​

class chronon::observe::ObservationQueue;

Lock-free SPSC ring buffer for observability events.

Cache-line aligned atomics, cached position reads, power-of-2 capacity for bit-masking, batched commits, and 2x buffer mirroring (no wrap-around handling). Writer side is protected by a mutex to support multiple producers (MPSC in practice); reader side is single-consumer.

Public Types Documentation​

enum EventType​

EnumeratorValueDescription
TRACE_EVENT1
SHUTDOWN255
LOG_EVENT2
EPOCH_ROLLBACK4
EPOCH_COMMIT3
COUNTER_SNAPSHOT0

Public Functions Documentation​

function prepareWrite​

inline std::byte * prepareWrite(
    size_t n
)

Reserve n bytes and acquire the writer lock.

Return: Pointer to write location, or nullptr if full (lock released on failure).

function prepareRead​

inline std::byte * prepareRead()

Return: Pointer to next record, or nullptr if empty.

function operator=​

ObservationQueue & operator=(
    const ObservationQueue & 
) =delete

function operator=​

ObservationQueue & operator=(
    ObservationQueue && 
) =delete

function incrementDropped​

inline void incrementDropped()

function hasSpace​

inline bool hasSpace(
    size_t n
) const

function forceCommitRead​

inline void forceCommitRead()

function finishWrite​

inline void finishWrite(
    size_t n
)

PRECONDITION: writer lock held (from prepareWrite).

function finishRead​

inline void finishRead(
    size_t n
)

function finishAndCommitWrite​

inline void finishAndCommitWrite(
    size_t n
)

function empty​

inline bool empty() const

function droppedCount​

inline uint64_t droppedCount() const

function commitWrite​

inline void commitWrite()

Publishes the write and releases the writer lock.

function commitRead​

inline void commitRead()

function capacity​

inline size_t capacity() const

function bytesWritten​

inline size_t bytesWritten() const

function bytesRead​

inline size_t bytesRead() const

function ObservationQueue​

inline explicit ObservationQueue(
    size_t capacity =256 *1024
)

Parameters:

  • capacity Queue capacity in bytes; rounded up to a power of 2.

function ObservationQueue​

ObservationQueue(
    const ObservationQueue & 
) =delete

function ObservationQueue​

ObservationQueue(
    ObservationQueue && 
) =delete

Updated on 2026-05-26 at 05:42:33 +0000