Skip to content
Weaverv0.5.0

Tasks and concurrency

A Weaver program does several things at once through tasks: lightweight threads, each with its own stack, run by a pool of system threads. A task suspends wherever it waits, on a socket, a lock, a channel or another task, and its thread runs others meanwhile. Nothing marks the functions that wait: there is no colored async that spreads through the call graph.

Concurrency is structured. A task’s result comes back through a Promise, which is a resource: the compiler checks that every promise is awaited, cancelled or handed on, on every path, errors included. No task is left running behind the code that launched it.

Calling an async fn launches a task, and returns at once a Promise<T>; spawn launches a lambda. await p, or p.await as a suffix, waits for the result:

import weaver.io.print
import weaver.task.{spawn, Cancelled}
fn fib(n: Int): Int = if n < 2 { n } else { fib(n - 1) + fib(n - 2) }
/// Calling it launches a task.
async fn slowSquare(n: Int): Int = n * n
fn main() ! Cancelled {
val a = slowSquare(12) // a Promise<Int>: the task runs
using b = spawn(() => fib(30)) // so does this one, beside it
print("both are running")
print("${a.await!} and ${await b!}")
print("${slowSquare(3).await!}")
}
both are running
144 and 832040
9

async does not say that a function waits, but that calling it launches a task. Any function may await, and await f(x) on an async function just calls it in the current task, since the caller would wait anyway.

A wait can fail: the task that waits may have been cancelled meanwhile. await on a Promise<T> is therefore a T ! Cancelled, and on a Promise<T ! E> a T ! E | Cancelled, which ! propagates like any other error.

A lambda launched by spawn captures by value: a task never shares a variable with the code that launched it.

A promise that nobody awaits would be a task running loose. The compiler refuses it:

import weaver.task.{spawn}
fn main() {
val p = spawn(() => 42)
}
main.wft:4:3: resource `p` is neither disposed nor passed on at the end of the block: bind it with `using`, or pass it to `dispose`

The error paths count too. In the first program, a.await! can leave main with Cancelled before b is awaited: b is therefore bound with using, whose disposal, on such an exit, cancels the task then waits for it to stop. Without using, the compiler says so:

main.wft:13:12: resource `b` is neither disposed nor passed on if `!` propagates an error: bind it with `using`, or pass it to `dispose`

The same holds for two requests, where the first one’s failure must not leave the second behind:

import weaver.io.print
import weaver.task.{Cancelled}
#Error
enum FetchError = | NotFound(id: Int) `error("no user ${id}")`
async fn fetchName(id: Int): String ! FetchError {
if id > 100 { fail NotFound(id) }
return "user${id}"
}
async fn pair(a: Int, b: Int): String ! FetchError | Cancelled {
val first = fetchName(a)
using second = fetchName(b) // if `first.await!` leaves, second is cancelled
return "${first.await!} & ${second.await!}"
}
fn main() ! Cancelled {
print(pair(1, 2).await catch e => "error: ${e}")
print(pair(1, 200).await catch e => "error: ${e}")
}
user1 & user2
error: no user 200

await all(tasks) waits for an array of promises and gives their results in order; await all(a, b) waits for promises of different types and gives a tuple. await any(…) takes the first source to finish, a promise, a channel or a deadline, and cancels the others:

import weaver.io.print
import weaver.task.{spawn, all, any, Promise, Cancelled}
import weaver.time.{sleep, Timeout, seconds, millis}
fn fib(n: Int): Int = if n < 2 { n } else { fib(n - 1) + fib(n - 2) }
async fn word(n: Int): String = "#${n}"
/// A slow answer: a sleep is a point where the task can be cancelled.
async fn lookup(host: String): String ! Cancelled {
sleep(2.seconds()).await!
return "${host} is 10.0.0.1"
}
fn main() ! Cancelled {
val tasks = mut Promise<Int>[]()
for n in [25, 10, 20] { tasks.push(spawn(() => fib(n))) }
print("${await all(tasks)!}")
val (n, w) = await all(spawn(() => fib(15)), word(7))!
print("${n} ${w}")
match await any(lookup("example.org"), sleep(100.millis()))! {
String(addr) => print(addr)
Timeout => print("no answer within 100 ms")
}
}
[75025, 55, 6765]
610 #7
no answer within 100 ms

