arc-swap for Atomic Arc Replacement in Rust

Why arc-swap Exists for Read-Mostly Shared State

arc-swap addresses a gap between ordinary `Arc<T>` and synchronization primitives such as `RwLock<Arc<T>>`. An `Arc<T>` can share ownership safely, but assigning a new value through a shared reference requires additional synchronization. `RwLock<Arc<T>>` supplies that synchronization, while the README describes arc-swap as the sort of facility that `Atomic<Arc<T>>` would provide if the standard library exposed one. The intended workload is explicit: reads are frequent and replacements are rare.

That distinction matters when many threads need access to the same current value. A configuration value, parser, or service object can be held behind `Arc<T>` and replaced when the application receives new state. Arc-swap focuses on making that replacement atomic without requiring readers to lock an `RwLock`. The README claims consistent performance characteristics and says the implementation is optimized for this access pattern, but it does not publish benchmark figures. Its `benches/` directory and several Criterion benchmark definitions indicate performance testing, yet repository layout alone does not establish results for any particular machine or workload.

Arc-swap is therefore aimed at programmers who already understand `Arc`, reference counting, thread safety, and Rust's ownership rules. It is not a general-purpose configuration manager or cache. The application still decides when a value should change, how long an acquired `Arc` remains useful, and what consistency policy applies after a replacement.

ArcSwap, AtomicPtr, and the Replacement Model

The project presents itself as atomic, swappable `Arc` storage. Its primary type is named `ArcSwap`, and the repository describes the package as “Atomically swappable Arc.” The README also links Rust's `AtomicPtr`, which points to an implementation based on atomic pointer operations rather than a lock-protected accessor. Based on the available documentation, the essential data flow is to keep a current `Arc<T>` in shared atomic storage, let readers obtain that value, and replace it with another value as one operation.

This approach separates the lifetime of a value from the decision to stop using it as the current value. A reader can hold an `Arc<T>` while another thread publishes a replacement. The crate's role is to coordinate the pointer and reference-counted ownership correctly; it does not mutate the internal state of `T` in place. That makes the abstraction most useful when each publication represents a complete value rather than a partial update.

The README is notably thin on operational guarantees. It does not explain ordering, memory visibility, the comparison and swap sequence, panic behavior, or the exact return types of the public API. Those are central adoption questions for a concurrency primitive. The Rust documentation at `https://docs.rs/arc-swap` is explicitly the recommended pre-use reference, so this repository overview cannot substitute for its API and ordering documentation.

Adding arc-swap to a Rust Package

The repository does not provide a README installation command. It identifies the crate as `arc-swap`, documents its published API through `https://docs.rs/arc-swap`, and contains a Cargo package manifest. Based on `Cargo.toml`, the package uses version `1.9.2`, Rust edition 2018, and the MIT OR Apache-2.0 license.

A first dependency declaration can be based directly on the repository manifest. Add the package entry to the `[dependencies]` section of the consuming crate's `Cargo.toml`:

[dependencies]
arc-swap = "1.9.2"

This is the manifest's exact package name and version, but the README does not give a command that adds it automatically. After adding the dependency, consult the versioned documentation linked by the repository rather than assuming an API shape. The manifest enables additional capabilities through features, and the exact Cargo feature-selection syntax is not shown in the README.

A useful first review should locate `ArcSwap`, determine how a value is stored and loaded, and identify the lifetime of an `Arc<T>` returned to a reader. It should also locate the comparison and replacement operation and inspect its ordering semantics. The README supports these lookup directions, but it does not contain a runnable first-use example.

Compiler Policy, Optional Features, and Upgrade Boundaries

The stated 1.x Rust policy is broader than the repository's own development setup. The README says version 1 will build on any edition 2018 capable compiler, while tests build and run on recent compilers, mostly because of dependencies. This creates an important distinction: compatibility with an older edition 2018 compiler does not mean the test suite, every dependency, or every optional configuration will compile there.

Optional features are also governed by the project policy. The README says most feature flags are guaranteed to build from the version that introduces them. Experimental features do not carry that guarantee. The manifest currently lists `weak`, `internal-test-strategies`, `experimental-strategies`, and `experimental-thread-local`. It explicitly warns that `internal-test-strategies` is not for application use, has no stability guarantee, and may perform badly. The `experimental-strategies` feature is currently empty and explicitly carries no stability guarantees. `experimental-thread-local` depends on nightly `thread_local` functionality for `no_std` builds and also has no stability guarantee.

The repository's last push was on 2026-06-28, which supports treating current work as recent, although `Cargo.toml` also contains a maintenance badge marked `actively-developed`. There are no GitHub releases, so `CHANGELOG.md`, dependency changes, and the commit history matter more than GitHub release notes for upgrade review. Consumers using optional features should read the relevant `CHANGELOG.md` entries rather than assuming every 1.x build has the same feature compatibility.

Where RwLock or OnceCell Is the Better Choice

`RwLock<Arc<T>>` is the clearest real alternative because the README explicitly compares it with arc-swap. Both approaches coordinate shared access to an `Arc<T>`, but they use different mechanisms. `RwLock` exposes standard locking semantics, while arc-swap is intended to avoid taking that read lock for its preferred read-mostly access pattern. An application that needs the established behavior and API of `RwLock`, or one whose access pattern is not predominantly reads, may have little reason to change.

For a value initialized only once, standard initialization facilities may also be more natural, although the README does not document `OnceCell` behavior and does not position it as an arc-swap replacement. The safe conclusion is narrower: arc-swap targets replacement, not every form of deferred initialization. The README does not explain deferred initialization APIs, capacity limits, eviction, or persistence.

Arc-swap is also the wrong abstraction when writers are common. Its stated optimization is for “read-mostly write-seldom” workloads, so placing it in a write-heavy design would discard the premise behind the library. Likewise, an application that needs the experimental thread-local path should first establish that the nightly dependency and absent stability guarantee fit its build policy.

Documentation Gaps That Block a Final API Decision

The repository provides a short project summary, compiler policy, license files, a changelog, tests, and benchmark source, but the README does not show how to construct an `ArcSwap`, load a value, replace a value, or use the `weak` feature. It also does not document failure behavior or explain whether operations can return errors. Without those details, a production adoption should not be based on the package description alone.

Performance is another unresolved point. The README asserts optimization for read-mostly workloads and consistent characteristics, while `Cargo.toml` defines benchmarks named `background`, `int-access`, and `track`. Those names show areas considered by the project, but neither the README nor the repository files include benchmark results. Claims about latency, throughput, contention, memory use, or superiority to `RwLock<Arc<T>>` would therefore exceed the documented evidence.

The license presents a practical choice rather than a constraint: users may select MIT or Apache-2.0. Contribution terms also use the dual-license model unless a contribution states otherwise. That is license information, not legal advice. For source-level or release-specific obligations, the repository's `LICENSE-MIT` and `LICENSE-APACHE` files remain the controlling documents.

Editorial conclusion

Rust developers should consider arc-swap when concurrent readers need a shared `Arc<T>` that is replaced occasionally without placing a lock around every read. It is a poor fit for workloads with frequent writes, experimental strategy requirements, or compatibility constraints that include tests or optional features. Before adoption, verify the exact API at `https://docs.rs/arc-swap`, confirm that the selected feature guarantees apply to your toolchain, and inspect the change from `RwLock<Arc<T>>` in a representative design. On the evidence available here, its focused data structure and broad 1.x compiler policy make it a reasonable fit for the stated read-mostly case, not a general replacement for every atomic container.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. vorner/arc-swap on GitHub