lite-sync

Fast, lightweight async primitives: SPSC channel, oneshot, notify, and atomic waker.

Overview

lite-sync provides a collection of optimized synchronization primitives designed for low latency and minimal allocations. These primitives are built from the ground up with performance in mind, offering alternatives to heavier standard library implementations.

Features

Zero or minimal allocations: Most primitives avoid heap allocations entirely
Lock-free algorithms: Using atomic operations for maximum concurrency
Single-waiter optimization: Specialized for common SPSC (Single Producer Single Consumer) patterns
Inline storage: Support for stack-allocated buffers to avoid heap allocations
Type-safe: Leverages Rust's type system to enforce correctness at compile time

Installation

Add this to your Cargo.toml:

[dependencies]

lite-sync = "0.1"

Modules

`oneshot`

One-shot completion notification with customizable state.

Perfect for signaling task completion with minimal overhead. Supports custom state types through the State trait, allowing you to communicate not just "done" but also "how it finished" (success, failure, timeout, etc.).

Key optimizations:

Zero Box allocation for waker storage
Direct Future implementation for ergonomic .await
Fast path for immediate completion

`spsc`

High-performance async SPSC (Single Producer Single Consumer) channel.

Built on smallring for efficient ring buffer operations with inline storage support. Type-safe enforcement of single producer/consumer semantics eliminates synchronization overhead.

Key optimizations:

Zero-cost interior mutability using UnsafeCell
Inline buffer support for small channels
Batch send/receive operations
Single-waiter notification

`notify`

Lightweight single-waiter notification primitive.

Much lighter than tokio::sync::Notify when you only need to wake one task at a time. Ideal for internal synchronization in other primitives.

`atomic_waker`

Atomic waker storage with state machine synchronization.

Based on Tokio's AtomicWaker but simplified for specific use cases. Provides safe concurrent access to a waker without Box allocation.

Examples

One-shot completion with custom state

use lite_sync::oneshot::{State, Sender};

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum TaskResult {
    Success,
    Error,
}

impl State for TaskResult {
    fn to_u8(&self) -> u8 {
        match self {
            TaskResult::Success => 1,
            TaskResult::Error => 2,
        }
    }
    
    fn from_u8(value: u8) -> Option<Self> {
        match value {
            1 => Some(TaskResult::Success),
            2 => Some(TaskResult::Error),
            _ => None,
        }
    }
    
    fn pending_value() -> u8 { 0 }
}

#[tokio::main]
async fn main() {
    let (sender, receiver) = Sender::<TaskResult>::new();
    
    tokio::spawn(async move {
        // Do some work...
        sender.notify(TaskResult::Success);
    });
    
    let result = receiver.await;
    assert_eq!(result, TaskResult::Success);
}

SPSC channel with inline storage

use lite_sync::spsc::channel;
use std::num::NonZeroUsize;

#[tokio::main]
async fn main() {
    // Channel with capacity 32, inline buffer size 8
    let (tx, rx) = channel::<i32, 8>(NonZeroUsize::new(32).unwrap());
    
    tokio::spawn(async move {
        for i in 0..10 {
            tx.send(i).await.unwrap();
        }
    });
    
    let mut sum = 0;
    while let Some(value) = rx.recv().await {
        sum += value;
    }
    assert_eq!(sum, 45); // 0+1+2+...+9
}

Single-waiter notification

use lite_sync::notify::SingleWaiterNotify;
use std::sync::Arc;

#[tokio::main]
async fn main() {
    let notify = Arc::new(SingleWaiterNotify::new());
    let notify_clone = notify.clone();
    
    tokio::spawn(async move {
        // Do some work...
        notify_clone.notify_one();
    });
    
    notify.notified().await;
}

Simple completion notification (unit type)

use lite_sync::oneshot::Sender;

#[tokio::main]
async fn main() {
    let (sender, receiver) = Sender::<()>::new();
    
    tokio::spawn(async move {
        // Task completes
        sender.notify(());
    });
    
    receiver.await; // Wait for completion
}

Benchmarks

Performance benchmarks are available in the benches/ directory. Run them with:

cargo bench

Key characteristics:

Oneshot: Extremely fast for immediate completion, optimized async wait path
SPSC: Low latency per-message overhead with efficient batch operations
Notify: Minimal notification roundtrip time

Safety

All primitives use unsafe internally for performance but expose safe APIs. Safety is guaranteed through:

Type system enforcement of single ownership (no Clone on SPSC endpoints)
Atomic state machines for synchronization
Careful ordering of atomic operations
Comprehensive test coverage including concurrent scenarios

Minimum Supported Rust Version (MSRV)

Rust 2024 edition (Rust 1.85.0 or later)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

Licensed under either of:

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

lite-sync 0.1.1