Tasks and channels
Module weaver.task: its API, wv doc weaver.task.
A task is a lightweight thread: it has its own stack, runs on a pool’s
system threads, and suspends anywhere it waits, a socket, a lock, another
task, without its functions being marked. Its result comes back through a
Promise, a resource: whoever holds it answers for the task.
Launching and awaiting
Section titled “Launching and awaiting”Calling an async fn launches a task; spawn launches a lambda.
import weaver.task.{spawn}
async fn fetchUser(id: Int): User ! NetError { … }
fn page(id: Int): Page ! NetError | Cancelled { val user = fetchUser(id) // a Promise<User>: it runs val total = spawn(() => prices(id).sum()) // so does this one return Page{user: user.await!, total: total.await!}}p.awaitandawait pwait for the result: the task’s error, orCancelledif the waiting task was cancelled meanwhile.- A promise must be awaited, cancelled, returned or given up on every
path: forgetting one is a compile error. One that a
!could leave behind is bound withusing, whose disposal cancels then awaits it. await all(tasks)waits for an array of promises,await all(a, b)for several of different types, each result returned as is, its error included;await any(a, b)takes the first to finish and cancels the others.- A lambda captures by value: a launched task never shares a variable with its caller.
Groups: TaskScope
Section titled “Groups: TaskScope”A TaskScope holds a group of tasks, its policy saying what one failure
does: .collectAll waits for all, .failFast cancels the others at the
first error, .race keeps the first result.
using scope = TaskScope<Int, String>(policy: .failFast)for n in [3, 1, 2] { scope.spawn(() => compute(n)) }val all = scope.awaitAllOrFail()!results() gives each task’s result or error, awaitAny() the first,
cancel() cancels them all; the scope’s disposal awaits what is left.
Cancelling
Section titled “Cancelling”Cancellation is cooperative: p.cancel() asks, the task stops where it
checks. A wait, await, a lock, a channel, a socket, is such a point; a
long computation checks itself:
loop { Task.current().checkCancelled()! // fails with Cancelled step()}A cancelled promise cancels the tasks it awaits in turn.
Channels
Section titled “Channels”A channel passes values from tasks to tasks. Channel<T>(capacity: n)
gives its two ends, which are shared: their copies are as many producers
and consumers.
val (tx, rx) = Channel<Int>(capacity: 4)val producer = spawn(() => { for i in 1..=3 { tx.send(i * 10)! } tx.close()})for x in rx { handle(x) }producer.await!sendgives the value up, a resource included; a full channel suspends the sender, and a capacity of 0 makes each send a rendezvous.receive()returnsNoneonce the channel is closed and drained; a receiver is iterated withfor.- Close it explicitly,
tx.close(): a copy of the sender left in scope would keep the loop waiting. await any(a.receiving(), b.receiving())receives from whichever has a message first.
Sharing state
Section titled “Sharing state”A value passed to another task is copied, never shared mutably. What tasks must share goes through an object made for it:
Shared(value): readers take a snapshot and never wait,s.get(),s.read(f); writers go one at a time,s.write(f),s.update(f).Mutex(value):m.with(v => …)holds the lock for the call,m.update(f)replaces the value.AtomicIntandAtomicBool:load,store,add,exchange,compareExchange, without a lock.Semaphore(permits: n),sem.withPermit(() => …);Latch(count: n), awaited until counted down;Barrier(parties: n),arrive()at each round.- An
actoris a state only its methods change, one at a time; called from outside, a method returns a promise.
A lock belongs to its task, which may wait while holding it. Tasks waiting on each other’s locks are a deadlock: the runtime sees the cycle and stops the program with code 101, naming them.
Tasks run on Pool.global(), sized on the machine’s processors, unless
told otherwise. A program declares its own pools at module level, for work
that blocks or that it wants apart:
pool io = ThreadPool(threads: 32, name: "io")
@threadPool(io)async fn download(url: String): Bytes ! IoError { … } // always on io
fn main() { on io { val a = fetch(x) } // the launches written in the block val b = spawn(() => parse(y), on: io)}The most specific wins: spawn(…, on:), then the function’s
@threadPool, then the caller’s on block, then the global pool.
Fire and forget
Section titled “Fire and forget”detach f(x) launches a task its pool answers for, and gives a Daemon, a
handle that observes and cancels it, isDone(), result(), cancel(),
but is not awaited. The pool cancels and awaits its daemons when it is
disposed of; a daemon’s error goes to the pool’s onError, or standard
error.
What follows a task
Section titled “What follows a task”Task.current()andThread.current()say which task and which thread run: id, name, pool.- A
task valcarries a value for the duration of a call, the tasks it launches included: a request id, a deadline, the log handler.
task val requestId: String = "none"
requestId.bind("r-42", () => handle(req))