Merge pull request #18 from userFRM/feat/lossy-subscribers

feat: subscribe_lossy — per-consumer delivery contracts on one ring

Author: userFRM

CHANGELOG.md

@@ -7,7 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- **`Subscribable::subscribe_lossy()`** — a subscriber that never gates the
+  publisher, even on a bounded channel. Registered subscribers keep their
+  no-loss guarantee while an observer (telemetry, logging, a debug tap) shares
+  the same ring without being able to stall it; when it falls behind it reports
+  `Lagged { skipped }` and `receive_ratio()` shows what it sampled. Both read the
+  same sequence numbers, so observations correlate with the messages a gating
+  consumer processed. Previously every subscriber on a bounded ring applied
+  backpressure, so mixing the two contracts required two rings and a second
+  publish.
+- **`Subscriber::cursor()`** — the sequence number this subscriber will read
+  next, for correlating positions across subscribers on a ring.
+- **`examples/degradation.rs` and `tests/degradation.rs`** — the slow-observer
+  and dead-consumer scenarios, run and asserted rather than described.
+
 ### Removed
+- **Multi-field tuple `Pod` impls.** `(A, B)` through the 12-element tuple used
+  `repr(Rust)` layout, so the compiler could insert padding — `(u8, u64)` carries
+  7 padding bytes. That made `channel::<(u8, u64)>()` undefined behaviour from
+  entirely safe code under `atomic-slots`, using impls the crate itself provided.
+  `()`, `(A,)`, arrays and primitives remain, none of which can carry padding.
+  Replace a multi-field tuple payload with a `#[repr(C)]` struct with explicit
+  padding fields. **Breaking.**
 - **`Publisher::sequence()`** — returned exactly what `published()` returns. Use
   `published()`, whose docs now carry the lag-computation note. **Breaking**;
   this makes the next release semver-major.
@@ -28,6 +50,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Crate packages exclude `docs/`, `verification/`, and `scripts/`.
 
 ### Fixed
+- **A newly registered subscriber could be lapped on a bounded channel.**
+  `subscribe()` read the head cursor and registered its tracker as two separate
+  steps. The publisher only rescans trackers when its cached slowest cursor says
+  it is close to lapping, so a subscriber that registered in the gap was invisible
+  to a publisher whose cached value came from a faster consumer — and could be
+  overwritten before the next rescan, losing messages the bounded channel had
+  promised it. Both steps now happen under the tracker lock, which orders them
+  against the scan. `subscribe_from_oldest` is inherently exempt: it starts at a
+  sequence the publisher was already entitled to overwrite, which registration
+  cannot retroactively reserve, and this is now documented on the method.
+- **Missing read-side `Acquire` fence in the default (volatile) slot read.**
+  `try_read` loaded the payload, then re-checked the stamp with an acquire *load*.
+  An acquire load is a one-way barrier: it stops later accesses from moving
+  earlier, but leaves the hardware free to satisfy the payload read *after* the
+  re-check has validated. On a weakly ordered CPU — aarch64, which this crate
+  supports and benchmarks — a reader could therefore return data from a later
+  overwrite as a valid read. Fixed by placing an `Acquire` fence between the
+  payload read and the re-check, mirroring both the `atomic-slots` path and the
+  `smp_rmb()` in the Linux kernel's `read_seqcount_retry()`. On x86 it emits no
+  instruction, but it is still a compiler barrier: the same-thread roundtrip
+  microbenchmark moves from ~3.0 ns to ~4.2 ns because the optimiser may no
+  longer reorder across it. Correctness on weakly ordered hardware is worth it,
+  and the cross-thread path — where the crate is actually used — moves ~2.8%.
 - **Out-of-bounds atomic access in the `atomic-slots` payload copy.** The striped
   copy rounded the payload up to whole `AtomicU64` stripes, so for any `T` whose
   size is not a multiple of 8 — `u8`, `u16`, `u32`, and most structs — the final
@@ -39,12 +84,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   in bounds with no change to slot layout and no extra operations in the common
   cases. Found by running Miri against the feature for the first time.
 - **Documented the padding requirement for `atomic-slots`.** A payload with
-  implicit padding — `(u8, u64)` has 7 such bytes, reachable through the crate's
-  own blanket tuple impls — leaves those bytes uninitialized, and reading them as
-  part of an atomic word is undefined regardless of the fix above. `Pod`'s safety
-  contract now states the no-padding requirement explicitly, and the feature's
-  soundness claim is scoped to padding-free payloads. Enforcing this at compile
-  time requires tightening the `Pod` contract and is deferred to a major release.
+  implicit padding leaves those bytes uninitialized, and reading them as part of
+  an atomic word is undefined regardless of the fix above. `Pod`'s safety contract
+  now states the no-padding requirement explicitly. The reachable-from-safe-code
+  case is closed by removing the multi-field tuple impls (see Removed); a
+  hand-written `unsafe impl Pod` for a padded struct remains the implementor's
+  responsibility, which the `miri (atomic-slots)` job is there to catch.
 - **`atomic-slots` is now covered by Miri in CI** (`miri (atomic-slots)` job). The
   existing `miri` job runs the default volatile slots single-threaded with all
   cross-thread tests skipped, so it could never have caught the above; the

