Axle v0.22.0

Concurrency primitives

std/concurrent ships atomics, locks, channels and rendezvous primitives. Two facts about how the task world is scheduled decide how much of it you need, and which of it you can block on at all. Read those first.

What this page covers: what a task yields at, and which waits park it · what crosses from one task to another · atomics, locks, channels and the rendezvous primitives · when a lock is actually load-bearing · the limits of the surface.

See Tasks and async for the two-worlds model and for how to spawn a task in the first place.

One task at a time, on one carrier

A spawned task runs on a carrier, a thread of the process’s small carrier pool. A carrier runs one task at a time. There is no timer preemption and no time quantum: a task keeps its carrier until it gives way, and it gives way only at a wait.

A spawn is filed on a peer carrier, another OS thread of the pool. The first spawn boots the pool. The task and the frame that spawned it therefore run at the same instant on two threads. A spawn made inside a task distributes the same way, on the same pool. The pool is sized from the machine: cpus - 1, never fewer than two and never more than 64. A program that spawns a thousand tasks spreads them over the cores it has, instead of queueing them onto one.

  main (carrier 0)            peer carrier 1        peer carrier 2
  ─────────────────           ──────────────        ──────────────
  spawn bump(c, 250) ──────►  bump(c, 250)  ...
  spawn bump(c, 250) ───────────────────────────►   bump(c, 250)  ...
  await a ... (parks main)    runs until a wait     runs until a wait

The whole Future<T> surface is three calls:

CallWhat it does
await t on a Future<T>waits for the task to end and yields its result. A task that awaits parks and hands its carrier back
t.timeout(ms) on a Future<T>the same wait, bounded. On expiry TimeoutException is thrown. A spawned task keeps running, with nobody waiting for it
t.isAlive() on a Future<T>a non-consuming peek. It never parks

The other way a task yields to a sibling is a wait on a primitive, described below. A Thread is a different handle with a different verb, the blocking .join(), and it is not on your carrier at all. See Tasks and async: the third backing.

Between two waits, a task is alone on its carrier. No other task of that carrier can observe a read-modify-write half-done, however many fields it touches. That is why much code that would need a lock between real threads needs none here, as long as all of the state runs on that one carrier.

A spawn, however, puts its task on another carrier of the pool. State that the spawning frame and the spawned task both touch is genuinely shared between two threads, and it needs an atomic or a lock.

Every wait parks the task

A wait on a primitive of std/concurrent belongs to the scheduler. Each of these suspends the task that made it and hands its carrier to the others, so the sibling that will release the wait can run:

  • a receive() on an empty channel, or a send on a full bounded one;
  • a lock(), or a synchronized on a lock another task holds;
  • an acquire() with no permit free;
  • a waitFor() on a latch that is not open yet;
  • a readLock() or writeLock() that has to wait;
  • a Thread.join() on a thread that is still running.

A blocking socket call, a blocking name lookup and Process.waitFor do the same. Their syscall runs on the runtime’s worker pool while the task is parked. The prelude sleep(ms) parks the task on a timer.

A parked task waits on the primitive’s queue, not on a thread. The release that can satisfy the wait wakes the tasks queued there, and they check again. Releases are: a send, an unlock(), a release(), or a countDown() that opens the latch.

A wait made outside any task has no stack to park. That covers main and a Thread::run body. Such a wait queues its thread instead, and runs the thread’s event loop between two looks. The release wakes it the way it wakes a task. The loop is also what lets the tasks of its own carrier make the progress the wait depends on. A task that lives as long as the program is better written as a Thread::run, which owns a platform thread rather than a share of a carrier.

The non-waiting forms never wait at all: tryAcquire, tryLock, trySend and tryReceive. An unbounded channel’s send never has to wait either.

Note: a wait ends with InterruptedException when the primitive is closed under it. A channel closed while a task waits on it ends the wait that way, and so does a primitive whose owner released it. The verbs that declare InterruptedException (waitFor, waitForWithTimeout, acquire, send, receive) raise it. A permit or a count that was already available still wins over the closure.

