Axle v0.22.0

Shared<T> reference counting

Shared<T> is Axle’s refcounted-pointer type. Use it when a single object needs more than one live owner — a long-lived collection, a cache reachable from a spawn target, a graph node referenced by multiple parents, anything where the escape-analysis tiers (stack / arena / heap-owned) don’t fit.

It’s the only memory model in Axle that costs you an explicit keyword. The compiler never turns an ordinary object into a counted one: you write Shared<T> or share new T(...) where you want a refcounted value. Once a value is Shared<T>, the compiler inserts the increments and decrements that its bindings and scopes require, as described below.

What this page covers: what a reference count is and why Shared<T> is a type rather than a prefix · allocating, using and returning one · sharing an array and storing one in a field · passing one to a task and what stays non-atomic · destructors, the owned ↔ shared transitions · cycles and Weak<T>.


TL;DR

class Cell {
    pub n : i32;
    constructor(v : i32) {
        self.n = v;
    }
}

fn main() : i32 {
    let p = share new Cell(42);    // refcount = 1
    println(p.n);
    return 0;
}                                    // scope exit → refcount = 0
                                     // → destructor (if any) → free

Three things to remember:

  1. Allocate with share new T(...).
  2. Annotate with Shared<T> when the type isn’t inferred (fields, return types, generic args).
  3. Drop is automatic — the compiler inserts the decrement at every scope exit; the runtime frees on the last drop.

(The pub on every field below is what makes Cell’s state readable from main. An unmarked class field belongs to the declaring class alone, so the examples say what they mean — see Visibility and member modifiers.)


What is a reference count?

The other three tiers each have exactly one owner, so the compiler always knows the single moment to free. But sometimes a value has several owners with no single “last” one decided at compile time — a cache a spawned task and its spawner both hold, a graph node two parents point at. Who frees it, and when?

Reference counting answers that at runtime with a small integer stored alongside the object: how many owners are alive right now. Every new owner adds 1 (inc); every owner that goes away subtracts 1 (dec); when the count hits 0, nobody is left and the object is freed — immediately, deterministically, no scan, no pause.

   share new Cell(42)        let q = p          scope end of q        scope end of p
        count = 1        ──►   count = 2    ──►    count = 1     ──►    count = 0
   ┌───────┬───────┐     inc  ┌───────┬───────┐   dec ┌────┬────┐  dec  ┌──────────┐
   │ rc=1  │  42   │          │ rc=2  │  42   │       │rc=1│ 42 │       │  FREED   │
   └───────┴───────┘          └───────┴───────┘       └────┴────┘       └──────────┘
        p ────────────────────► p, q ──────────►      p ─────────►      (destructor
                                                                          runs here)

The count is what makes multi-owner cleanup deterministic without a garbage collector: the free happens the instant the last owner drops, at a point in the code you can predict. The cost is that every inc and dec is a real operation — and because two owners can be reached from different threads, the count must be atomic wherever the compiler cannot rule that out, which is why Shared<T> is the one tier you opt into by hand.

Axle inserts every inc and dec for you: an inc at each new binding that aliases the handle, a dec at each scope exit. You never write the arithmetic — you just decide, by reaching for Shared<T>, that this value has more than one owner.

One alias costs nothing. A binding that aliases a Shared<T> declared earlier, is never re-pointed, and is read exactly once through a field — the signature of the throwaway name (let alias = cur; … alias.value) — holds no share of its own. The source already keeps the object alive for as long as the alias can reach it, so the compiler drops both halves of the pair and the alias compiles to a plain read. Anything that hands the share on — a second read, a pass to a function, a return, re-pointing either name — keeps the full pair, which is what makes the elision safe rather than merely likely.


Why Shared<T> is a type and not a prefix

The other ownership keywords — mut, own, the default borrow — are prefixes on parameter names. They share the same machine representation (one pointer per parameter); only the calling convention contract differs.

Shared<T> is fundamentally different. The runtime allocates a 16-byte header in front of every shared object:

[ AtomicU32 strong | AtomicU32 weak | u64 size ] [ user payload, 16-B aligned ]
                                                 ^
                                                 you receive this pointer

That header is real memory. The strong count is incremented every time a new owner takes a reference and decremented every time one drops out of scope — atomically when the class can reach another thread; when it hits zero the runtime runs the destructor (if the class declared one) and drops the payload. The weak count follows the std::sync::Arc / Weak model: the strong references collectively hold one implicit weak, so the backing block itself is freed only once the weak count reaches zero — which, with no Weak<T> alive, happens at the same moment as the last strong drop.

Because Shared<T> has a representation that’s distinct from plain T, it’s spelled as a real type — capital S, generic brackets — not a keyword qualifier. You’d write ArrayList<Shared<T>> the same way you’d write ArrayList<Future<T>>: a wrapper that changes both the storage shape and the lifecycle.


Allocating a Shared<T>

The constructor sugar share new T(args) produces a fresh shared allocation with refcount = 1:

let cache = share new Cache();              // type inferred: Shared<Cache>
let p : Shared<Cell> = share new Cell(42);  // type written explicitly

You can drop the annotation when the right-hand side is itself a share new — the type is inferred from the allocation. You must write the annotation when:

  • the binding gets its value from somewhere other than a new expression (a function return, a field load, a method call);
  • the binding is a field, parameter, or return type, where Axle has no inference at the declaration site.

Always construct a shared value with share new (or share x on an owned value) — never a plain new. A Shared<T> object carries a 16-byte refcount header (see below); the share new allocator is what reserves it. A plain new T(...) allocates without that header, so a handle built from it would run its refcount ops over memory that was never set aside for them. The compiler rejects the mismatch: binding or returning a plain new T(...) where a Shared<T> is expected is a compile error (E0034), whose hint tells you to allocate it share new T(...) — or to share an already-built object with share x. The word share appears at every construction site.


Using a Shared<T>: fields and methods

A Shared<T> is a refcounted handle in front of the payload, and the handle is the payload’s address — the count sits just before the object. So the object is used through the handle exactly as it is used directly:

  • its fields read and write on the handle — cache.hits, cache.hits = 1;
  • its methods are called on the handle — cache.record(). A self or mut self method borrows the object for the call while the handle keeps it alive.
class Cache {
    hits : i32;
    constructor() { self.hits = 0; }

    pub fn record(mut self) : void { self.hits = self.hits + 1; }
    pub fn count(self) : i32 { return self.hits; }
}

fn main() : i32 {
    let c = share new Cache();
    c.record();                   // a `mut self` method, through the handle
    return c.count() - 1;         // → 0
}

The one method a handle cannot call is an own self one: it would take the object away from every other handle still holding it (E0504). Declare it self or mut self, or call it on an owned object.

A mutation through a handle is an ordinary memory access — see the warning in Passing Shared<T> to a task before two tasks write through handles to one object.

Sharing an array

An array is shared by allocating it in the shared tier:

let s : Shared<i32[]> = share new i32[4096];
s[0] = 7;                       // read and write through the handle
let n : i64 = s.length;

s[i], s[i] = v and s.length work on the handle exactly as on the array, and the handle is passed, stored and released like any other Shared<T>: the last owner frees the buffer. Two rules follow from the buffer being shared from its allocation on (E0766 otherwise):

  • the allocation is written inside the call — share new T[n], not share a for an array allocated earlier, which belongs to a tier with its own release;
  • the elements own nothing — numbers, bool, char, or a struct of those. The last owner frees the buffer and nothing inside it; to share strings or objects, share a class holding the array. Nor may they hold a SIMD vector wider than 16 bytes: the elements sit at a 16-byte alignment.

A shared array is not an array: pass s where a T[] is expected and it is a type error. Index it, or read its length, through the handle.

Storing Shared<T> in fields

Shared<T> composes with the regular type system. The canonical use case is one object with several long-lived owners:

class Cache {
    pub hits : i32;
    constructor() {
        self.hits = 0;
    }
}

class Service {
    pub cache : Shared<Cache>;

