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:
- Allocate with
share new T(...). - Annotate with
Shared<T>when the type isn’t inferred (fields, return types, generic args). - 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
newexpression (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(orshare xon an owned value) — never a plainnew. AShared<T>object carries a 16-byte refcount header (see below); theshare newallocator is what reserves it. A plainnew 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 plainnew T(...)where aShared<T>is expected is a compile error (E0034), whose hint tells you to allocate itshare new T(...)— or to share an already-built object withshare x. The wordshareappears 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(). Aselformut selfmethod 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], notshare afor 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.)
| Write | Meaning | Consumes its operand? | Result |
|---|---|---|---|
share x | an owned value becomes shared | yes, x | Shared<T> |
share new C(…) | allocate the shared block directly: one allocation, no copy | — | Shared<C> |
unshare s | take sole ownership back | yes, s, even when it fails | T \| null |
downgrade s | observe the object without keeping it alive | no | Weak<T> |
upgrade w | get a strong handle if the object still lives | no | Shared<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 xtakes a uniquely-owned value and always succeeds. The source binding is consumed — reading it after the share is a compile-time error (E0501).unshare sreturns the unique value if you held the sole strong reference,nullotherwise — and consumesseither way: the call releases your reference, and readingsafterwards is a compile-time error (E0501). On thenulloutcome 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→ aWeak<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, ornullonce 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.
Weak edges and nullable strong links in fields
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 plainload/add/store. When an instance can reach another thread — throughspawnor an FFI boundary — every inc/dec becomes alock-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
i32return 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
| Limit | Why it holds |
|---|---|
| Atomicity covers the handle, not the payload | two 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 atomic | thread-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 leaks | reference counting cannot detect a cycle; break an edge with Weak<T> |
Shared<T> costs an explicit keyword | the compiler never inserts a refcount operation you did not write |
unshare s consumes the handle either way | on 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
| Feature | State | Detail or workaround |
|---|---|---|
| Sharing a handle through a global variable | The 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 detection | Not 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 strings | Refused 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/unsharelowering. - Concept index — every shared-memory concept cross-linked.