Skip to content
Tutorials Center
My learning

Topics

Lesson 78 of 132 ยท Concurrency

Atomics and Memory Ordering

Learn Rust atomics: AtomicUsize and AtomicBool, fetch_add, compare_exchange, Relaxed, Acquire, Release and SeqCst ordering, a spin lock, Once, OnceLock and LazyLock.

A Mutex is a good tool, but it is heavy for tiny jobs. Counting how many requests were served, setting a "please stop" flag, handing out unique ids: for such single-value tasks, taking a lock, waiting for it and releasing it is a lot of ceremony. Modern processors have special instructions that read-modify-write a single machine word in one indivisible step. Rust exposes them as the atomic types in std::sync::atomic: AtomicBool, AtomicUsize, AtomicI32, AtomicU64 and friends, plus AtomicPtr.

"Atomic" means no other thread can ever see the operation half done. Atomics never block, never poison and cannot deadlock. They also have a sharp edge: every operation takes an Ordering argument that controls how the operation is ordered with respect to other memory. This lesson builds the intuition for Relaxed, Acquire, Release and SeqCst, then uses atomics for counters, flags, a spin lock and one-time initialization with Once, OnceLock and LazyLock.

If you are unsure, use Ordering::SeqCst. It is the strongest, simplest to reason about, and on common hardware the cost over the weaker orderings is small for most programs. Weaker orderings are an optimization you apply only when you can explain exactly why they are correct.

A lock-free counter

An atomic can be shared between threads by reference, because its methods take &self. Combine it with Arc or scoped threads.

Rust AtomicUsize as a shared counter

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

fetch_add adds and returns the previous value, in one indivisible step. The result is always 10,000. A naive let v = hits.load(..); hits.store(v + 1, ..) would lose updates because another thread can slip in between the load and the store; the atomic read-modify-write operations exist to close exactly that gap. The family is: fetch_add, fetch_sub, fetch_and, fetch_or, fetch_xor, fetch_max, fetch_min, swap, and the conditional ones below. Integer atomics wrap on overflow instead of panicking.

Notice that Relaxed is enough here. A pure counter only needs to be correct about itself; nobody uses its value to conclude anything about other data.

Flags with AtomicBool

The most common atomic is a stop flag shared between a worker and its controller.

Rust A stop flag

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

We print only facts that are guaranteed (the exact tick count is not). thread::yield_now() hints to the scheduler that this thread can give up its slice, which matters on our single CPU; real programs would usually sleep or wait on a Condvar instead of spinning.

compare_exchange: conditional updates

compare_exchange(current, new, success_order, failure_order) is the building block of lock-free algorithms. In one atomic step it says: "if the value is currently current, replace it with new and report success; otherwise leave it and tell me what it actually was." It returns Result<previous, actual>: Ok means the swap happened.

Rust compare_exchange claims a slot exactly once

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The usual shape in real code is a retry loop: read the current value, compute the new one from it, try to swap, and if the swap fails because someone else changed the value, loop with the fresh value. try_update is that loop (it was called fetch_update in older Rust versions; the old name is now deprecated and rustc suggests the rename). There is also compare_exchange_weak, which may fail spuriously (a legal behaviour on some CPUs) but can be a little faster inside a loop.

Here is a loop written by hand: a counter that saturates at a limit instead of passing it.

Rust A saturating counter with a CAS loop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Four threads try 400 increments, but the limit is 150, so exactly 150 succeed no matter how the threads interleave. A plain load-check-store would let the counter overshoot.

What Ordering means

Here is the part everyone finds hard, so let us build it from the problem. Compilers and processors reorder memory operations to go faster, as long as a single thread cannot tell. Another thread, however, can see the effects in a surprising order. Consider a producer that prepares data and then raises a flag:

Rust
DATA = 42;           // (1) write the data
READY.store(true);   // (2) tell the consumer

and a consumer that waits for the flag and reads the data:

Rust
while !READY.load() {}
println!("{}", DATA); // must be 42

If the processor were free to perform (2) before (1), the consumer could see READY == true and still read the old DATA. We need a way to say "everything I wrote before this store must be visible to anyone who sees this store". That is exactly what release and acquire do:

Ordering Use it on Meaning
Relaxed any Atomic, but no ordering with other memory.
Release stores All earlier writes become visible to a thread that acquires this value.
Acquire loads Sees everything written before the release that stored this value.
AcqRel read-modify-write Both: acquire the old value, release the new one.
SeqCst any Acquire/release plus a single global order of all SeqCst operations.

Think of release as "publishing" and acquire as "subscribing". A Release store paired with an Acquire load that reads the stored value forms a bridge: whatever happened before the store is guaranteed to be visible after the load.

Rust Release and Acquire publish data

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Because the consumer only exits the loop after an Acquire load saw the Release store, the later load of DATA is guaranteed to return 42. Change both orderings to Relaxed and the program would be allowed to print 0 on weakly ordered hardware (x86 happens to be forgiving, ARM is not). That is the nasty thing about ordering bugs: tests on your laptop pass and phones fail.