    constructor(own c : Shared<Cache>) {
        self.cache = c;
    }

    pub fn hit(self) : i32 {
        return self.cache.hits;
    }
}

fn main() : i32 {
    let c = share new Cache();
    let s1 = new Service(c);
    let s2 = new Service(c);
    return s1.hit() + s2.hit();
}

A field store takes one reference of its own, and so does a return: a Shared<T> parameter — borrowed or own — may be stored into a field or handed back, and either way the count goes up by one, so the caller’s handle and the stored or returned one are released separately. own on a Shared<T> hands the callee one more reference, not the object: the caller’s handle stays live, which is why c is handed to both services above. The same holds for a Shared<T> field of self handed on (new Service(self.cache)). Each Service holds its own count on the cache; destroying a Service releases its reference, and the last drop frees the Cache.


Passing Shared<T> to a task

The refcount survives being shared: handing a Shared<T> to a spawn — or to the target of a Thread::run — is one of the two seeds that take its class out of the thread-local set, so the compiler counts it with atomic operations here — incrementing and decrementing the strong/weak counts cannot corrupt the counter or cause a double-free, no matter which owner ends up dropping last; the destructor still runs exactly once. (A Shared<T> whose class never leaves its thread uses non-atomic counts instead — see Refcount and transitions.)

This does not make the payload thread-safe. The atomicity covers only the 16-byte header (strong/weak/size) — reading or writing the object’s own fields (cache.hits, and any other field) is an ordinary, unsynchronized memory access. An atomic counter says nothing about the object it counts. Two owners that mutate the same field need a lock of their own: a spawn files its task on another carrier of the pool, a second OS thread, so the task and the frame that spawned it race a field outright, while two tasks of one carrier lose an update across a suspension point instead. An owner on a thread of its own — the target of a Thread::run, an FFI callback — races it too. The compiler detects neither, and nothing on the spawn path inserts that lock: record_hit above is safe while a single owner is live, and needs one the moment a second can run against it.

Read-only sharing — every participant only reads a field, as in the lookup example below — is fine as-is. The moment any participant writes a field, guard the access explicitly with synchronized over a lock object of your choosing; synchronized is a plain user-supplied lock, never injected automatically:

class Cache {
    pub hits : i32;
    constructor() { self.hits = 0; }
}

class Guard {
    pub tag : i32;
    constructor() { self.tag = 0; }
}

fn record_hit_locked(c : Shared<Cache>, lock : Shared<Guard>) : void {
    synchronized (lock) {
        c.hits = c.hits + 1;
    }
}
class Cache {
    pub hits : i32;
    constructor() { self.hits = 0; }
}

// Read-only sharing: every participant only reads `cache.hits`, so no
// synchronization is needed beyond the atomic refcount.
fn lookup(cache : Shared<Cache>, key : i32) : i32 {
    return cache.hits + key;
}

fn worker(cache : Shared<Cache>, key : i32) : i32 {
    return lookup(cache, key);
}

fn main() : i32 {
    let cache = share new Cache();
    let h : Future<i32> = spawn worker(cache, 0);   // one live ref crosses to the task
    let mine = lookup(cache, 0);                   // main holds another live ref
    let got = await h;
    return got + mine;
}                            // main and worker both released
                             // → refcount drops to 0 → free

This is the one tier a spawn target may hold on to. Arena allocations belong to the execution context that made them (a value allocated in one context’s arena cannot be referenced from another — neither from another thread nor from a sibling task on the same thread); heap-owned has no synchronization on the drop side. If you need to share, use Shared<T>.


Returning a Shared<T> (transfer of ownership)

A function that returns a Shared<T> hands its refcount to the caller. The compiler does not dec the local at function exit when the return value is exactly that binding — the caller inherits the existing count.

class Cache {
    pub hits : i32;
    constructor() { self.hits = 0; }
}

fn build_cache() : Shared<Cache> {
    let mut c = share new Cache(); // refcount = 1
    c.hits = 1;                     // populate its fields directly
    return c;                       // count NOT dec'd here —
                                    // ownership transferred
}