any gives the union of what its sources give, here String | Timeout, which a match takes apart by type.

For a number of tasks known only at run time, and a policy for their failures, a TaskScope<T, E> holds them. .collectAll, the default, lets every task finish; .failFast cancels the others at the first error; .race keeps the first success. Its disposal cancels and awaits whatever is left.

import weaver.io.print
import weaver.task.{TaskScope, Cancelled}
#Error
enum CheckError = | Unreachable(host: String) `error("${host} does not answer")`
fn check(host: String): Int ! CheckError {
if host.startsWith("down.") { fail Unreachable(host) }
return host.byteLen() * 3
}
fn main() ! Cancelled {
val hosts = ["a.example", "down.example", "c.example"]
using all = TaskScope<Int, CheckError>()
for h in hosts { all.spawn(() => check(h)) }
for r in all.results()! {
match r {
Ok(ms) => print("ok in ${ms} ms")
Err(e) => print("failed: ${e}")
}
}
using strict = TaskScope<Int, CheckError>(policy: .failFast)
for h in hosts { strict.spawn(() => check(h)) }
match strict.awaitAllOrFail() {
Ok(times) => print("all answered: ${times}")
Err(e) => print("stopped: ${e}")
}
}
ok in 27 ms
failed: down.example does not answer
ok in 27 ms
stopped: down.example does not answer

Cancellation is cooperative: p.cancel() asks the task to stop, and waits until it has. A task stops at a cancellation point: a wait, await, a lock, a channel, a socket, a sleep. A long computation that does not wait checks for itself, Task.current().checkCancelled()!, which fails with Cancelled:

import weaver.io.print
import weaver.task.{Task, Cancelled}
import weaver.time.{sleep, millis}
/// Counts as far as it may.
async fn countUp(): Int ! Cancelled {
var n = 0
loop {
if n % 10_000 == 0 { Task.current().checkCancelled()! }
n += 1
}
}
fn main() ! Cancelled {
using counting = countUp()
sleep(20.millis()).await!
counting.cancel() // asks, then waits for the task to stop
print("stopped")
}
stopped

Cancelling a task cancels the tasks it is awaiting in turn, down the tree. The disposal of a promise, of a scope, or of a pool cancels the same way.

A value passed to another task is copied or given up, never shared mutably. Tasks that exchange a stream of values do it through a channel: Channel<T>(capacity: n) gives a Sender and a Receiver, whose copies are as many producers and consumers.

import weaver.io.print
import weaver.task.{spawn, Channel, ChannelError, Cancelled}
fn main() ! ChannelError | Cancelled {
val (tx, rx) = Channel<String>(capacity: 8)
val producer = spawn(() => {
for word in ["pear", "fig", "apple", "kiwi"] { tx.send(word.copy())! }
tx.close()
})
var longest = ""
for word in rx {
print("received ${word}")
if word.byteLen() > longest.byteLen() { longest = word }
}
producer.await!
print("longest: ${longest}")
}
received pear
received fig
received apple
received kiwi
longest: apple
  • send gives the value up, a resource included: a file sent to a task belongs to it. A full channel suspends the sender, which bounds the memory a fast producer takes; a capacity of 0 makes each send a rendezvous.
  • A receiver is iterated with for, which ends once the channel is closed and drained. Close it explicitly, tx.close().
  • await any(a.receiving(), b.receiving()) receives from whichever channel has a message first; await any(rx.receiving(), sleep(d)) waits at most d.

What several tasks must see goes through an object made for it, whose copies all designate the same one:

