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/// # tokio_test::block_on(async {
32/// let (sender, receiver) = Sender::<()>::new();
33/// 
34/// tokio::spawn(async move {
35///     // ... do work ...
36///     sender.send(());
37/// });
38/// 
39/// receiver.await; // Wait for completion
40/// # });
41/// ```
42/// 
43/// ## `generic` - Generic value transfer oneshot
44/// 
45/// Supports arbitrary types with zero extra heap allocation for the value.
46/// Uses `UnsafeCell<MaybeUninit<T>>` + `AtomicU8` for lock-free value transfer.
47/// Value is stored directly in the structure, avoiding Box allocation.
48/// Ideal for transferring ownership of any data between tasks.
49/// 
50/// 支持任意类型，值无需额外堆分配。
51/// 使用 `UnsafeCell<MaybeUninit<T>>` + `AtomicU8` 实现无锁值传递。
52/// 值直接存储在结构体中，避免 Box 分配。
53/// 非常适合在任务间传递任意数据的所有权。
54/// 
55/// ### Use cases | 使用场景:
56/// - Request-response patterns with complex types
57/// - Transferring ownership of heap-allocated data
58/// - Sending results of arbitrary computations
59/// 
60/// ### Example:
61/// 
62/// ```
63/// use lite_sync::oneshot::generic::Sender;
64/// 
65/// # tokio_test::block_on(async {
66/// let (sender, receiver) = Sender::<String>::new();
67/// 
68/// tokio::spawn(async move {
69///     let result = "Hello, World!".to_string();
70///     sender.send(result).unwrap();
71/// });
72/// 
73/// let message = receiver.await.unwrap();
74/// assert_eq!(message, "Hello, World!");
75/// # });
76/// ```
77/// 
78/// # Performance Characteristics | 性能特点
79/// 
80/// ## `lite`
81/// - **Allocation**: Zero heap allocation for values
82/// - **Size**: Single `AtomicU8` + `AtomicWaker`
83/// - **Latency**: Minimal - direct atomic operations
84/// - **Best for**: High-frequency notifications
85/// 
86/// ## `generic`
87/// - **Allocation**: Zero heap allocation (value stored inline)
88/// - **Size**: `UnsafeCell<MaybeUninit<T>>` + `AtomicU8` + `AtomicWaker`
89/// - **Latency**: Low - single atomic state transition
90/// - **Best for**: Arbitrary data transfer
91/// 
92/// # Thread Safety | 线程安全
93/// 
94/// Both implementations are fully thread-safe and lock-free:
95/// - Sender can be called from any thread
96/// - Receiver can be awaited from any task
97/// - No spinlocks or blocking operations
98/// 
99/// 两种实现都是完全线程安全且无锁的：
100/// - Sender 可以从任何线程调用
101/// - Receiver 可以从任何任务 await
102/// - 无自旋锁或阻塞操作
103
104pub mod common;
105pub mod lite;
106pub mod generic;
lite_sync/oneshot.rs

lite_sync/
oneshot.rs