fn report(c : Shared<Cache>) : void {
    println(c.hits);
}

fn main() : i32 {
    let cache = build_cache();      // still refcount = 1
    report(cache);
    return 0;
}                                    // dec → 0 → drop

If you instead return c.field or any derived expression, the binding the field belongs to stays alive until after the read — the compiler proves the dec doesn’t fire before the value is materialised.


Destructors

When the refcount reaches zero, the runtime invokes the class destructor (if the class has one) before freeing. The destructor runs exactly once.

Destructors are synthesised by the compiler: a class that owns heap fields — a dynamic array T[], an owned object field, a Shared<U> handle — gets a destructor that releases each owned field. You never write the cleanup, and you cannot forget it:

class Holder {
    pub data : i32[],                   // owned heap buffer

    constructor(n : i32) {
        self.data = new i32[n];
    }
}

fn main() : i32 {
    let mut h = share new Holder(64);
    h.data[0] = 7;
    return h.data[0] - 7;
}                                        // last drop → the synthesised
                                         // destructor frees h.data,
                                         // then the Holder itself

Writing a destructor body of your own uses the reserved drop() member (no parameters); it runs first, then the compiler appends the cleanup it can prove — owned fields, refcounted handles. A class with no drop() relies entirely on that synthesised cleanup. For external resources (files, sockets), put the release in drop() or pair the object with a defer … close().


The ownership verbs

Four words move a value between owned, shared and weak. Each is a prefix, like drop and return: no parentheses, and nothing hidden behind a method name. (Two more prefixes, copy and own, say what happens to a struct that changes hands: see Structs: copy and own.)

WriteMeaningConsumes its operand?Result
share xan owned value becomes sharedyes, xShared<T>
share new C(…)allocate the shared block directly: one allocation, no copy—Shared<C>
unshare stake sole ownership backyes, s, even when it failsT \| null
downgrade sobserve the object without keeping it alivenoWeak<T>
upgrade wget a strong handle if the object still livesnoShared<T> \| null
let owned = new Cache();
let s = share owned;             // owned is consumed; s counts 1
let w = downgrade s;             // a weak view; s is still live
let again = upgrade w;           // Shared<Cache> while s lives, null after

let unique = unshare s;          // Cache if no one else holds it, else null

A word is a verb only where an operand follows it. upgrade(x) is still a call, let share = 3; still declares a variable, and node.upgrade() is still a method.

Strong or weak? It is a property of the reference, not of the object. A strong reference (Shared<T>) says “I own this: keep it alive”. A weak one (Weak<T>) says “I can look at it if it still exists”. Ask of each reference: if everyone else forgot this object, would I want it to survive? Yes means strong; no means weak. In practice the references that go up (a child to its parent, an observer to its subject, a cache to its source) are weak, and the ones that go down (a parent to its children) are strong. The strong references must never form a loop.


Owned ↔ Shared transitions

You can promote a uniquely-owned value into a Shared<T> and — when you hold the last reference — try to recover unique ownership back.

class Cache {
    pub hits : i32;
    constructor() {
        self.hits = 0;
    }
}

fn promote() : Shared<Cache> {
    let owned = new Cache();             // uniquely owned (heap)
    return share owned;           // → Shared<Cache>, refcount = 1
}

fn main() : i32 {
    let s = promote();
    let unique = unshare s;   // sole owner → value, else null
    if (unique != null) {
        return unique.hits;              // unique ownership recovered
    }
    return 1;
}
  • share x takes a uniquely-owned value and always succeeds. The source binding is consumed — reading it after the share is a compile-time error (E0501).
  • unshare s returns the unique value if you held the sole strong reference, null otherwise — and consumes s either way: the call releases your reference, and reading s afterwards is a compile-time error (E0501). On the null outcome the surviving holders keep the object alive and free it at their own scope exits. The strong-count check is atomic, so the outcome is correct under concurrency.

Both transitions preserve the object’s identity bit-for-bit — no constructor re-runs, no fields are reinitialised. They are metadata moves, not deep copies.

