ArcSwap

arc-swap provides ArcSwap, a container that makes an Arc<T> itself atomically swappable — semantically similar to Atomic<Arc<T>> or RwLock<Arc<T>> but without needing a lock, and optimized for read-mostly, write-seldom workloads with consistent, predictable performance under contention.

It targets scenarios like live configuration reloads, routing-table updates, and periodic data-structure snapshots, where many threads need to read a shared value frequently and concurrently while updates happen rarely, and where a naive RwLock<Arc<T>> suffers from lock and reference-count contention.

What You Get

• ArcSwap<T> — lock-free atomic container for swapping an Arc<T> across threads
• ArcSwapOption/ArcSwapWeak variants for optional and weak-reference use cases (behind the weak feature)
• A Cache type for amortizing the cost of repeated loads on a single thread
• Optional serde (de)serialization support behind a feature flag
• no_std support via an experimental thread-local feature flag for constrained environments
• Configurable internal strategies exposed for advanced/experimental tuning (not part of the stable API surface)

Common Use Cases

• Hot-reloading application configuration without pausing request processing on every read
• Sharing an up-to-date routing table or feature-flag snapshot across many worker threads with minimal read overhead
• Replacing RwLock<Arc<T>> in read-heavy, low-write concurrent data structures to reduce lock contention
• Building lock-free caches or snapshot-style shared state where readers must never block on a writer

Under The Hood

Architecture — The crate’s public surface centers on ArcSwap defined in src/lib.rs, backed by pluggable internal strategy implementations (src/strategy/) that implement the actual atomic-swap algorithm, a debt module implementing a hazard-pointer-like reference-counting scheme to safely reclaim old Arc allocations without blocking readers, and access.rs/cache.rs providing higher-level access patterns (like the Cache type for per-thread load amortization). ref_cnt.rs and as_raw.rs abstract over reference-counted types so the same machinery can support Arc, Rc-like, and weak-reference variants.

Tech Stack — Pure Rust, edition 2018, with rustversion as its only mandatory dependency (used to gate version-specific code paths) and serde as an optional feature. Dev-dependencies include criterion for benchmarking (three benchmark suites: background, int-access, track), proptest for property-based testing, and loom-adjacent concurrency testing tools like crossbeam-utils and adaptive-barrier to validate lock-free correctness under concurrent execution.

Code Quality — The crate carries #![warn(missing_docs)] and denies warnings in doctests (#![doc(test(attr(deny(warnings))))]), and includes compile_fail_tests.rs to assert that certain misuse patterns fail to compile. With Codecov integration, a dedicated docs/ folder of internal design documentation, and proptest-based property tests alongside criterion benchmarks, the project treats correctness of its lock-free algorithm as the primary quality bar — appropriate given the subtlety of writing sound concurrent/atomic code.

API Design — The type mirrors familiar Arc/RwLock ergonomics (ArcSwap::from_pointee, .load(), .store()) so Rust developers already familiar with Arc and locking primitives can adopt it with minimal new concepts, while advanced users can reach for Cache or the access module for further tuning. Experimental strategies and thread-local no_std support are explicitly marked without stability guarantees, keeping the stable API small and well-scoped.