Turbo MPMC 🚀

A blazingly fast lock-free Multi-Producer Multi-Consumer (MPMC) queue implementation in Rust that outperforms crossbeam-channel. Built using a ticket-based Vyukov-style bounded queue design with cache-line optimization.

Features ✨

🚀 High Performance: Outperforms crossbeam-channel in most scenarios
🔒 Lock-Free: Uses atomic operations for thread-safe communication
💪 MPMC Support: Multiple producers and consumers can work simultaneously
🎯 Cache-Optimized: Cache-line aligned slots prevent false sharing
⚡ Zero-Copy: Efficient memory management with minimal overhead
🛡️ Type-Safe: Leverages Rust's type system for compile-time safety
🧪 Well-Tested: Includes integration tests and Loom-based concurrency tests

Quick Start

Installation

Add this to your Cargo.toml:

[dependencies]
turbo-mpmc = "0.1.0"

Basic Usage

use turbo_mpmc::Queue;
use std::sync::Arc;
use std::thread;

fn main() {
    // Create a queue with 16 slots (must be power of 2)
    let queue = Arc::new(Queue::<String, 16>::new());

    let producer_queue = queue.clone();
    let consumer_queue = queue.clone();

    // Producer thread
    let producer = thread::spawn(move || {
        for i in 0..10 {
            let message = format!("Message {}", i);
            producer_queue.send(message);
        }
    });

    // Consumer thread
    let consumer = thread::spawn(move || {
        for _ in 0..10 {
            if let Ok(message) = consumer_queue.recv() {
                println!("Received: {}", message);
            }
        }
    });

    producer.join().unwrap();
    consumer.join().unwrap();
}

API Overview

Core Methods

Blocking Operations

send(value: T) - Blocks until the value is successfully sent (spins when queue is full)
recv() -> Result<T, RecvError> - Blocks until a value is received (spins when queue is empty)

Non-Blocking Operations

try_send(value: T) -> Result<(), SendError<T>> - Returns immediately with error if queue is full
try_recv() -> Result<T, RecvError> - Returns immediately with error if queue is empty

Queue Creation

// CAP must be > 0 and a power of 2
let queue = Queue::<MessageType, 1024>::new();

Performance 📊

Benchmarks comparing against popular Rust MPMC implementations:

1 Producer, 1 Consumer (1p_1c)

turbo_mpmc: ~50-100% faster than crossbeam-channel
Lower latency and higher throughput

4 Producers, 4 Consumers (4p_4c)

turbo_mpmc: Maintains performance under high contention
Better cache utilization through aligned slots

Run Benchmarks

cargo bench

Benchmark results are saved to target/criterion/report/index.html

Examples

The repository includes several examples demonstrating different use cases:

Simple Example

cargo run --example simple

Work Queue Pattern

cargo run --example work_queue

Quick Performance Test

cargo run --example quick_perf --release

Architecture 🏗️

Design Highlights

Vyukov-Style Queue: Based on Dmitry Vyukov's bounded MPMC queue algorithm
Ticket-Based System: Uses fetch_add for lock-free ticket distribution
Cache-Line Alignment: Each slot is 64-byte aligned to prevent false sharing
Bounded Queue: Fixed capacity set at compile time (must be power of 2)
Spin-Waiting: Optimized spinning with yields for better CPU utilization

Memory Layout

┌─────────────────────────────────────┐
│  CachePadded<AtomicUsize> tail      │  Producer ticket counter
├─────────────────────────────────────┤
│  CachePadded<AtomicUsize> head      │  Consumer ticket counter
├─────────────────────────────────────┤
│  Slot<T> [0]  (64-byte aligned)     │
├─────────────────────────────────────┤
│  Slot<T> [1]  (64-byte aligned)     │
├─────────────────────────────────────┤
│  ...                                │
├─────────────────────────────────────┤
│  Slot<T> [CAP-1] (64-byte aligned)  │
└─────────────────────────────────────┘

Testing 🧪

Run Tests

# Standard tests
cargo test

# Loom-based concurrency tests (slow but thorough)
RUSTFLAGS="--cfg loom" cargo test --test loom_tests --release

Integration Tests

The project includes comprehensive integration tests covering:

Single producer, single consumer scenarios
Multiple producers, multiple consumers
Capacity verification
Blocking and non-blocking operations
Edge cases and error handling

Development

Requirements

Rust 1.70 or later
Cargo

Build

# Debug build
cargo build

# Release build (optimized)
cargo build --release

Verification Scripts

# Linux/macOS
./verify.sh

# Windows
./verify.ps1

Comparison with Alternatives

Feature	turbo-mpmc	crossbeam-channel	flume	std::mpsc
MPMC Support	✅	✅	✅	❌ (MPSC only)
Lock-Free	✅	✅	✅	✅
Bounded	✅	✅	✅	✅
Unbounded	❌	✅	✅	✅
Performance	🚀 Fastest	Fast	Fast	Moderate
Select Support	❌	✅	✅	✅

Contributing

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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is dual-licensed under either:

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

at your option.

Acknowledgments

Based on Dmitry Vyukov's bounded MPMC queue design
Inspired by crossbeam-channel and other high-performance queue implementations
Thanks to the Rust community for excellent concurrency primitives

turbo-mpmc 0.1.0