README.md

@@ -14,7 +14,7 @@
 
 Photon Ring is a zero-allocation pub/sub crate for Rust built around pre-allocated ring buffers, per-slot stamp validation, and `T: Pod` payloads. It targets the part of concurrent systems where queueing overhead dominates: market data, telemetry fanout, staged pipelines, and other hot-path broadcast workloads where every subscriber should see every message.
 
-By default, slots use a volatile-based seqlock for maximum performance. With the `atomic-slots` feature, the same stamp protocol operates over `AtomicU64` stripes — **formally sound under the Rust abstract machine** with zero performance regression on x86-64.
+By default, slots use a volatile-based seqlock for maximum performance. With the `atomic-slots` feature, the same stamp protocol operates over `AtomicU64` stripes — **free of data races under the Rust abstract machine** for padding-free payloads, with zero performance regression on x86-64, and verified under Miri in CI.
 
 It is `no_std` compatible with `alloc`, supports named-topic buses and typed buses, and includes a pipeline builder for multi-stage thread topologies on supported desktop/server platforms.
 
@@ -57,7 +57,7 @@ Optional features:
 
 - `derive`: enables `#[derive(photon_ring::DerivePod)]` for user-defined `Pod` types.
 - `hugepages`: enables Linux memory controls such as `mlock`, `prefault`, and NUMA helpers.
-- `atomic-slots`: enables a data-race-free slot implementation that decomposes the payload into `AtomicU64` stripes (stepping down through `AtomicU32`/`U16`/`U8` for a trailing partial stripe) instead of `write_volatile`/`read_volatile`. Zero performance cost on x86-64; ~5-10ns reader overhead on ARM64 due to acquire fence. Eliminates the formal undefined behavior the default path carries under the Rust abstract machine, **for payloads with no padding bytes**. Its multi-threaded tests run under Miri in CI (`miri (atomic-slots)`), so the claim is machine-checked rather than asserted. Padding is the remaining gap: a type such as `(u8, u64)` has 7 uninitialized bytes, and reading those as part of an atomic word is itself undefined. Use `#[repr(C)]` with explicit padding fields (as the examples do) so every byte is initialized.
+- `atomic-slots`: enables a data-race-free slot implementation that decomposes the payload into `AtomicU64` stripes (stepping down through `AtomicU32`/`U16`/`U8` for a trailing partial stripe) instead of `write_volatile`/`read_volatile`. Zero performance cost on x86-64. On ARM64 both paths pay the same reader-side acquire fence, so `atomic-slots` costs nothing extra there either. Eliminates the formal undefined behavior the default path carries under the Rust abstract machine, **for payloads with no padding bytes**. Its multi-threaded tests run under Miri in CI (`miri (atomic-slots)`), so the claim is machine-checked rather than asserted. Padding is the remaining gap: a type such as `(u8, u64)` has 7 uninitialized bytes, and reading those as part of an atomic word is itself undefined. Use `#[repr(C)]` with explicit padding fields (as the examples do) so every byte is initialized.
 
 Rust 1.94+ is supported. For best performance, compile with `-C target-cpu=native` to enable `PREFETCHW` and other CPU-specific optimizations.
 
@@ -106,9 +106,10 @@ Photon Ring moves synchronization into each slot. Every slot carries its own seq
 3. if s1 < expected -> Empty
 4. if s1 > expected -> Lagged
 5. value = read_volatile(slot)    (direct read, T: Pod)