Lock verbs (lock(), readLock(), writeLock()) declare no exception. When the primitive is closed under them, they return without the hold. A lock with no owner left excludes nothing.

What still holds the carrier is a call the runtime does not route: a blocking file read or write, or a blocking call into C of your own. Such a call stops every task on its carrier until it returns. A program whose sibling task is the one whose progress would end that call stops with it.

None of these waits may be made directly from an async fn. Its state machine runs on the stack of whoever resumes it, and a parked frame there would take the machine with it (E0767). Reach the wait through spawn, or use the ...Async form where one exists.

What crosses from one task to another

Return the value and await it. An await parks rather than blocks, so a result carried back through the Future<T> is a handoff that works:

struct Report {
    rows  : i32;
    bytes : i64;
}

fn analyse(path : string) : Report {
    let r : Report = Report { rows: path.length, bytes: path.length };
    return r;
}

fn main() : i32 {
    let job : Future<Report> = spawn analyse("/var/log/app.log");
    let report : Report = await job;
    return report.rows;
}

A channel is the handoff that does not need the two tasks to meet. Either side may reach the queue first. The one that finds the queue empty or full waits as a task, and leaves the other to run. The two stages overlap, which a returned value cannot express:

use std::concurrent::UnboundedChannel;

fn produce(ch : UnboundedChannel) : void ! InterruptedException {
    for (i of 0..100) { ch.send(i + 1); }
    ch.send(-1);                                  // end of stream
}

fn consume(ch : UnboundedChannel) : i32 ! InterruptedException {
    let mut total : i32 = 0;
    let mut v : i32 = ch.receive();
    while (v != -1) {
        total = total + v;
        v = ch.receive();
    }
    return total;
}

fn main() : i32 ! InterruptedException, IOException {
    let ch : UnboundedChannel = new UnboundedChannel();
    defer ch.close();

    let producer : Future<void> = spawn produce(ch);
    let consumer : Future<i32> = spawn consume(ch);
    await producer;
    return await consumer;                        // 5050
}

Neither await is load-bearing. The consumer is spawned second and reaches its first receive() against an empty queue. That wait suspends the task rather than the thread, so the producer runs and the value arrives. The -1 is a sentinel chosen by this program. It is not a language feature. A channel carries i32, so a protocol that ends has to say so with a value its payload never uses.

When you actually need a lock

The section you are protectingReach for
a section a second OS thread can reach (a Thread::run body, or the work of a spawn on another carrier)synchronized or ReentrantLock
a plain read-modify-write with no wait in it (no await, channel, lock or sleep), touched only by work on one carriernothing: that carrier already serialises it
a section that itself waitsrestructure it. A lock does not make it safe (see below)

The second row is why the stdlib and the samples still write synchronized around single updates. A lock taken where it is not strictly needed is a cheap statement of an invariant. A lock dropped because it looked redundant is a correctness argument that holds only until someone adds an await to the block.

class Counter {
    pub(file) n : i32;

    constructor() {
        self.n = 0;
    }
}

fn bump(mut c : Shared<Counter>, times : i32) : void {
    for (i of 0..times) {
        synchronized (c) {
            c.n = c.n + 1;
        }
    }
}

fn main() : i32 {
    let c : Shared<Counter> = share new Counter();

    let a : Future<void> = spawn bump(c, 250);
    let b : Future<void> = spawn bump(c, 250);
    let d : Future<void> = spawn bump(c, 250);
    let e : Future<void> = spawn bump(c, 250);
    await a;
    await b;
    await d;
    await e;

    if (c.n != 1000) { return 1; }
    return 0;
}

Never await inside a critical section

synchronized takes a lock keyed by the object’s identity. A ReentrantLock is such a lock, held as an object. Either one is owned by the task that entered it. It is re-entrant, so that task can walk straight back in. A sibling task waits on it like any other contender.

A task that holds the lock and then reaches an await parks while still holding it. Every task that wants the same lock waits for as long as that await lasts. A sibling whose progress the await depends on deadlocks with it.

In an async fn the compiler refuses both halves. An await inside synchronized is E0722, and entering synchronized at all is E0767. Outside an async fn nothing refuses it, so keeping the section free of waits is your job:

