lite_sync/
oneshot.rs

1/// One-shot channel implementations for single-use value transfer
2///
3/// This module provides two variants of one-shot channels optimized for different use cases:
4///
5/// 一次性通道实现，用于单次值传递
6///
7/// 此模块提供两种针对不同使用场景优化的一次性通道变体：
8///
9/// # Variants | 变体
10///
11/// ## `lite` - Lightweight state-based oneshot
12///
13/// Optimized for small copyable states that can be encoded as u8.
14/// Zero heap allocation for the value itself (stored in AtomicU8).
15/// Perfect for completion notifications, simple enums, and boolean states.
16///
17/// 为可编码为 u8 的小型可复制状态优化。
18/// 值本身零堆分配（存储在 AtomicU8 中）。
19/// 非常适合完成通知、简单枚举和布尔状态。
20///
21/// ### Use cases | 使用场景:
22/// - Task completion notification (unit type `()`)
23/// - Small state machines (custom enums with `State` trait)
24/// - Boolean flags and simple status codes
25///
26/// ### Example:
27///
28/// ```
29/// use lite_sync::oneshot::lite::{Sender, error::RecvError};
30///
31/// # #[cfg(not(feature = "loom"))]
32/// # tokio_test::block_on(async {
33/// let (sender, receiver) = Sender::<()>::new();
34///
35/// tokio::spawn(async move {
36///     // ... do work ...
37///     sender.send(());
38/// });
39///
40/// receiver.await; // Wait for completion
41/// # });
42/// ```
43///
44/// ## `generic` - Generic value transfer oneshot
45///
46/// Supports arbitrary types with zero extra heap allocation for the value.
47/// Uses `UnsafeCell<MaybeUninit<T>>` + `AtomicU8` for lock-free value transfer.
48/// Value is stored directly in the structure, avoiding Box allocation.
49/// Ideal for transferring ownership of any data between tasks.
50///
51/// 支持任意类型，值无需额外堆分配。
52/// 使用 `UnsafeCell<MaybeUninit<T>>` + `AtomicU8` 实现无锁值传递。
53/// 值直接存储在结构体中，避免 Box 分配。
54/// 非常适合在任务间传递任意数据的所有权。
55///
56/// ### Use cases | 使用场景:
57/// - Request-response patterns with complex types
58/// - Transferring ownership of heap-allocated data
59/// - Sending results of arbitrary computations
60///
61/// ### Example:
62///
63/// ```
64/// use lite_sync::oneshot::generic::Sender;
65///
66/// # #[cfg(not(feature = "loom"))]
67/// # tokio_test::block_on(async {
68/// let (sender, receiver) = Sender::<String>::new();
69///
70/// tokio::spawn(async move {
71///     let result = "Hello, World!".to_string();
72///     sender.send(result).unwrap();
73/// });
74///
75/// let message = receiver.await.unwrap();
76/// assert_eq!(message, "Hello, World!");
77/// # });
78/// ```
79///
80/// # Performance Characteristics | 性能特点
81///
82/// ## `lite`
83/// - **Allocation**: Zero heap allocation for values
84/// - **Size**: Single `AtomicU8` + `AtomicWaker`
85/// - **Latency**: Minimal - direct atomic operations
86/// - **Best for**: High-frequency notifications
87///
88/// ## `generic`
89/// - **Allocation**: Zero heap allocation (value stored inline)
90/// - **Size**: `UnsafeCell<MaybeUninit<T>>` + `AtomicU8` + `AtomicWaker`
91/// - **Latency**: Low - single atomic state transition
92/// - **Best for**: Arbitrary data transfer
93///
94/// # Thread Safety | 线程安全
95///
96/// Both implementations are fully thread-safe and lock-free:
97/// - Sender can be called from any thread
98/// - Receiver can be awaited from any task
99/// - No spinlocks or blocking operations
100///
101/// 两种实现都是完全线程安全且无锁的：
102/// - Sender 可以从任何线程调用
103/// - Receiver 可以从任何任务 await
104/// - 无自旋锁或阻塞操作
105pub mod common;
106pub mod generic;
107pub mod lite;
lite_sync/oneshot.rs

lite_sync/
oneshot.rs
