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:
| Call | What 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 asendon a full bounded one; - a
lock(), or asynchronizedon a lock another task holds; - an
acquire()with no permit free; - a
waitFor()on a latch that is not open yet; - a
readLock()orwriteLock()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
InterruptedExceptionwhen 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 declareInterruptedException(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 protecting | Reach 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 carrier | nothing: that carrier already serialises it |
| a section that itself waits | restructure 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.
synchronizedon ani32, astringor an array slot is E0770. A stdlib lock class is refused too, and that is the natural mistake:ReentrantLock,ReadWriteLockandSemaphoreare handles.synchronized (myLock)would key on the handle, not on the lock thatmyLock.lock()takes. Take those through their ownlock().
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
synchronizedon a local. Locking on anything shared (aShared<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;
} | Method | Signature | Throws | Notes |
|---|---|---|---|
lock() | () : void | none | block until acquired; parks the task while another holds the lock |
tryLock() | () : bool | none | never waits |
unlock() | () : void | IllegalStateException | release one acquisition. Only the holder may call it. A task holding no acquisition gets the exception, and the lock stays with its holder |
isLocked() | () : bool | none | a 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
i32keys, notstring? Inserting into aHashMapmoves the key and the value into the container. Astringparameter is only borrowed from the caller, so forwarding it straight intoputwould give away something you do not own. That is rejected as E0504. Scalar keys such asi32are copied, so they forward freely. SeeShared<T>and ownership for the moving rules.
| Method | Signature | Throws | Notes |
|---|---|---|---|
readLock() | () : void | none | many readers may hold it at once |
readUnlock() | () : void | IllegalStateException | a task holding no read lock gets the exception, and the other readers’ holds stay in place |
writeLock() | () : void | none | excludes all readers and other writers |
writeUnlock() | () : void | IllegalStateException | the holder releases its write lock |
tryReadLock() | () : bool | none | never waits |
tryWriteLock() | () : bool | none | never 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.
| Method | BoundedChannel | UnboundedChannel | Throws |
|---|---|---|---|
send(v) | parks while full | never waits | InterruptedException |
receive() | parks while empty | parks while empty | InterruptedException |
trySend(v) | false when full or closed | false when closed | none |
tryReceive() | 0 when empty or closed | 0 when empty or closed | none |
close() | ends both waits; releases a parked send | ends both waits | IOException |
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;
} | Method | Signature | Throws | Notes |
|---|---|---|---|
countDown() | () : void | none | decrements; at zero the latch opens |
waitFor() | () : void | InterruptedException | parks the task until the count reaches zero |
waitForWithTimeout(ms) | (i64) : bool | InterruptedException | false on timeout instead of waiting forever |
getCount() | () : i32 | none | the 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
} | Method | Signature | Throws | Notes |
|---|---|---|---|
acquire() | () : void | InterruptedException | parks until a permit is free |
tryAcquire() | () : bool | none | answers at once |
release() | () : void | none | frees one permit and wakes a parked waiter |
availablePermits() | () : i32 | none | the 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;
} | Method | Signature | Notes |
|---|---|---|
constructor(initial) | (i32) | creates the cell |
get() | () : i32 | atomic load |
set(v) | (i32) : void | atomic store |
getAcquire() | () : i32 | load with acquire ordering |
setRelease(v) | (i32) : void | store with release ordering |
incrementAndGet() | () : i32 | adds one, returns the new value |
decrementAndGet() | () : i32 | subtracts one, returns the new value |
addAndGet(d) | (i32) : i32 | adds d, returns the new value |
compareAndSet(expected, update) | (i32, i32) : bool | stores update only if the value equals expected. true when the swap happened |
compareAndSetAcqRel(expected, update) | (i32, i32) : bool | compareAndSet with acquire-release ordering |
swap(v) | (i32) : i32 | stores 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;
} | Method | Signature | Notes |
|---|---|---|
get() / set(v) | () : bool / (bool) : void | atomic load / store |
getAcquire() / setRelease(v) | () : bool / (bool) : void | acquire load / release store |
compareAndSet(expected, update) | (bool, bool) : bool | true if the swap fired, false if the current value did not match expected |
compareAndSetAcqRel(expected, update) | (bool, bool) : bool | compareAndSet with acquire-release ordering |
Snapshot of the surface
| You need to… | Reach for… |
|---|---|
| share a single int, long or bool | AtomicI32, AtomicI64, AtomicBoolean |
| protect a section a second OS thread can reach | synchronized (lock) { ... } |
| read often, write rarely | ReadWriteLock |
a lock object with tryLock | ReentrantLock |
| move values between two tasks that overlap | a channel: BoundedChannel for backpressure |
| move one value back to the spawner | a returned value and await |
| wait until a fixed set of tasks finish | their awaits, or CountDownLatch when the count is produced elsewhere |
| cap work in flight | Semaphore: acquire() parks until a permit frees, tryAcquire() answers at once |
Limits / Uncabled
| Feature | State | Detail / workaround |
|---|---|---|
A wait outside a task (in main, or a Thread::run body) | Runs the thread’s event loop between looks | It 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 own | Holds the carrier | No 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 lock | Parks the task holding the lock | Restructure the section so the lock is released before the wait |
tryReceive() on an empty or closed channel | Answers 0, the same as a queued 0 | Use receive() to tell a closed channel apart. Reserve tryReceive for protocols where 0 is never a payload |
trySend() on a full or closed channel | Answers false for both | Use send() if you need to wait, or check the channel’s state in your protocol |
CountDownLatch re-use | Single-use | Create a fresh latch |
UnboundedChannel growth | Unbounded | Rate-limit the producer elsewhere, or use BoundedChannel for backpressure |
| A primitive released before a waiting call reaches it | Not covered by the close-wakes-waiters guarantee | Do not release a primitive while another task may still call it |
Any of these waits inside an async fn | Refused (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
- The task world: a stack per job, and what a
spawncosts Shared<T>reference counting: lifetimes- Stdlib overview: the
std::concurrentsurface - Concept index: every concurrency primitive, cross-linked
- Conventions: concurrency idioms: the
Shared<T>plussynchronizedbaseline