Skip to content
Weaverv0.5.0

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.

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.await and await p wait for the result: the task’s error, or Cancelled if 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 with using, 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.

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.

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.

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!
  • send gives the value up, a resource included; a full channel suspends the sender, and a capacity of 0 makes each send a rendezvous.
  • receive() returns None once the channel is closed and drained; a receiver is iterated with for.
  • 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.

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.
  • AtomicInt and AtomicBool: 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 actor is 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.

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.

  • Task.current() and Thread.current() say which task and which thread run: id, name, pool.
  • A task val carries 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))