Axle v0.22.0

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.

OperationOrderingWhy
Initial counts, when the allocator returnsA plain write, before the block is publishedThe 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_subThe 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 every spawn site and every Thread launch (its arguments and the resolved target’s parameters, return and receiver). It also seeds from every body-less extern "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 a Shared or Weak field, 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 spawn whose 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, inc and dec lower to a plain load, add and store, with no lock prefix and no Acquire fence 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:

  1. Call the shared allocator for the size of Cache. This gives a fresh refcount header (count = 1) and an uninitialised payload.
  2. Copy the owned payload into the new payload slot, bit for bit.
  3. Release the original owned cell.
  4. 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 Acquire fence 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: unshare consumes s uniformly, 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

LimitWhy it holds
The counter is 32 bits per directiona program with more than 2³² live references to one object is already broken; the inc path aborts rather than wrapping
There is no cycle collectorthe counts are the only reachability information the runtime keeps
Thread-locality is per class, not per valuetwo handles to one object always share the class, hence the same atomicity
Both transitions consume their sourceshare x consumes the owned value; unshare s consumes the handle on either outcome
The class identity is copied exactly, not reconstructedno constructor runs during either transition

Limits / Uncabled

FeatureStateDetail or workaround
unshare of a shared arrayRefused with E0766.Keep the array in its shared handle; share a class that holds the array instead.
Thread-locality through a global variableThe 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

memoryrefcountsharedatomics