Skip to content

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/await works in the interpreter, through C and in native executables (fid emit, fixed on Nov 9). The interpreter runs an async fn to 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, and Vec, HashMap, Option, Result, Box, Future, Mutex and Channel of 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_send must be @send too.

  • 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_lock or write_lock); the compiler rejects the program otherwise. Data shared through raw pointers is not checked.

  • stdlib/sync.fd has mutexes (sync_mutex_*), read-write locks (sync_rwlock_*) and atomics (atomic_u64_*); use atomic; gives Atomic with memory orders. Every order currently runs as SeqCst.

  • 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_new and friends (use rc;) give an atomically counted shared value.

Report an issue