Struct TraceBufferHandle 

pub struct TraceBufferHandle { /* private fields */ }

Thread-safe handle for sharing a trace buffer across tasks.

This wraps a TraceBuffer in a mutex and adds a monotonically increasing sequence counter for event ordering.

Implementations

impl TraceBufferHandle

pub fn new(capacity: usize) -> Self

Creates a new trace buffer handle with the given capacity.

pub fn next_seq(&self) -> u64

Allocates and returns the next trace sequence number.

Callers that are about to push onto this shared handle should prefer record_event so sequence allocation and buffer insertion cannot be interleaved by another producer.

pub fn push_event(&self, event: TraceEvent)

Pushes a pre-built trace event into the buffer.

This preserves the event’s existing sequence number and advances the handle’s allocator past it. The latter matters when importing a replay prefix before recording new events. Callers that need a fresh sequence number from this handle should prefer record_event.

pub fn record_event<F>(&self, build: F)

where F: FnOnce(u64) -> TraceEvent,

Builds and pushes a trace event while holding the buffer lock.

This keeps sequence allocation and insertion serialized so concurrent producers cannot insert seq N + 1 ahead of seq N.

The builder runs while the buffer lock is held, so it should stay lightweight and must not re-enter the same trace handle.

pub fn snapshot(&self) -> Vec<TraceEvent>

Returns a snapshot of buffered events in seq order (oldest to newest).

br-asupersync-xh4efw: insertion order and seq order can differ — spawn-effect events allocate their seq at admission (via next_seq) but are pushed at deferred dispatch, after later-sequenced events may already be in the ring. The snapshot sorts by seq so consumers observe the per-task causal contract (a task’s Spawn seq precedes its Complete seq). Seqs may have gaps (an allocated-but-abandoned spawn effect never pushes); seq is an ordering key, not a dense index.

pub fn len(&self) -> usize

Returns the current number of buffered events.

pub fn capacity(&self) -> usize

Returns the configured buffer capacity.

pub fn total_pushed(&self) -> u64

Returns the total number of events pushed since creation.

This includes events that may no longer be present in the ring buffer due to capacity eviction.

pub fn is_empty(&self) -> bool

Returns true if the buffer is empty.

Trait Implementations

impl Clone for TraceBufferHandle

fn clone(&self) -> TraceBufferHandle

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TraceBufferHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.