pub struct EventBuf<T: Copy, const N: usize> { /* private fields */ }Expand description
Bounded SPSC event buffer with backpressure.
When the buffer is full, Producer::push returns Err(val) instead
of overwriting, giving the producer a chance to retry, drop, or log.
The consumer drains items with Consumer::pop or Consumer::drain,
and can inspect the oldest item with Consumer::peek without consuming it.
§Panics
EventBuf::new()fails to compile (const assertion) whenN == 0on the host path; under Loom it panics at runtime.producer()/consumer()panic if called while another handle of the same kind is already active. UseEventBuf::try_producer/EventBuf::try_consumerfor a fallible alternative.
Implementations§
Source§impl<T: Copy, const N: usize> EventBuf<T, N>
impl<T: Copy, const N: usize> EventBuf<T, N>
Sourcepub const fn new() -> Self
pub const fn new() -> Self
Create a new, empty event buffer.
On the normal (non-Loom) build this is a const fn, so the buffer can
be placed in a static:
static BUF: EventBuf<u32, 64> = EventBuf::new();.
Under --cfg loom it is deliberately non-const — Loom’s atomics are
not const-constructible.
§Capacity 0 is a build failure
The N > 0 check is a const assertion, so a zero-capacity buffer
cannot be constructed at all – there is no runtime panic left to
catch, and therefore no way to write the negative case as a #[test].
This compile_fail doctest is that coverage, and pinning the error code
keeps it honest: without it the test would also pass on a typo.
let _ = ph_eventing::EventBuf::<u32, 0>::new();§Panics
Does not panic on the host path. Under Loom, where new is non-const,
N == 0 is a runtime assertion instead.
Sourcepub fn len(&self) -> usize
pub fn len(&self) -> usize
Approximate number of items currently buffered.
Returns a consistent (tail, head) snapshot. The value may still be
stale by the time the caller acts on it, but it will never spuriously
exceed capacity.
This never blocks: it makes a bounded number of attempts and then falls back to a clamped estimate, so a busy consumer cannot stall the caller.
Sourcepub fn try_producer(&self) -> Option<Producer<'_, T, N>>
pub fn try_producer(&self) -> Option<Producer<'_, T, N>>
Try to create the producer handle.
Returns None if a producer is already active. Prefer this over
producer when fallible bring-up is needed.
Sourcepub fn producer(&self) -> Producer<'_, T, N>
👎Deprecated since 0.2.0: on an embedded target a panic is a reset, and the panic machinery costs flash; use try_producer() and handle None
pub fn producer(&self) -> Producer<'_, T, N>
on an embedded target a panic is a reset, and the panic machinery costs flash; use try_producer() and handle None
Create the producer handle. Only one producer may be active.
§Deprecated
Prefer try_producer. This crate targets firmware,
where a panic is a reset and the panic machinery itself costs flash — a
code-size probe shows no panic strings reach the binary when only the
try_* constructors are used. The shorter, more discoverable name being
the hazardous one is the inversion this deprecation exists to correct.
Still sound, still tested, and convenient on a host where a panic is just a failed test. Scheduled for removal in 0.3.0.
§Panics
Panics if a producer handle is already active.
Sourcepub fn try_consumer(&self) -> Option<Consumer<'_, T, N>>
pub fn try_consumer(&self) -> Option<Consumer<'_, T, N>>
Try to create the consumer handle.
Returns None if a consumer is already active. Prefer this over
consumer when fallible bring-up is needed.
Sourcepub fn consumer(&self) -> Consumer<'_, T, N>
👎Deprecated since 0.2.0: on an embedded target a panic is a reset, and the panic machinery costs flash; use try_consumer() and handle None
pub fn consumer(&self) -> Consumer<'_, T, N>
on an embedded target a panic is a reset, and the panic machinery costs flash; use try_consumer() and handle None
Create the consumer handle. Only one consumer may be active.
§Deprecated
Prefer try_consumer. This crate targets firmware,
where a panic is a reset and the panic machinery itself costs flash — a
code-size probe shows no panic strings reach the binary when only the
try_* constructors are used. The shorter, more discoverable name being
the hazardous one is the inversion this deprecation exists to correct.
Still sound, still tested, and convenient on a host where a panic is just a failed test. Scheduled for removal in 0.3.0.
§Panics
Panics if a consumer handle is already active.