kovan_channel/
lib.rs

1#![doc(
2    html_logo_url = "https://raw.githubusercontent.com/vertexclique/kovan/master/art/kovan-square.svg"
3)]
4//! Multi-producer multi-consumer channels using Kovan for memory reclamation.
5//!
6//! This crate provides high-performance, lock-free channel implementations built on top of the
7//! [Kovan](https://github.com/vertexclique/kovan) memory reclamation system. It offers both
8//! unbounded and bounded channels, along with a powerful `select!` macro for concurrent operations.
9//!
10//! # Key Features
11//!
12//! - **Multi-producer Multi-consumer (MPMC)**: All channels support multiple concurrent senders and receivers.
13//! - **Lock-Free Operations**: Core operations are lock-free, ensuring system-wide progress.
14//! - **Blocking Support**: Channels support blocking `send` (when full) and `recv` (when empty) operations.
15//! - **Select Macro**: A `select!` macro for waiting on multiple channel operations, including a `default` case.
16//! - **Special Channels**: Includes `after`, `tick`, and `never` channels for timing and control flow.
17//! - **Kovan Integration**: Uses Kovan's safe memory reclamation to manage channel nodes without garbage collection.
18//!
19//! # Channel Flavors
20//!
21//! - [`unbounded()`]: A channel with infinite capacity. It never blocks on send, but can block on receive.
22//! - [`bounded()`]: A channel with fixed capacity. It blocks on send when full and on receive when empty.
23//!
24//! # Example
25//!
26//! ```rust
27//! use kovan_channel::{unbounded, select};
28//! use std::thread;
29//!
30//! let (s1, r1) = unbounded::<i32>();
31//! let (s2, r2) = unbounded::<i32>();
32//!
33//! thread::spawn(move || {
34//!     s1.send(10);
35//! });
36//!
37//! thread::spawn(move || {
38//!     s2.send(20);
39//! });
40//!
41//! select! {
42//!     v1 = r1 => println!("Received from s1: {}", v1),
43//!     v2 = r2 => println!("Received from s2: {}", v2),
44//! }
45//! ```
46//!
47//! # Safety
48//!
49//! This crate uses `unsafe` code internally for performance and to interface with the Kovan memory
50//! reclamation system. However, it exposes a safe API. Memory safety is guaranteed by Kovan's
51//! epoch-based reclamation, ensuring that nodes are only freed when no threads are accessing them.
52
53#![warn(missing_docs)]
54/// Channel flavors (unbounded, bounded, special).
55pub mod flavors;
56/// Select macro implementation.
57pub mod select;
58/// Signal mechanism for thread synchronization.
59pub mod signal;
60
61pub use flavors::bounded;
62pub use flavors::unbounded;
63
64/// Creates a channel of unbounded capacity.
65///
66/// This channel has a growable buffer that can hold any number of messages.
67pub fn unbounded<T: 'static>() -> (unbounded::Sender<T>, unbounded::Receiver<T>) {
68    unbounded::channel()
69}
70
71/// Creates a channel of bounded capacity.
72///
73/// This channel has a buffer of fixed capacity.
74pub fn bounded<T: 'static>(cap: usize) -> (bounded::Sender<T>, bounded::Receiver<T>) {
75    bounded::channel(cap)
76}
77
78pub use flavors::after::after;
79pub use flavors::never::never;
80pub use flavors::tick::tick;
kovan_channel/lib.rs

kovan_channel/
lib.rs