// Sketch of the placement, not a complete function: take the shared value
// under the lock, then await with the lock released.
let raw : i32 = 0;
synchronized (state) {
    raw = state.pending;          // the whole critical section
}
let rest : i32 = await other;     // the only yield, out here

Choosing between synchronized and explicit locks

synchronized (X) { ... }     block-scoped, exception-safe, reentrant
ReentrantLock                explicit object, can be passed around, tryLock
ReadWriteLock                many readers or one writer

Default to synchronized. It has less ceremony, releases automatically, and the lock travels with the data. Reach for ReentrantLock when you need tryLock, and for ReadWriteLock when reads vastly outnumber writes. Atomics are for the single-value case, where there is no section at all.

synchronized blocks

The simplest mutual-exclusion primitive. Name the object to guard, and the block holds that object’s identity-keyed, reentrant lock:

class Account {
    pub(file) id      : i32;
    pub(file) balance : i32;
    constructor(id : i32, initial : i32) {
        self.id = id;
        self.balance = initial;
    }
}

fn transfer(from : Shared<Account>, to : Shared<Account>, amount : i32) : void {
    // Lock ordering by a stable key (the account id). Every caller takes the
    // two locks in the same order, so no pair of them can deadlock.
    if (from.id < to.id) {
        synchronized (from) {
            synchronized (to) {
                from.balance = from.balance - amount;
                to.balance   = to.balance + amount;
            }
        }
    } else {
        synchronized (to) {
            synchronized (from) {
                from.balance = from.balance - amount;
                to.balance   = to.balance + amount;
            }
        }
    }
}

Properties:

  • Re-entrant: a task holding the lock can enter it again without deadlocking.
  • Exception-safe: the lock releases even if the body throws.
  • Block-scoped: no lock() / try / finally / unlock() boilerplate.

The parenthesised operand is part of the statement. synchronized has no key-less form, so every critical section names the object it locks. The object’s identity is the key. Any shared object will do, which is why the common shape locks on the very Shared<T> being mutated.

Note: the operand must be a reference to an object. The monitor is keyed on the operand’s address, so a value with no address names no monitor. synchronized on an i32, a string or an array slot is E0770. A stdlib lock class is refused too, and that is the natural mistake: ReentrantLock, ReadWriteLock and Semaphore are handles. synchronized (myLock) would key on the handle, not on the lock that myLock.lock() takes. Take those through their own lock().

Note: a monitor nothing can reach costs nothing. When the guarded object cannot leave the frame that made it (a plain local, never re-pointed, whose address never escapes), no other thread, task or coroutine can name it. The block then emits no lock at all. That is the common case of a defensive synchronized on a local. Locking on anything shared (a Shared<T>, a field, a receiver) keeps the real lock.

ReentrantLock: explicit lock object

Use it when you need tryLock semantics, or a lock object you can pass around explicitly:

use std::concurrent::ReentrantLock;

fn doProtectedWork() : void {
    println("in the critical section");
}

fn main() : i32 ! IllegalStateException {
    let lock : ReentrantLock = new ReentrantLock();

    if (lock.tryLock()) {
        defer lock.unlock();
        doProtectedWork();
    } else {
        // lock was busy: back off
    }
    return 0;
}
MethodSignatureThrowsNotes
lock()() : voidnoneblock until acquired; parks the task while another holds the lock
tryLock()() : boolnonenever waits
unlock()() : voidIllegalStateExceptionrelease one acquisition. Only the holder may call it. A task holding no acquisition gets the exception, and the lock stays with its holder
isLocked()() : boolnonea query with no synchronisation (advisory)

Pair lock() or tryLock() with defer unlock() immediately. The function that does this declares ! IllegalStateException, like any caller of a throwing method.

ReadWriteLock: multi-reader, single writer

Use it when reads dominate writes:

use std::concurrent::ReadWriteLock;
use std::collections::HashMap;

class Cache {
    rw    : ReadWriteLock;
    data  : HashMap<i32, i32>;

    constructor() {
        self.rw   = new ReadWriteLock();
        self.data = new HashMap<i32, i32>();
    }

