refactor(channels): prototype the 0.7 design

Author: tisonkun

CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project will be documented in this file.
 
 ## Unreleased
 
+### Breaking changes
+
+* Group all channel families under `mea::channel` and replace the previous root-level oneshot, mpsc, and broadcast implementations with a shared correctness-first design.
+* Use `is_disconnected` consistently for channel endpoint state queries.
+
+### New features
+
+* Add SPSC, MPSC, SPMC, and MPMC queues with rendezvous, bounded, and unbounded capacities.
+* Add explicit bounded-queue replacement strategies that return the displaced value.
+* Add overflow, backpressure, and unbounded broadcast retention policies.
+* Add a coalescing watch channel.
+* Add single-producer and multi-producer Disruptor-style multicast sequencers.
+* Add `sync`, `channel`, `coordination`, and `atomic` public module groups for the proposed 0.7 layout.
+
 ### Bug fixes
 
 * Prevent `OwnedMappedMutexGuard` from allowing invalid lifetime coercions. ([#121](https://github.com/fast/mea/pull/121))

README.md

@@ -22,6 +22,8 @@ MEA is a runtime-agnostic library providing essential synchronization primitives
 
 ## Features
 
+### Synchronization
+
 * [**Barrier**](https://docs.rs/mea/*/mea/barrier/struct.Barrier.html): A synchronization primitive that enables tasks to wait until all participants arrive.
 * [**Condvar**](https://docs.rs/mea/*/mea/condvar/struct.Condvar.html): A condition variable that allows tasks to wait for a notification.
 * [**Latch**](https://docs.rs/mea/*/mea/latch/struct.Latch.html): A synchronization primitive that allows one or more tasks to wait until a set of operations completes.
@@ -32,12 +34,23 @@ MEA is a runtime-agnostic library providing essential synchronization primitives
 * [**RwLock**](https://docs.rs/mea/*/mea/rwlock/struct.RwLock.html): A reader-writer lock that allows multiple readers or a single writer at a time.
 * [**Semaphore**](https://docs.rs/mea/*/mea/semaphore/struct.Semaphore.html): A synchronization primitive that controls access to a shared resource.
 * [**WaitGroup**](https://docs.rs/mea/*/mea/waitgroup/struct.WaitGroup.html): A synchronization primitive that allows waiting for multiple tasks to complete.
+
+### Channels
+
+All channel families are grouped under [**mea::channel**](https://docs.rs/mea/*/mea/channel/):
+
+* **oneshot** transfers one value once.
+* **spsc**, **mpsc**, **spmc**, and **mpmc** provide rendezvous, bounded, and unbounded competing-consumer queues.
+* **broadcast** provides bounded overflow, bounded backpressure, and unbounded multicast retention.
+* **watch** distributes the latest state while coalescing intermediate versions.
+* **disruptor** provides single-producer and multi-producer bounded multicast sequencers.
+
+See the [channel design for 0.7](docs/channel-design.md) for the topology matrix, overload policies, cancellation rules, Disruptor invariants, and proposed Cargo feature groups.
+
+### Coordination and atomic utilities
+
 * [**admission::FairShare**](https://docs.rs/mea/*/mea/admission/struct.FairShare.html): A work-conserving admission policy that fairly shares bounded concurrency across keys.
 * [**atomicbox**](https://docs.rs/mea/*/mea/atomicbox/): A safe, owning version of AtomicPtr for heap-allocated data.
-* [**broadcast**](https://docs.rs/mea/*/mea/broadcast/): A multi-producer, multi-consumer broadcast channel.
-* [**mpsc::bounded**](https://docs.rs/mea/*/mea/mpsc/fn.bounded.html): A multi-producer, single-consumer bounded queue for sending values between asynchronous tasks.
-* [**mpsc::unbounded**](https://docs.rs/mea/*/mea/mpsc/fn.unbounded.html): A multi-producer, single-consumer unbounded queue for sending values between asynchronous tasks.
-* [**oneshot::channel**](https://docs.rs/mea/*/mea/oneshot/): A one-shot channel for sending a single value between tasks.
 * [**shutdown**](https://docs.rs/mea/*/mea/shutdown/): A composite synchronization primitive for managing shutdown signals.
 * [**singleflight::Group**](https://docs.rs/mea/*/mea/singleflight/): A duplicate function call suppression mechanism.
 
@@ -55,7 +68,7 @@ All synchronization primitives in this library are runtime-agnostic, meaning the
 
 ## Thread Safety
 
-All types in this library implement `Send` and `Sync`, making them safe to share across thread boundaries. This is essential for concurrent programming where data needs to be accessed from multiple threads.
+Types implement `Send` when their contained values can cross thread boundaries. A channel endpoint is `Sync` and cloneable when that endpoint supports multiple producers or multiple consumers; a single-side endpoint deliberately requires exclusive access.
 
 ## Minimum Supported Rust Version (MSRV)
 
@@ -82,8 +95,7 @@ This crate collects runtime-agnostic synchronization primitives from spare parts
 * **Semaphore** is derived from `tokio::sync::Semaphore`, without `close` method since it is quite tricky to use. And thus, this semaphore doesn't have the limitation of max permits. Besides, new methods like `forget_exact` are added to fit the specific use case.
 * **WaitGroup** is inspired by [`waitgroup-rs`](https://github.com/laizy/waitgroup-rs), providing different API flavor with a different implementation based on the internal `CountdownState` primitive.
 * **atomicbox** is forked from [`atomicbox`](https://github.com/jorendorff/atomicbox/) at commit 07756444.
-* **broadcast::overflow::channel** is derived from `tokio::sync::broadcast::channel`, with a different implementation based on the internal `WaitSet` primitive.
-* **oneshot::channel** is derived from [`oneshot`](https://github.com/faern/oneshot), with significant simplifications since we need not support synchronized receiving functions.
+* **channel** is a correctness-first implementation of one-shot, competing-consumer, multicast, coalescing, and Disruptor-style sequenced channels using runtime-agnostic task parking.
 
 Other parts are written from scratch.