Both transitions are fully implemented — the recovery’s scope-exit cleanup frees the recovered value exactly once, with no double-free. See Refcount and transitions for the header copy and atomic ordering.


Lifecycle patterns

The everyday single-owner-plus-aliases patterns work: allocate, alias, pass around, transfer through a return, and let the scope-exit decrements free the object exactly once.

Single-binding lifecycle

class Cell {
    pub n : i32;
    constructor(v : i32) {
        self.n = v;
    }
}

fn main() : i32 {
    {
        let c = share new Cell(42);
        println(c.n);
    }                              // dec → free
    {
        let c : Shared<Cell> = share new Cell(7);
        println(c.n);
    }                              // dec → free
    return 0;
}

Allocation, scope-exit drop, destructor + free — the whole pipeline fires correctly.

Transfer through return

class Cell {
    pub n : i32;
    constructor(v : i32) {
        self.n = v;
    }
}

fn make() : Shared<Cell> {
    return share new Cell(42);    // refcount stays at 1
}

fn main() : i32 {
    let c = make();                // caller inherits the count
    return c.n - 42;
}                                   // dec → free

Aliasing

class Cell {
    pub n : i32;
    constructor(v : i32) {
        self.n = v;
    }
}

fn main() : i32 {
    let p = share new Cell(42);
    let q = p;                     // alias — refcount rises to 2
    let total : i32 = p.n + q.n;   // both reads see 42

    {
        let e = p;                 // third alias — refcount 3
        println(e.n);
    }                              // inner dec → back to 2

    println(p.n + q.n);
    return total - 84;
}                                   // two decs → 0 → free, exactly once

A second binding to a Shared<T> bumps the refcount; each binding’s scope-exit decrement brings it back down, and only the last drop frees the object. Aliasing within a scope, passing the handle as a parameter, and rebinding in a loop all keep the count balanced.


Cycles, and Weak<T>

A reference cycle is two (or more) objects that each hold a strong reference to the other:

   ┌─────────┐   next (strong)   ┌─────────┐
   │  Node a │ ────────────────► │  Node b │
   │ strong=1│ ◄──────────────── │ strong=1│
   └─────────┘   back  (strong)  └─────────┘

Neither strong count can ever reach 0: a keeps b alive and b keeps a alive, even after every outside owner drops. So a pure-strong cycle leaks its backing storage. Axle does not detect cycles automatically — strong refcounting fundamentally cannot.

The fix is a Weak<T> reference: a non-owning observer that does not keep the payload alive. Make one edge of the cycle weak, and the count on that side stops propping the object up, so the strong owners can reach 0 and free it. You mint a weak reference from a strong one and recover a usable handle when the payload is still alive:

  • downgrade s → a Weak<T>. Non-owning; it bumps only the weak count, never the strong count.
  • upgrade w → Shared<T> | null. Returns a fresh strong reference if the payload is still alive, or null once the last strong owner has dropped it.
class Cell {
    pub n : i32;
    constructor(v : i32) {
        self.n = v;
    }
}

fn main() : i32 {
    let a = share new Cell(42);
    let w = downgrade a;      // Weak<Cell> — does not keep a alive
    let p = upgrade w;          // Shared<Cell> | null
    if (p != null) {                   // a still alive → non-null
        return p.n - 42;               // → 0
    }
    return 1;
}

The weak count keeps only the 16-byte header block alive — so an upgrade can safely observe “gone” and return null — while the payload itself is reclaimed the moment the strong owners drop.

Breaking a real cycle means storing the weak edge as a field (parent : Weak<Node>), and building the cycle in the first place means a nullable strong link (next : Shared<Node> | null). Both shapes are first-class: a Weak<T> field, parameter, or return type, and a Shared<T> | null / Weak<T> | null field, all name the same handle the allocator and downgrade produce.

Store the weak edge in a field and recover a strong handle on demand — the weak slot does not keep the payload alive:

class Cell {
    pub n : i64;
    constructor(v : i64) { self.n = v; }
}

