Struct SeqRing

Source

pub struct SeqRing<T: Copy, const N: usize> { /* private fields */ }

Expand description

Overwrite ring for SPSC high-rate telemetry. Producer never waits; consumer may drop if it lags > N.

Implementations§

Source §

impl<T: Copy, const N: usize> SeqRing<T, N>

Source

pub const fn new() -> Self

Create a new ring buffer.

On the normal (non-Loom) build this is a const fn, so the ring can be placed in a static: static RING: SeqRing<u32, 64> = SeqRing::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::SeqRing::<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.

Source

pub const fn capacity(&self) -> usize

Maximum number of items the ring can hold.

Source

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.

Source

pub 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

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.

Source

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.

Source

pub 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

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.