Struct CdcBuffer 

pub struct CdcBuffer { /* private fields */ }

CDC event buffer — circular buffer of change events.

Splits the “next LSN” counter (write-contended on every emit) from the event ring (short-hold push/pop) so that concurrent emitters don’t serialise on a single RwLock. The previous design used one RwLock<CdcState> that turned every insert into a write-lock acquire, capping 16-way concurrent writes at ~1000 ops/s (each writer paid ~1ms queueing for the same mutex even though the work it guarded was a one-line VecDeque push).

New layout:

• LSN is an AtomicU64, assigned with fetch_add(1). Zero contention.
• Events are guarded by a parking_lot::Mutex<VecDeque>. The critical section is pop_front (if full) + push_back — microseconds at most, parking-free at low contention.

Readers (poll, current_lsn, stats) take the same mutex briefly; they’re cold paths compared to the write hot path.

Implementations

impl CdcBuffer

pub fn new(max_size: usize) -> CdcBuffer

Create a new CDC buffer with maximum capacity.

pub fn emit( &self, operation: ChangeOperation, collection: &str, entity_id: u64, entity_kind: &str, ) -> u64

Emit a change event into the buffer. changed_columns defaults to None for backwards compatibility; call sites that have a damage vector available should use Self::emit_with_columns instead.

pub fn emit_with_columns( &self, operation: ChangeOperation, collection: &str, entity_id: u64, entity_kind: &str, changed_columns: Option<Vec<String>>, ) -> u64

Emit a change event with an optional list of column names that were affected. Use from update paths that have already computed a RowDamageVector so CDC consumers can filter by touched column without re-diffing.

pub fn emit_batch_same_collection<I>( &self, operation: ChangeOperation, collection: &str, entity_kind: &str, entity_ids: I, ) -> Vec<u64>

where I: IntoIterator<Item = u64>, <I as IntoIterator>::IntoIter: ExactSizeIterator,

Emit many same-collection events with one LSN reservation and one ring-buffer lock. This is used by bulk insert paths that do not need per-row logical-WAL records.

pub fn emit_kv( &self, operation: ChangeOperation, collection: &str, key: &str, entity_id: u64, before: Option<Value>, after: Option<Value>, ) -> u64

Emit a committed logical KV event into the same CDC ring used by result-cache invalidation and /changes consumers.

pub fn poll(&self, since_lsn: u64, max_count: usize) -> Vec<ChangeEvent>

Poll for events since a given LSN.

pub fn current_lsn(&self) -> u64

Get the current (latest) LSN.

pub fn set_current_lsn(&self, lsn: u64)

Restore the LSN cursor after process restart. Only advances; never rewinds. Under concurrent emit this is guarded by a compare-exchange loop.

pub fn oldest_lsn(&self) -> Option<u64>

Get the oldest available LSN (or None if empty).

pub fn stats(&self) -> CdcStats

Get buffer stats (single lock acquisition — no deadlock risk).