    pub fn lookup(self, key : i32) : i32 ! IllegalStateException {
        self.rw.readLock();
        defer self.rw.readUnlock();
        return self.data.getOrDefault(key, -1);   // -1 on a miss
    }

    pub fn store(mut self, key : i32, value : i32) : void ! IllegalStateException {
        self.rw.writeLock();
        defer self.rw.writeUnlock();
        self.data.put(key, value);
    }
}

Why i32 keys, not string? Inserting into a HashMap moves the key and the value into the container. A string parameter is only borrowed from the caller, so forwarding it straight into put would give away something you do not own. That is rejected as E0504. Scalar keys such as i32 are copied, so they forward freely. See Shared<T> and ownership for the moving rules.

MethodSignatureThrowsNotes
readLock()() : voidnonemany readers may hold it at once
readUnlock()() : voidIllegalStateExceptiona task holding no read lock gets the exception, and the other readers’ holds stay in place
writeLock()() : voidnoneexcludes all readers and other writers
writeUnlock()() : voidIllegalStateExceptionthe holder releases its write lock
tryReadLock()() : boolnonenever waits
tryWriteLock()() : boolnonenever waits

Many readers can hold readLock() at once. writeLock() excludes all of them and every other writer. A waiting writer stops admitting new readers, so a steady stream of readers cannot starve it. A reader that arrives after a writer has queued waits behind that writer. A task that already holds a read lock may take another one at once.

The lock is not re-entrant across the read / write boundary. A task holding readLock must release it before calling writeLock.

Each read hold belongs to the task that took it.

Channels

A channel carries i32 values. send and receive wait when the queue is full or empty. That wait parks the task, so the producer and the consumer both make progress on one carrier. trySend and tryReceive never wait.

MethodBoundedChannelUnboundedChannelThrows
send(v)parks while fullnever waitsInterruptedException
receive()parks while emptyparks while emptyInterruptedException
trySend(v)false when full or closedfalse when closednone
tryReceive()0 when empty or closed0 when empty or closednone
close()ends both waits; releases a parked sendends both waitsIOException

BoundedChannel

spawn takes a function call, so the producer and the consumer are named functions. The capacity is the backpressure. A producer that outruns its consumer eventually finds the queue full and waits there, which stops an unbounded producer from growing the queue without limit.

use std::concurrent::BoundedChannel;

fn produce(ch : BoundedChannel) : void ! InterruptedException {
    for (i of 0..3) { ch.send(i + 1); }
}

fn consume(ch : BoundedChannel) : i32 ! InterruptedException {
    let mut sum : i32 = 0;
    for (i of 0..3) { sum = sum + ch.receive(); }
    return sum;
}

fn main() : i32 ! InterruptedException, IOException {
    let ch : BoundedChannel = new BoundedChannel(1);
    defer ch.close();

    let producer : Future<void> = spawn produce(ch);
    let consumer : Future<i32> = spawn consume(ch);
    await producer;
    return await consumer;                      // 6
}

A capacity below the number of sends does not fail. The producer parks when the single slot is taken, and resumes as the consumer drains it. Nothing here needs a thread of its own: a bounded channel between two tasks on one carrier is a pipeline with backpressure.

close(), and the channel’s release when its owner’s scope ends, also releases a send parked on a full queue. A producer waiting for room that no receive will ever make would otherwise wait forever, so end of stream is an answer to it.

Non-blocking variants

use std::concurrent::BoundedChannel;

fn main() : i32 ! IOException {
    let ch : BoundedChannel = new BoundedChannel(1);

    if (ch.trySend(42)) {
        // value queued
    } else {
        // channel full or closed: drop, retry, or back off
    }

    let v : i32 = ch.tryReceive();             // 0 if empty or closed
    ch.close();
    return v - 42;
}

trySend answers false for a full channel and for a closed one alike. tryReceive answers 0 for both “nothing yet” and “nothing ever”. receive is the verb that raises on a closed channel. Reserve tryReceive for protocols where 0 is never a legitimate payload.

UnboundedChannel

The same API, minus the capacity argument:

