SMR-Swap: Version-Based Single-Writer Multiple-Reader Swap Container

A high-performance Rust library for safely sharing mutable data between a single writer and multiple readers using version-based memory reclamation.

中文文档 | English

Features

• Minimal-Locking: Read operations are wait-free; write operations only require synchronization during garbage collection
• High Performance: Optimized for both read and write operations
• Simple API: Only three core types: SmrSwap, LocalReader, ReadGuard
• Memory Safe: Uses version-based reclamation (via swmr-cell) to prevent use-after-free
• Zero-Copy Reads: Readers get direct references to the current value via RAII guards
• no_std Compatible: Supports no_std environments (requires alloc)

Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
smr-swap = "0.8"

no_std Usage

Use with default-features = false and enable spin feature (if you need the default spinlock-based mutex implementation in swmr-cell):

[dependencies]
smr-swap = { version = "0.8", default-features = false, features = ["spin"] }

Basic Usage

use smr_swap::SmrSwap;
use std::thread;

fn main() {
    // Create a new SMR container
    let mut swap = SmrSwap::new(0);

    // Get a thread-local reader
    let local = swap.local();

    // Writer stores a new value
    swap.store(1);

    // Read in another thread
    let local2 = swap.local();
    let handle = thread::spawn(move || {
        let guard = local2.load();
        assert_eq!(*guard, 1);
    });

    handle.join().unwrap();
}

Multi-Thread Reading

use smr_swap::SmrSwap;
use std::thread;

fn main() {
    let mut swap = SmrSwap::new(vec![1, 2, 3]);
    
    // Create independent LocalReader for each thread
    let readers: Vec<_> = (0..4).map(|_| swap.local()).collect();
    
    let handles: Vec<_> = readers
        .into_iter()
        .enumerate()
        .map(|(i, local)| {
            thread::spawn(move || {
                let guard = local.load();
                println!("Thread {} sees: {:?}", i, *guard);
            })
        })
        .collect();

    // Writer stores a new value
    swap.store(vec![4, 5, 6]);

    for handle in handles {
        handle.join().unwrap();
    }
}

Using Closures

use smr_swap::SmrSwap;

fn main() {
    let mut swap = SmrSwap::new(vec![1, 2, 3]);
    let local = swap.local();

    // Use map to transform value
    let sum: i32 = local.map(|v| v.iter().sum());
    println!("Sum: {}", sum);

    // Use filter to conditionally get guard
    if let Some(guard) = local.filter(|v| v.len() > 2) {
        println!("Vector has more than 2 elements: {:?}", *guard);
    }

    // Use update_and_fetch to update and get new value
    let new_guard = swap.update_and_fetch(|v| {
        let mut new_vec = v.clone();
        new_vec.push(4);
        new_vec
    });
    println!("New value: {:?}", *new_guard);
}

Shared Reader Creation with SmrReader

If you need to distribute the ability to create readers to multiple threads (e.g., in a dynamic thread pool), use SmrReader. Unlike LocalReader, SmrReader is Sync and Clone.

use smr_swap::SmrSwap;
use std::thread;

let mut swap = SmrSwap::new(0);

// Create a shareable SmrReader factory
let reader_factory = swap.reader();

for i in 0..3 {
    // Clone the factory for each thread
    let factory = reader_factory.clone();
    
    thread::spawn(move || {
        // Use factory to create a LocalReader on the thread
        let local = factory.local();
        
        // ... use local reader ...
    });
}

Core Concepts

Type Hierarchy

SmrSwap  ──local()──►  LocalReader  ──load()──►  ReadGuard
 (main)                (per-thread)              (RAII guard)

Why LocalReader?

LocalReader is a thread-local read handle:

• Each thread should create its own LocalReader and reuse it
• LocalReader is Send but not Sync, should not be shared across threads
• Contains thread-local version tracking for safe memory reclamation

API Overview

SmrSwap<T>

Main entry point, holds data and write capability.

LocalReader<T>

Thread-local read handle.

SmrReader<T>

A sharable factory for LocalReader.

ReadGuard<'a, T>

RAII guard, implements Deref<Target = T> and AsRef<T>, protects data from reclamation while guard is alive.

Standard Trait Implementations

Performance

Since smr-swap v0.9.0, the default strategy is Write-Preferred. The previous Read-Preferred strategy is available via the read-preferred feature.

Benchmark results comparing SMR-Swap against arc-swap (Windows, Bench mode, Intel Core i9-13900KS).

Benchmark Summary

Single-Writer Read/Write Ratio (1 Writer + 2 Readers)

Multi-Writer Multi-Reader (SMR-Swap wrapped in Mutex)

Operational Overhead

Analysis

• Write-Preferred (Default):

  • Balanced Performance: Better trade-off between read and write performance.
  • Mechanism: Uses Symmetric Memory Barriers, distributing synchronization overhead across both reads and writes.
  • Fast Multi-Threaded Writes: Significantly faster in mixed read/write and multi-writer scenarios (Avg ~500ns in 4W+4R vs ~2µs in Read-Preferred).
  • Good Read Performance: Read latency (~4.5ns) is higher than Read-Preferred (~0.9ns) but still ~2x faster than ArcSwap (~9.2ns).

• Read-Preferred (Feature):

  • Ultimate Read Performance: Sub-nanosecond read latency (~0.9ns), ideal for read-heavy (>99% reads) workloads.
  • Mechanism: Uses Asymmetric Memory Barriers (Heavy-Write/Light-Read), shifting synchronization overhead almost entirely to the writer.
  • Slower Writes: Write operations are more expensive due to reader checking overhead and heavy barriers.
  • Poor Multi-Writer Scaling: Heavy contention in multi-writer scenarios.

• Comparison:

  • Reads: Read-Preferred > Write-Preferred > ArcSwap > Mutex
  • Writes: Mutex > Write-Preferred > Read-Preferred > ArcSwap
  • Mixed: Write-Preferred > Read-Preferred > ArcSwap

Design

Single-Writer Multiple-Reader Pattern

• SmrSwap<T> holds write capability, not Clone

  • Single writer guaranteed by ownership system
  • Wrap in Mutex<SmrSwap<T>> for multiple writers if needed

• LocalReader<T> is Send but not Sync

  • Contains thread-local version information
  • Each thread should have its own LocalReader

Memory Management

SMR-Swap uses swmr-cell for version-based memory reclamation:

• Old values are automatically queued for reclamation on write
• Memory is reclaimed when no readers reference old values
• Use collect() to manually trigger reclamation

License

This project is 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.