Struct Shard 

pub struct Shard {
    pub id: u16,
    /* private fields */
}

A single shard with its own ring buffer and timestamp generator.

Fields

id: u16

Shard identifier.

Implementations

impl Shard

pub fn new(id: u16, capacity: usize) -> Self

Create a new shard.

pub fn with_metrics( id: u16, capacity: usize, metrics: Arc<ShardMetricsCollector>, ) -> Self

Create a new shard with a metrics collector for dynamic scaling.

pub fn counters(&self) -> Arc<ShardCounters>

Clone the atomic counter handle (for lock-free aggregation).

pub fn set_metrics_collector(&mut self, metrics: Arc<ShardMetricsCollector>)

Set the metrics collector.

pub fn try_push_raw(&mut self, raw: Bytes) -> Result<u64, IngestionError>

Try to push a raw event (pre-serialized bytes) into the shard’s ring buffer. Returns the assigned insertion timestamp on success.

This is the fastest ingestion path - no serialization or hashing needed.

PERF_AUDIT §1.3 — dynamic-scaling instrumentation subsamples on a 1-in-METRICS_SAMPLE_STRIDE cadence. Pre-fix the path took Instant::now() twice (Windows QPC, ~15–30 ns each) plus a CAS-loop on push_latency under the shard mutex per event when a metrics_collector was set — ~60–120 ns of pure instrumentation overhead per event for dynamic-scaling deployments. Now: per-event counters (events_in_window / pushes_since_drain_start) still bump at full resolution, but the latency clock-read pair + CAS update + buffer-length store only fire every Nth successful push. The quanta TSC clock (~1–5 ns per read) replaces Instant::now() at the sampling boundary so even the sampled cost is ~10× smaller than the pre-fix path.

pub fn try_push(&mut self, raw: JsonValue) -> Result<u64, IngestionError>

Try to push a JSON value into the shard’s ring buffer. Returns the assigned insertion timestamp on success.

This serializes the value once before storing.

Same dynamic-scaling subsampling discipline as Self::try_push_raw — see that method’s PERF_AUDIT §1.3 commentary for the rationale.

pub fn pop_batch(&mut self, max: usize) -> Vec<InternalEvent>

Pop a batch of events from the ring buffer.

Allocates a fresh Vec. Prefer pop_batch_into in drain loops where the per-cycle Vec allocation should happen outside the shard mutex.

pub fn pop_batch_into( &mut self, dst: &mut Vec<InternalEvent>, max: usize, ) -> usize

Pop a batch of events into a caller-owned buffer.

Append semantics: does not clear dst; reserves count slots and pushes drained elements onto the end. Returns the number drained this call. Use this in steady-state drain loops where the caller keeps a scratch Vec across cycles, so the per-cycle allocation moves out of the consumer’s critical section.

pub fn try_pop(&mut self) -> Option<InternalEvent>

Try to pop a single event from the ring buffer.

pub fn len(&self) -> usize

Get the current buffer length.

pub fn is_empty(&self) -> bool

Check if the buffer is empty.

pub fn is_full(&self) -> bool

Check if the buffer is full.

pub fn fill_ratio(&self) -> f64

Get the fill ratio (0.0 - 1.0).

pub fn capacity(&self) -> usize

Get the ring buffer capacity.

pub fn stats(&self) -> ShardStats

Get a snapshot of shard statistics.

pub fn record_batch_dispatch(&self)

Record a batch dispatch.