use std::concurrent::UnboundedChannel;

fn main() : i32 ! InterruptedException, IOException {
    let ch : UnboundedChannel = new UnboundedChannel();
    ch.send(1); ch.send(2); ch.send(3);        // never waits
    ch.close();
    return 0;
}

send never waits for room. That makes the unbounded variant the one to reach for when a task is the producer. It still grows without bound, so use it only where the producer is rate-limited elsewhere.

CountDownLatch: single-shot barrier

use std::concurrent::CountDownLatch;

fn initializeWorker() : void {
    println("worker ready");
}

fn startAcceptingRequests() : void {
    println("accepting");
}

fn initWorker(ready : CountDownLatch) : i32 {
    initializeWorker();
    ready.countDown();
    return 0;
}

fn main() : i32 ! InterruptedException {
    let ready : CountDownLatch = new CountDownLatch(3);

    let mut workers : Future<i32>[3];
    for (w of 0..3) { workers[w] = spawn initWorker(ready); }

    for (w of 0..3) { await workers[w]; }        // park, not block
    ready.waitFor();                             // already open: returns
    startAcceptingRequests();
    return 0;
}
MethodSignatureThrowsNotes
countDown()() : voidnonedecrements; at zero the latch opens
waitFor()() : voidInterruptedExceptionparks the task until the count reaches zero
waitForWithTimeout(ms)(i64) : boolInterruptedExceptionfalse on timeout instead of waiting forever
getCount()() : i32nonethe current count

waitFor() parks the calling task until the counter hits zero. The tasks that call countDown() run on their own carriers meanwhile, so the latch opens in whatever order the waits happen. The counter is single-use. To re-arm, create a fresh latch.

Semaphore: permit pool

use std::concurrent::Semaphore;

fn handleRequest(id : i32) : i32 {
    println("served");
    return id;
}

fn main() : i32 ! InterruptedException {
    let connPool : Semaphore = new Semaphore(8);

    let mut batch : Future<i32>[8];
    for (i of 0..8) { batch[i] = spawn handleRequest(i); }

    let mut served : i32 = 0;
    for (i of 0..8) { served = served + await batch[i]; }

    // Eight permits, eight tasks already settled: no acquire() ever waits.
    if (connPool.tryAcquire()) {
        connPool.release();
    }
    return served;                               // 0+1+...+7 = 28
}
MethodSignatureThrowsNotes
acquire()() : voidInterruptedExceptionparks until a permit is free
tryAcquire()() : boolnoneanswers at once
release()() : voidnonefrees one permit and wakes a parked waiter
availablePermits()() : i32nonethe current count

A permit pool caps the work in flight. A task that finds no permit parks, and the release() that frees one wakes it. tryAcquire() is the non-waiting form, for a caller that would rather back off than queue.

Atomics

Where a lock protects a section, an atomic protects a value. Every operation on it is one indivisible transition, so there is no window to widen and no rule to remember. Reach for one when the state is one value. The compiler emits each atomic method as a single hardware atomic at the call site, with no call into the stdlib shim. See Atomic cells lower to one instruction.

Atomics also stay correct once the state is reachable from a second OS thread, which a spawn on another carrier or a Thread::run makes it.

AtomicI32: a single counter, no section

use std::concurrent::AtomicI32;

fn main() : i32 {
    let counter : AtomicI32 = new AtomicI32(0);
    counter.incrementAndGet();                 // 0 -> 1, returns the new value
    counter.addAndGet(10);                     // returns the new value (11)
    counter.decrementAndGet();                 // back to 10, returns it
    counter.set(0);
    if (counter.get() != 0) { return 1; }
    return 0;
}
MethodSignatureNotes
constructor(initial)(i32)creates the cell
get()() : i32atomic load
set(v)(i32) : voidatomic store
getAcquire()() : i32load with acquire ordering
setRelease(v)(i32) : voidstore with release ordering
incrementAndGet()() : i32adds one, returns the new value
decrementAndGet()() : i32subtracts one, returns the new value
addAndGet(d)(i32) : i32adds d, returns the new value
compareAndSet(expected, update)(i32, i32) : boolstores update only if the value equals expected. true when the swap happened
compareAndSetAcqRel(expected, update)(i32, i32) : boolcompareAndSet with acquire-release ordering
swap(v)(i32) : i32stores v and returns the value it replaced

