Skip to main content

BufferReader

aimdb_core::buffer

Trait BufferReader 

Source 
pub trait BufferReader<T: Clone + Send>: Send {
    // Required methods
    fn poll_recv(&mut self, cx: &mut Context<'_>) -> Poll<Result<T, DbError>>;
    fn try_recv(&mut self) -> Result<T, DbError>;
}
Expand description

Reader trait for consuming values from a buffer

This is the object-safe service-provider interface that runtime adapters implement. It is poll-based — and therefore object-safe and zero-allocation — rather than async: an async fn on an erased trait forces a Pin<Box<dyn Future>> heap allocation on every call. Consumers do not call this directly; they use the Reader<T> handle returned by Consumer::subscribe, whose recv() is async and wraps poll_recv via core::future::poll_fn with no allocation.

Each reader is independent with its own state.

§Error Handling

  • Ok(value) - Successfully received a value
  • Err(BufferLagged) - Missed messages (SPMC ring only, can continue)
  • Err(BufferClosed) - Buffer closed (graceful shutdown)

§Contract (poll/try_recv interleaving and cancellation)

Every implementation in this workspace (tokio/embassy/wasm adapters) conforms — this section makes the contract explicit for future implementors.

  1. try_recv MAY be called between Pending poll_recv calls; implementations MUST NOT lose values or wakeups across the interleaving.
  2. A value claimed internally just before caller cancellation MUST be delivered on the next poll_recv/try_recv call — this is why, e.g., the tokio broadcast/watch readers keep a persistent ReusableBoxFuture across calls rather than dropping and recreating it per call.
  3. poll_recv MUST register the latest waker on every Pending return; spurious wakes are permitted (a registered waker firing with no corresponding new value is not a bug — callers must re-poll and tolerate a no-op).
  4. Lag MUST surface as Err(DbError::BufferLagged) plus a metrics add_dropped call on both poll_recv and try_recv.

Required Methods§

Source

fn poll_recv(&mut self, cx: &mut Context<'_>) -> Poll<Result<T, DbError>>

Poll for the next value.

Returns Poll::Ready(Ok(value)) when a value is available, Poll::Ready(Err(..)) on lag/closure, or Poll::Pending after registering cx.waker() to be woken when the next value arrives.

§Behavior by Buffer Type
  • SPMC Ring: Returns next value, or Lagged(n) if fell behind
  • SingleLatest: Waits for value change, returns most recent
  • Mailbox: Waits for slot value, takes and clears it
Source

fn try_recv(&mut self) -> Result<T, DbError>

Non-blocking receive — returns immediately.

Returns Err(DbError::BufferEmpty) if no pending values.

§Behavior by Buffer Type
  • SPMC Ring: Returns next buffered value, or BufferEmpty if caught up
  • SingleLatest: Returns value if changed since last read, or BufferEmpty
  • Mailbox: Takes and returns slot value, or BufferEmpty if empty

Dyn Compatibility§

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§