SeqCst goes one step further: all SeqCst operations on all variables appear in one single order that every thread agrees on. You need it when several independent atomics must be observed consistently, which is rare. Two more points that professionals remember:

  • A failing compare_exchange is only a load, so its failure ordering can only be Relaxed, Acquire or SeqCst (never Release or AcqRel); since Rust 1.64 it may be stronger than the success ordering.
  • Passing an invalid ordering is a panic at run time, for example load(Ordering::Release). The compiler cannot catch it, because Ordering is an ordinary enum.

Building a spin lock

A spin lock busy-waits instead of sleeping. It is a good exercise in using acquire and release correctly, and a bad idea in most real code (a Mutex is better because it lets waiting threads sleep). Our lock stores false for unlocked and uses a compare-exchange to flip it to true.

Rust A tiny spin lock

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

1000 * (1 + 2 + 3 + 4) is 10,000, and that is what you get on every run. The pattern is the heart of every lock: acquire when taking it, release when giving it back. This version is deliberately small and not production quality: it is not panic safe (if f panics the lock stays locked forever; a real one uses a guard with Drop) and it starves under heavy contention. It uses unsafe because UnsafeCell is the only legal way to mutate through a shared reference; see Unsafe Rust.

ABA, and other traps

  • Atomics only protect one variable. Two separate atomics do not form a consistent pair. If two values must change together, use a Mutex around a struct, or pack both into one AtomicU64.
  • Check-then-act with separate calls is a race. if flag.load() { flag.store(false) } lets two threads both succeed. Use swap(false) or compare_exchange.
  • The ABA problem. A compare-exchange only checks that the value looks the same; if it went A, then B, then A again, your assumption about what happened in between may be wrong. Lock-free data structures solve this with version tags or hazard pointers. Do not write lock-free containers yourself: use a vetted crate.
  • False sharing. Two atomics that sit on the same cache line slow each other down even though they are unrelated. High-performance code pads hot atomics to separate cache lines (the crossbeam_utils::CachePadded type does this).

Prefer, in this order: no sharing, channels, Mutex, then atomics. Reach for atomics when you have a single counter, flag or id generator, or when profiling shows a lock is the bottleneck.

One-time initialization: Once, OnceLock, LazyLock

Atomics are also the machinery behind "initialize this once, the first time it is needed". Rust has three tools.

std::sync::Once runs a closure exactly once across all threads; others calling at the same time wait for it to finish.

OnceLock<T> (stable since Rust 1.70) is a cell that can be set once and then read freely. get_or_init computes the value on first use.

LazyLock<T> (stable since Rust 1.80) is a value initialized by a closure at first dereference, perfect for static data that is expensive or impossible to build in a const.

Rust Once, OnceLock and LazyLock

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

OnceLock::set returns Err(value) when it was already initialized, handing your value back. The LazyLock closure runs on the first access and never again, so "building lookup table" appears once, after "before first use". Older code uses the lazy_static! or once_cell crates for this; since 1.80 the standard library covers the same ground, and LazyLock is the modern way to write a global.

Which tool should I pick?

Need Tool
A counter, an id generator, a stats number Atomic with fetch_add
A stop or "ready" flag AtomicBool
Protect several fields that change together Mutex<Struct>
Many readers, rare writer RwLock
Hand work from one thread to another Channel
Global value initialized once LazyLock or OnceLock

Whatever you pick, Send and Sync explains why the compiler allows these types to cross threads in the first place.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why is counter.store(counter.load(..) + 1, ..) not a safe way to increment a shared atomic?

    Each call is atomic on its own, but the pair is not. fetch_add performs the read and the write as one indivisible step.
  2. 2. What does fetch_add return?

    All the fetch_* operations return the value the atomic held before the operation, which is handy for handing out unique ids.
  3. 3. Which pairing makes data written before a flag visible to a thread that sees the flag?

    A Release store publishes earlier writes, and an Acquire load that reads that value subscribes to them. Relaxed gives no such guarantee on weakly ordered hardware such as ARM.
  4. 4. What does a compare_exchange that returns Err(actual) tell you?

    The swap happens only when the current value equals the expected one. On failure you get the real value back and usually retry in a loop.
  5. 5. Which type runs a closure the first time a static is dereferenced?

    LazyLock (Rust 1.80) initializes on first access. OnceLock is the same idea when you want to supply the value yourself, with get_or_init or set.

Summary

  • Atomic types perform read-modify-write operations on one value indivisibly, without locks, poisoning or deadlocks.
  • Use fetch_add and friends for counters, AtomicBool for flags, and compare_exchange or try_update for conditional updates in retry loops.
  • Relaxed is atomic only; Release stores and Acquire loads publish and subscribe to earlier writes; SeqCst adds one global order. When unsure, use SeqCst.
  • Atomics protect a single variable; check-then-act sequences and multi-field invariants need compare_exchange or a Mutex.
  • A spin lock acquires with Acquire and releases with Release; real code prefers Mutex.
  • Once, OnceLock (1.70) and LazyLock (1.80) give thread-safe one-time initialization for globals.

Next: Send, Sync and Fearless Concurrency