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.
Launching and awaiting
Section titled “Launching and awaiting”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.printimport 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 running144 and 8320409async 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 is not forgotten
Section titled “A promise is not forgotten”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.printimport weaver.task.{Cancelled}
#Errorenum 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 & user2error: no user 200Waiting for several
Section titled “Waiting for several”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.printimport 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 #7no answer within 100 msany gives the union of what its sources give, here String | Timeout,
which a match takes apart by type.
A group of tasks
Section titled “A group of tasks”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.printimport weaver.task.{TaskScope, Cancelled}
#Errorenum 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 msfailed: down.example does not answerok in 27 msstopped: down.example does not answerCancelling
Section titled “Cancelling”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.printimport 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")}stoppedCancelling 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.
Channels
Section titled “Channels”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.printimport 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 pearreceived figreceived applereceived kiwilongest: applesendgives 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 mostd.
Sharing state
Section titled “Sharing state”What several tasks must see goes through an object made for it, whose copies all designate the same one:
import weaver.io.printimport 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 24 lines, 4 servedShared(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.
Actors
Section titled “Actors”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.printimport 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 movesThe 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.printimport 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 bytesglobalioioThe 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.
Fire and forget
Section titled “Fire and forget”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.printimport 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 -3done: trueGoing further
Section titled “Going further”- The tasks and channels guide sums up
weaver.task, down to thetask valthat 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.