Docs/Language/Concurrency
Concurrency
async tasks, structured concurrency with spawn scope, cancellation, channels and select, and green threads.
~5 min read
On this page
Async / await
An async fn returns Future<T>. Calling it starts a task (a green thread with its own stack) that runs until it first waits; await f waits for the result:
use task;
async fn slow_double(id: i64, ms: i64) -> Future<i64> {
task_sleep(ms); // suspends this task only
return id * 2;
}
fn main() -> i64 {
val a = slow_double(1, 50); // both tasks start now
val b = slow_double(2, 10);
println("started");
println((await a) + (await b));
return 0;
}Output: started, 6. A task suspends at await, task_sleep, task_yield, task_wait_read and task_wait_write. A Future is an ordinary value, and a plain fn can await one. f64 and struct arguments travel to the task through a generated adapter:
struct Point { x: i64, y: i64 }
async fn scaled(p: Point, f: f64) -> Future<i64> {
return ((p.x + p.y) as f64 * f) as i64;
}
fn main() -> i64 {
val t = scaled(Point { x: 2, y: 3 }, 2.5);
println(await t); // 12
return 0;
}Good to know:
async/awaitworks in the interpreter, through C and in native executables (fid emit, fixed on Nov 9). The interpreter runs anasync fnto its end when it is called, so a program that interleaves tasks can print in a different order there.
spawn and spawn scope
spawn f(args); runs a call on another thread. Every argument of the spawned call must be @send (below). A spawn scope { } block joins every task spawned in it at its closing brace, and cancel scope; stops the ones that have not finished:
fn work(n: i64) -> i64 {
println(n * 10);
return n;
}
fn main() {
spawn scope {
spawn work(1);
spawn work(2);
} // both tasks are joined here
println("all done");
spawn scope {
spawn work(3);
cancel scope; // stop tasks that have not finished
}
println("scope closed");
}Output: 10, 20 (in either order), all done, then scope closed (after 30 if task 3 already ran). For cancelling from inside a task, see the Cancel.stop handler in Errors & Effects.
Green threads
stdlib/task.fd schedules many tasks over one worker per CPU, each with its own stack; tasks also yield at loop safepoints, so a busy loop cannot starve the others. In the interpreter a task runs to its end when started.
use task;
fn worker(n: i64) -> i64 {
task_yield(); // let other tasks run
return n * 2;
}
fn main() -> i64 {
val t = task_go("worker", 21);
task_run(); // run every task to the end
println(task_result(t)); // 42
return 0;
}Channels and select
p_chan_create(n) makes a bounded channel; p_chan_send, p_chan_recv and p_chan_close use it. select runs the first case whose channel has a value, or default:
fn main() {
val jobs = p_chan_create(4); // bounded channel
val control = p_chan_create(1);
p_chan_send(control, 9);
select {
case jobs => j => { println(j); }
case control => c => { println(f"control {c}"); }
default => { println("idle"); }
}
}Output: control 9. use channel; gives the same operations as channel_create, channel_send, channel_recv, channel_try_recv and channel_close; channels carry i64 values.
Fork-join: parallel
parallel { | ... | ... } runs its branches on threads and joins them all at the end of the block. A branch that is one call, or x = f(...), is spawned, and x gets the result at the join. A branch of several statements runs on its own thread when it only reads word-sized locals (numbers, bool) and assigns none; any other branch runs in order on the current thread.
fn report(name: str) -> i64 {
println(name);
return 0;
}
fn main() -> i64 {
parallel {
| report("left")
| report("right")
}
println("both done");
return 0;
}With results:
fn fib(n: i64) -> i64 {
if n < 2 { return n; }
return fib(n - 1) + fib(n - 2);
}
fn main() -> i64 {
var a: i64 = 0;
var b: i64 = 0;
parallel {
| a = fib(25);
| b = fib(26);
}
println(a + b); // 196418
return 0;
}The parallel stdlib module has par_sum and par_dot, which split large inputs (10,000 elements or more) across threads.
Sharing state
- Every argument of a spawned call, and every variable the spawned expression names, must be
@send. Numbers,bool,str, enums, structs marked@send, structs whose fields are all@send, andVec,HashMap,Option,Result,Box,Future,MutexandChannelof such types are@send. References and raw pointers are not:
fn read(p: &i64) -> i64 { return *p; }
fn main() -> i64 {
val x = 5;
spawn scope {
spawn read(&x);
}
return 0;
}error: Thread safety error (line 6): argument 1 of the spawned call has type &i64, which is not @send.
Fix: pass a value (numbers, strings, structs of such values) or mark the struct @send.A value sent to a channel with
p_chan_sendmust be@sendtoo.A function that runs on another thread, or any function it calls, may not assign a global unless it calls a lock function (one whose name ends in
mutex_lockorwrite_lock); the compiler rejects the program otherwise. Data shared through raw pointers is not checked.stdlib/sync.fdhas mutexes (sync_mutex_*), read-write locks (sync_rwlock_*) and atomics (atomic_u64_*);use atomic;givesAtomicwith memory orders. Every order currently runs asSeqCst.Each thread allocates from its own free lists (and, in the C runtime, its own arenas). No multi-thread stress test has been run on them yet.
arc_newand friends (use rc;) give an atomically counted shared value.