-6. s2 = stamp.load(Acquire)
-7. if s1 == s2 -> return
-8. else -> retry
+6. fence(Acquire)                 (payload read completes before re-check)
+7. s2 = stamp.load(Relaxed)
+8. if s1 == s2 -> return
+9. else -> retry
 ```
 
 ## Why this is fast
@@ -128,7 +129,7 @@ Measured with Criterion on an **Intel i7-10700KF** (8C/16T, 3.80 GHz, Linux 6.8,
 
 ### Against `disruptor-rs`
 
-- **Publish:** 2.8 ns (Intel) / 2.4 ns (M1 Pro), versus 30.6 ns / 15.3 ns for `disruptor-rs`
+- **Publish:** not directly comparable as measured here — photon's publish-only benchmark ran with no consumer attached, while `disruptor-rs` always runs one, so the gap partly measures cache-coherence traffic that photon never paid. Use the `publish, live consumer` benchmarks for a like-for-like figure.
 - **Cross-thread roundtrip:** 95 ns (Intel) / 130 ns (M1 Pro), versus 138 ns / 186 ns for `disruptor-rs`
 
 ### Core operations
@@ -153,6 +154,47 @@ Measured with Criterion on an **Intel i7-10700KF** (8C/16T, 3.80 GHz, Linux 6.8,
 - **Sustained throughput:** about 300M msg/s on Intel and 88M msg/s on M1 Pro
 - **Payload scaling:** at cache-line-sized payloads the copy is a few percent of latency — cross-core cache-coherence transfer dominates. The copy only becomes co-dominant in the KiB range; see [`docs/payload-scaling.md`](docs/payload-scaling.md)
 
+## Degradation, not deadlock
+
+Backpressure exists so a consumer that must not lose messages can stop the
+publisher. But two things should never stop the world: a consumer that is only
+*observing*, and a consumer that has *died*.
+
+Because each slot carries its own stamp, subscribers need no shared barrier —
+so a single ring can carry **different delivery contracts per consumer**:
+
+```rust
+let (mut pub_, subs) = channel_bounded::<Order>(1024, 0);
+
+let mut risk = subs.subscribe();              // gates the publisher, loses nothing
+let mut telemetry = subs.subscribe_lossy();   // never gates it, drops when behind
+```
+
+`risk` keeps its no-loss guarantee. `telemetry` is invisible to the publisher's
+backpressure scan, so however slow it gets it cannot stall order flow; when it
+falls behind it observes `Lagged { skipped }` with an exact count, and
+`receive_ratio()` reports what it sampled. Both read the same sequence numbers,
+so an observation can be correlated with the message the risk engine processed.
+
+A consumer that *dies* also releases the ring, **provided its `Subscriber` drops
+with it** — which is automatic when the consumer thread owns the subscriber, as
+the thread unwinds and `Drop` removes it from the backpressure set. A subscriber
+parked in long-lived shared state (an `Arc`'d registry, a supervisor struct)
+outlives its consumer and keeps gating the publisher, so don't do that with a
+tracked subscriber. A merely *wedged* consumer still applies backpressure — that
+is the guarantee working as intended.
+
+The no-loss guarantee is a property of each tracked subscriber's lifetime, not
+of the ring: if the last tracked subscriber goes away while lossy ones remain,
+nothing gates the publisher any more and the bounded ring behaves like a lossy
+one.
+
+Subscribers can also attach to a ring that is already running, so a lossy
+debug tap can be added and removed on a live system without perturbing it.
+
+`cargo run --release --example degradation` demonstrates both scenarios;
+`tests/degradation.rs` asserts them.
+
 ## Comparison
 
 | | Photon Ring | disruptor-rs (v4) | crossbeam-channel | bus |
@@ -242,11 +284,25 @@ Photon Ring offers two slot implementations, selectable at compile time:
 | **Formal status** | Data race under Rust abstract machine (practical UB) | **Formally sound** — no data races |
 | **Miri** | Flags multi-threaded tests | **Passes, enforced in CI** |
 | **x86-64 cost** | Baseline | **Zero** — identical `MOV` instructions |
-| **ARM64 cost** | Baseline | **+5-10 ns** reader (one `DMB ISHLD` fence) |
+| **ARM64 cost** | One `DMB ISHLD` reader fence (both paths) | Same fence — no additional cost |
 | **Precedent** | Same pattern as Linux kernel seqlocks (20+ years) | Per-word atomic decomposition, as in `atomic-memcpy` |
 
 > [!NOTE]
-> The default volatile-based implementation is **correct on all real hardware** (x86, ARM). The "UB" is purely under Rust's abstract machine — no compiler has ever miscompiled this pattern, and the Linux kernel relies on identical semantics. Enable `atomic-slots` if you need formal soundness, Miri compliance, or defense against hypothetical future compiler optimizations.
+> Both implementations place an `Acquire` fence between the payload read and the
+> stamp re-check — the same barrier the Linux kernel's `read_seqcount_retry()`
+> carries as `smp_rmb()`. Without it an acquire *load* is one-way and a weakly
+> ordered CPU may satisfy the payload read after the re-check has validated,
+> which would return data from a later overwrite. On x86 the fence emits no
+> instruction — TSO already orders load-load — but it is still a compiler
+> barrier, and measured at roughly +1.2 ns on the same-thread roundtrip
+> microbenchmark because it forbids reordering the optimiser was otherwise
+> free to do. That is the price of the guarantee, on every architecture.
+>
+> With that fence in place, the default volatile implementation produces correct
+> results on real hardware; what remains is that it is a data race under Rust's
+> abstract machine, which Miri reports and no compiler has yet exploited. Enable
+> `atomic-slots` for a build free of that race — machine-checked in CI, and free
+> on x86-64.
 
 > [!TIP]
 > Keep rich domain types at the edges and publish compact `Pod` messages in the middle. Convert enums, `Option`, booleans, and strings into explicit numeric fields or fixed-size buffers before calling `publish`.