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

Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
smr-swap = "0.8"

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);
}

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.

ReadGuard<'a, T>

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

Standard Trait Implementations

Performance

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)

Analysis

• Excellent Read Performance: Sub-nanosecond latency (~0.9 ns) for both single and multi-thread reads, ~10x faster than ArcSwap
• Linear Scaling: Multi-thread read performance remains nearly constant regardless of thread count
• Stable Mixed Workload: Maintains ~57 ns latency under 1 writer + N readers scenarios
• Optimal for Read-Heavy Workloads: At 100:1 and 10:1 R/W ratios, SMR-Swap dominates, 91-97% faster than Mutex
• Write-Heavy Workloads: At higher write ratios (1:10, 1:100), Mutex has better write efficiency
• Excellent Multi-Writer Performance: Even with Mutex wrapping, SMR-Swap is 70-80% faster than ArcSwap in multi-writer multi-reader scenarios
• Good Under Memory Pressure: Aggressive GC ensures stable performance under memory pressure

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.