// A back-reference that does NOT keep the Cell alive.
class Observer {
    pub watch : Weak<Cell>;
    constructor(c : Shared<Cell>) {
        self.watch = downgrade c;   // store a weak edge in a field
    }
    pub fn read(self) : i64 {
        let c = upgrade self.watch;   // recover a strong handle if alive
        if (c != null) { return c.n; }
        return -1;                            // Cell already freed
    }
}

fn main() : i32 {
    let cell = share new Cell(42);
    let obs = new Observer(cell);
    return obs.read();                        // → 42, cell still alive
}

The forward strong link is a nullable Shared<T> field, which accepts a share new value or null:

class Node {
    pub v : i64;
    pub next : Shared<Node> | null;
    constructor(val : i64) {
        self.v = val;
        self.next = null;
    }
}

fn main() : i32 {
    let a = share new Node(7);
    let mut head = new Node(1);
    head.next = a;                 // nullable strong link accepts a Shared<Node>
    let n = head.next;
    if (n != null) { return n.v; } // → 7
    return 0;
}

Model a cyclic or parent/child graph with a nullable Shared<T> field on the owning edge and a Weak<T> field on the back-edge, so the strong counts can still reach zero and free the graph.


Performance notes

  • The count goes atomic only when another thread can reach the object. When the compiler proves a Shared<T> class is thread-local, inc/dec are a plain load/add/store. When an instance can reach another thread — through spawn or an FFI boundary — every inc/dec becomes a lock-prefixed atomic, and the cache line holding the count is invalidated across cores. This is decided per class, automatically; see Refcount and transitions. Even the plain form is a read-modify-write per touch, so for a single-owner value that never needs sharing the default tiers are still leaner.
  • Header overhead is 16 B per object. For very small payloads (a few bytes) that’s a real overhead ratio. Bundle small objects into a single shared container instead of refcounting each one.
  • The destructor + free path is branch-predicted false on every dec except the last. The drop block only enters when the runtime’s i32 return signals “you just hit zero”, so in steady state you pay one cmp + one branch in addition to the atomic op.

If you find yourself reaching for Shared<T> to avoid thinking about ownership, stop and check: does the value actually outlive its caller? Does it really need to be reachable from a spawn target or across an FFI boundary? If not, the default escape analysis is faster and just as correct.


Limitations

LimitWhy it holds
Atomicity covers the handle, not the payloadtwo threads may reach the same object through it, but a plain field write through two aliases is still a data race
A class that no spawn or FFI boundary can reach pays no atomicthread-locality is elected per class at compile time, so the counter is a plain load and add, not a lock-prefixed one
A cycle of strong references leaksreference counting cannot detect a cycle; break an edge with Weak<T>
Shared<T> costs an explicit keywordthe compiler never inserts a refcount operation you did not write
unshare s consumes the handle either wayon the contended outcome your reference is genuinely released; there is no restore-increment

The ordering of the atomics and the exact lowering of the two transitions are on Refcount and transitions.

Limits / Uncabled

FeatureStateDetail or workaround
Sharing a handle through a global variableThe thread-locality analysis reads function signatures and class field graphs, not global variables. A class reachable from two threads only through a global keeps non-atomic counts.Do not publish a Shared<T> handle through a global that another thread reads. Hand it over through spawn or a Thread argument instead.
Automatic cycle detectionNot implemented. A cycle made only of Shared<T> edges leaks its storage and nothing reports it: breaking the cycle with a Weak<T> edge is the author’s job.Make the reference that points back toward the owner a Weak<T>.
Shared arrays holding objects or stringsRefused with E0766: the elements must own nothing.Share a class that holds the array; the class is then the shared value.

See also

  • Memory model — the four storage tiers and how the compiler picks between them.
  • Language tour — the ownership prefixes on parameters that pair with this page.
  • Reading compiler errors — E0501–E0506 cover the move/use diagnostics that interact with Shared<T> bindings.
  • Tasks and async — the primary user of Shared<T> across task boundaries.
  • Refcount and transitions — the 16-byte header, atomic ordering, and the share / unshare lowering.
  • Concept index — every shared-memory concept cross-linked.
memorysharedrefcountownership