ph_eventing/lib.rs
1//! Eventing primitives for no-std embedded targets.
2//!
3//! # Highlights
4//! - Lock-free SPSC sequence ring for high-throughput telemetry.
5//! - No allocation, no dynamic dispatch.
6//! - Designed for fast producers and potentially slower consumers.
7//!
8//! # Quick start
9//! ```
10//! use ph_eventing::SeqRing;
11//!
12//! let ring = SeqRing::<u32, 64>::new();
13//! let producer = ring.producer();
14//! let mut consumer = ring.consumer();
15//!
16//! producer.push(42);
17//! consumer.poll_one(|seq, v| {
18//! assert_eq!(seq, 1);
19//! assert_eq!(*v, 42);
20//! });
21//! ```
22//!
23//! # No-std
24//! The crate is `#![no_std]` by default. Tests require `std`.
25//!
26//! # Safety and concurrency
27//! This crate is SPSC by design: exactly one producer and one consumer must be active.
28//! `producer()`/`consumer()` will panic if called while another handle of the same kind is active.
29//! Using unsafe to bypass these constraints (or sharing handles concurrently) is undefined behavior.
30//!
31//! # Semantics
32//! - Sequence numbers are monotonically increasing `u32` values; `0` is reserved for "empty".
33//! - `poll_one`/`poll_up_to` drain in-order and return `PollStats`.
34//! - `latest` reads the newest value without advancing the consumer cursor.
35//! - If the consumer lags by more than `N`, it skips ahead and reports drops via `PollStats`.
36#![no_std]
37
38pub mod seq_ring;
39
40pub use seq_ring::{Consumer, PollStats, Producer, SeqRing};
41
42#[cfg(test)]
43extern crate std;