Refcount and transitions
This is the deep-dive companion to Shared<T> reference
counting — read that page first for what a
reference count is and how to use Shared<T>. Here we open the
box: what’s actually allocated, how the atomics are ordered, and
how the explicit share / unshare transitions
lower to IR.
Both transitions are fully implemented: share x emits the
shared allocation and copies the owned payload in; unshare s emits the speculative decrement and the
unique-branch recovery.
What this page covers: the 16-byte header’s layout · the memory ordering
of each refcount operation · when the counter is atomic and when it is a plain
load and add · the overflow guard · the exact emission of share and unshare · what is not built.
Header layout
Every Shared<T> allocation is a single contiguous block:
┌──────────────────────────────────────────┬─────────────────────┐
│ 16-byte refcount header │ payload : T │
│ ┌───────────┬───────────┬──────────────┐│ │
│ │ AtomicU32 │ AtomicU32 │ u64 ││ │
│ │ strong │ weak │ payload size ││ │
│ └───────────┴───────────┴──────────────┘│ │
└──────────────────────────────────────────┴─────────────────────┘
^ the shared allocator returns this address
^ the compiler steps past
the header to the payload The payload size slot lets the matching free reconstruct the
exact Layout the system allocator needs — no size threading
required from the call site. The weak count drives the std::sync::Arc / Weak lifecycle: the strong references hold one
implicit weak (so it starts at 1), the payload is dropped at
strong 0, and the block is freed at weak 0.
Atomic ordering
The strong and weak counts are each an AtomicU32. Four billion
references is unreachable before memory runs out, so carrying both still
fits the 16-byte header. Every operation uses an explicit ordering, and
none uses SeqCst.
| Operation | Ordering | Why |
|---|---|---|
| Initial counts, when the allocator returns | A plain write, before the block is published | The block is not yet visible to any other thread, so no ordering is owed. The publishing store carries its own release edge. |
inc (clone) | Relaxed fetch_add(1) | The caller already holds a live strong reference, so the block is valid. The cross-thread happens-before is carried by the Release decrement and the last-drop Acquire fence, the same discipline as Arc::clone. |
dec (drop, count > 1) | Release fetch_sub(1) | Publishes the dropper’s writes; pairs with the last-drop fence so the eventual destructor sees them. |
dec (last drop, count == 1) | Acquire fence after the Release fetch_sub | The destructor about to run must observe every write any prior holder made, even on cores that have not yet seen the decrement. |
The Acquire fence on the last drop is load-bearing: it guarantees
the destructor sees the fields’ final values, not stale cached copies
on another core. Without it, a final write made by a holder on one core
could still be in that core’s store buffer when the destructor on
another core runs — undefined behaviour through stale reads.
Note
The fence is emitted only for a class whose counts are atomic (see the next section). A class that never leaves its thread has no other writer, so there is nothing for the fence to order.
The implementation uses fetch_sub and a branch on the previous
value rather than a compare-and-swap loop. It is cheaper on every
target (one atomic operation against a retry loop), and the rarely
taken last-drop branch is colder than the common count > 1 path.
Atomic only when another thread can reach the object
The ordering table above describes the atomic variant. You do not always pay for it. Atomicity is chosen per class, at compile time, by a thread-locality analysis in sema:
A
Shared<T>class is thread-local unless one of its instances can be reached from another thread. Sema seeds the escaping set from everyspawnsite and everyThreadlaunch (its arguments and the resolved target’s parameters, return and receiver). It also seeds from every body-lessextern "C"signature, because the foreign boundary is a channel the analysis cannot see through. It then closes the set over class field graphs by fixpoint: if a thread-reachable class owns aSharedorWeakfield, that field’s class escapes too.Both seeds are asked of the site, not of a proof that a second thread is really reached: a
spawnwhose task never touches the object from another thread still pays for the atomic counter. Over-approximating is the direction a missing proof must fail in.For a class in the thread-local set,
incanddeclower to a plainload,addandstore, with nolockprefix and noAcquirefence on the last drop. For every other class you get the atomic sequence above.
The decision is keyed on the class (its TypeId), never on a pointer or a
binding. It is therefore sound under aliasing and reassignment: two
handles to the same object always share the class, hence the same
atomicity. The header layout is identical either way (still 16 bytes),
as is the overflow guard and the drop diamond; only the instructions
for the count change.
same program, two classes
class used only on one thread class reachable through spawn
┌──────────────────────────────┐ ┌────────────────────────────────┐
│ inc: load / add / store │ │ inc: lock-prefixed atomic add │
│ dec: load / sub / store │ │ dec: lock-prefixed atomic sub, │
│ no last-drop fence │ │ then Acquire fence on │
└──────────────────────────────┘ │ the last drop │
└────────────────────────────────┘ You can watch the decision in the emitted IR. A Shared<T> graph that
is only used on one thread should show no atomic read-modify-write on
its strong count:
$ axle build shared_local.axle --emit=llvm | grep -c atomicrmw Send the same graph through a spawn and the strong count goes atomic
again: the lock-prefixed atomicrmw and the last-drop fence reappear
at every inc and dec of that class, and of no class the seeds do not
reach. In other words, you pay for atomic reference counting when a spawn target or a foreign boundary can reach the object. The analysis is
asked of the site, so it errs toward paying.
Overflow
The inc path checks the value before the increment and aborts the
process when the 32-bit count is already at its maximum. The alternative,
a silent wrap, would let the next decrement bring a still-live object to
zero and free it. A program with more than 2³² live references to one
object is already broken, so aborting is the safer failure mode. The
check costs one compare and a branch that is never taken in a correct
program.
The weak upgrade path has the same guard: when its strong count would
overflow it aborts the process too. Arc<T> in Rust’s standard library
makes the same trade-off on clone, so the per-clone overhead is identical.
share lowering
class Cache {
hits : i32;
constructor() { self.hits = 0; }
}
fn promote() : Shared<Cache> {
let owned = new Cache(); // uniquely owned
let s : Shared<Cache> = share owned; // owned consumed
return s;
} The emission sequence:
- Call the shared allocator for the size of
Cache. This gives a fresh refcount header (count = 1) and an uninitialised payload. - Copy the owned payload into the new payload slot, bit for bit.
- Release the original owned cell.
- Return the
Shared<Cache>pointer.
The source binding is consumed at compile time (own semantics), so no
scope-exit cleanup runs on it later. The class identity is preserved
exactly; no constructor is re-invoked.
unshare lowering
class Cache {
pub hits : i32;
constructor() { self.hits = 0; }
}
fn recover(s : Shared<Cache>) : i32 {
let owned = unshare s; // unique value, or null
if (owned == null) {
return -1;
}
return owned.hits;
} The emission speculatively decrements the refcount and branches on the value before the decrement:
- Count was 1 (last reference). The decrement reaches zero. Emit a
fresh owned allocation, copy the payload into it, release the shared
cell, and return the owned pointer. For a class that is atomic, an
Acquirefence is taken before the copy, so the copy sees every write a prior holder made. - Count was greater than 1. Return
null. There is no restore-increment:unshareconsumessuniformly, so on the contended outcome your reference is genuinely released. The surviving holders keep the object alive and free it at their own scope exits.
The nullable result lowers to a plain pointer (null means no value), so
the two branches merge in a single phi. The value recovered on the
unique branch is an ordinary owned heap object: its scope-exit cleanup
frees it exactly once, unless you move it on (return it, store it,
re-share it).
Limitations
| Limit | Why it holds |
|---|---|
| The counter is 32 bits per direction | a program with more than 2³² live references to one object is already broken; the inc path aborts rather than wrapping |
| There is no cycle collector | the counts are the only reachability information the runtime keeps |
| Thread-locality is per class, not per value | two handles to one object always share the class, hence the same atomicity |
| Both transitions consume their source | share x consumes the owned value; unshare s consumes the handle on either outcome |
| The class identity is copied exactly, not reconstructed | no constructor runs during either transition |
Limits / Uncabled
| Feature | State | Detail or workaround |
|---|---|---|
unshare of a shared array | Refused with E0766. | Keep the array in its shared handle; share a class that holds the array instead. |
| Thread-locality through a global variable | The analysis reads signatures and field graphs, not globals. A class reachable from two threads only through a global is not seen as escaping. | Do not publish a Shared<T> handle through a global variable that another thread reads. Pass it through spawn or a Thread argument instead. |
See also
Shared<T>reference counting — user-facing API and lifecycle.- Memory model — when the compiler picks shared vs heap vs arena.
- Escape analysis and promotion — the other deep-dive page in this section.
- Compiler internals overview — index of all internals pages.
- Concept index — every shared-memory concept on one page.