There is no bare increment() or decrement(). The value is always returned, so the caller never needs a separate read.

Cross-thread example:

fn bump1000(hits : AtomicI32) : i32 {
    let mut i : i32 = 0;
    while (i < 1000) {
        hits.incrementAndGet();
        i = i + 1;
    }
    return 0;
}

fn main() : i32 {
    let hits : AtomicI32 = new AtomicI32(0);

    let f1 : Future<i32> = spawn bump1000(hits);
    let f2 : Future<i32> = spawn bump1000(hits);

    await f1;
    await f2;
    return hits.get();                         // 2000: never less, never more
}

AtomicI64: the same shape, 64-bit

use std::concurrent::AtomicI64;

fn totalAfterAdd() : i64 {
    let bytes : AtomicI64 = new AtomicI64(0);
    bytes.addAndGet(4096);
    return bytes.get();
}

The method set is identical to AtomicI32, with the same get, set, getAcquire, setRelease, incrementAndGet, decrementAndGet, addAndGet, compareAndSet, compareAndSetAcqRel and swap. Only the width differs: i64 arguments and results.

AtomicBoolean: flag with compare-and-set

use std::concurrent::AtomicBoolean;

fn runOnceInitialization() : void {
    println("initialised");
}

fn main() : i32 {
    let started : AtomicBoolean = new AtomicBoolean(false);

    // Idempotent initialisation: only the first caller does the work.
    if (started.compareAndSet(false, true)) {
        runOnceInitialization();
    }
    return 0;
}
MethodSignatureNotes
get() / set(v)() : bool / (bool) : voidatomic load / store
getAcquire() / setRelease(v)() : bool / (bool) : voidacquire load / release store
compareAndSet(expected, update)(bool, bool) : booltrue if the swap fired, false if the current value did not match expected
compareAndSetAcqRel(expected, update)(bool, bool) : boolcompareAndSet with acquire-release ordering

Snapshot of the surface

You need to…Reach for…
share a single int, long or boolAtomicI32, AtomicI64, AtomicBoolean
protect a section a second OS thread can reachsynchronized (lock) { ... }
read often, write rarelyReadWriteLock
a lock object with tryLockReentrantLock
move values between two tasks that overlapa channel: BoundedChannel for backpressure
move one value back to the spawnera returned value and await
wait until a fixed set of tasks finishtheir awaits, or CountDownLatch when the count is produced elsewhere
cap work in flightSemaphore: acquire() parks until a permit frees, tryAcquire() answers at once

Limits / Uncabled

FeatureStateDetail / workaround
A wait outside a task (in main, or a Thread::run body)Runs the thread’s event loop between looksIt has no stack to park. Tasks on the same carrier still make progress while it waits
Blocking file read or write, and a blocking call into C of your ownHolds the carrierNo stdlib verb stands behind them, so nothing routes the wait to the scheduler. Put them in a Thread::run body, or accept that sibling tasks on the carrier stop with them
A section that waits, under a lockParks the task holding the lockRestructure the section so the lock is released before the wait
tryReceive() on an empty or closed channelAnswers 0, the same as a queued 0Use receive() to tell a closed channel apart. Reserve tryReceive for protocols where 0 is never a payload
trySend() on a full or closed channelAnswers false for bothUse send() if you need to wait, or check the channel’s state in your protocol
CountDownLatch re-useSingle-useCreate a fresh latch
UnboundedChannel growthUnboundedRate-limit the producer elsewhere, or use BoundedChannel for backpressure
A primitive released before a waiting call reaches itNot covered by the close-wakes-waiters guaranteeDo not release a primitive while another task may still call it
Any of these waits inside an async fnRefused (E0767)The machine’s frame runs on the stack of whoever resumes it, so a parked frame there takes the machine with it

See Every wait parks the task for which waits the scheduler owns, and which still hold the carrier.

See also

concurrencytasksmutexchannelsatomics