import weaver.io.print
import weaver.task.{spawn, all, Promise, Shared, Mutex, AtomicInt, Cancelled}
import weaver.collections.Map
fn main() ! Cancelled {
val visits = Shared(Map<String, Int>())
val log = Mutex(String[]())
val served = AtomicInt(0)
val tasks = mut Promise<()>[]()
for i in 0..4 {
tasks.push(spawn(() => {
val page = if i % 2 == 0 { "/home" } else { "/docs" }
visits.write(v => v[page] = (v[page] ?? 0) + 1)
log.with(l => l.push("task ${i} served ${page}"))
val _ = served.add(1)
}))
}
val _ = await all(tasks)!
val counts = visits.get() // a snapshot, which never waits
print("/home ${counts["/home"] ?? 0}, /docs ${counts["/docs"] ?? 0}")
print("${log.with(l => l.len())} lines, ${served.load()} served")
}
/home 2, /docs 2
4 lines, 4 served
Shared(value) readers take a snapshot and never wait, get(), read(f); writers go one at a time, write(f)
Mutex(value) with(f) holds the lock for the call; a lock belongs to its task, which may wait while holding it
AtomicInt, AtomicBool load, store, add, exchange, compareExchange, without a lock
Semaphore, Latch, Barrier permits, a one-time gate awaited with await, a meeting point at each round

Tasks that wait on each other’s locks in a cycle are a deadlock: the runtime sees the cycle close, and stops the program with code 101, naming the tasks.

An actor is a state that only its methods change, one call at a time. Called from outside, a method launches a task and returns a promise:

import weaver.io.print
import weaver.task.{all, Promise, Cancelled}
/// An account that tasks credit together, one method at a time.
actor Account = { balance: Int, moves: Int }
impl Account {
fn open(): Account = Account{balance: 0, moves: 0}
fn credit(mut self, amount: Int): Int {
self.balance += amount
self.moves += 1
return self.balance
}
fn summary(self): String = "${self.balance} after ${self.moves} moves"
}
fn main() ! Cancelled {
val account = Account.open()
val tasks = mut Promise<Int>[]()
for i in 1..=10 { tasks.push(account.credit(i * 10)) }
val _ = await all(tasks)!
print(account.summary().await!)
}
550 after 10 moves

The state is read only through methods: account.balance is refused outside impl Account.

Tasks run on Pool.global(), sized on the machine’s processors. Work that blocks, or that a program wants apart, gets a pool of its own, declared at module level:

import weaver.io.print
import weaver.task.{ThreadPool, Task, spawn, Cancelled}
pool io = ThreadPool(threads: 4, name: "io")
/// Blocks on the network: it always runs on io.
@threadPool(io)
async fn download(url: String): Int = url.byteLen() * 100
fn poolName(): String = Task.current().pool().name()
fn main() ! Cancelled {
print("${download("https://example.org").await!} bytes")
print(spawn(() => poolName()).await!)
print(spawn(() => poolName(), on: io).await!)
on io {
val p = spawn(() => poolName())
print(p.await!)
}
}
1900 bytes
global
io
io

The most specific choice wins: spawn(…, on: p) at the call, then the function’s @threadPool, then an on p { … } block around the launch, then the global pool. A pool is a resource too: when the program ends, it cancels and awaits what still runs on it.

detach f(x) launches a task that its pool answers for, rather than a block. It gives a Daemon, a handle that observes and cancels the task, isDone(), result(), cancel(), but is not awaited. The task’s error goes to the pool’s onError, or to standard error:

import weaver.io.print
import weaver.task.{ThreadPool, Cancelled}
import weaver.time.{sleep, millis}
pool background = ThreadPool(
threads: 1,
name: "background",
onError: msg => print("background: ${msg}")
)
@threadPool(background)
async fn report(n: Int) ! UserError {
if n < 0 { fail "negative count ${n}" }
print("reported ${n}")
}
fn main() ! Cancelled {
val d = detach report(-3)
sleep(50.millis()).await!
print("done: ${d.isDone()}")
}
background: negative count -3
done: true
  • The tasks and channels guide sums up weaver.task, down to the task val that follows a request through the tasks it launches.
  • The reference, Errors and concurrency, has the rules: what a panic in a task does, how values are counted between threads, how a pool shuts down within a deadline.