std/task/lib

A computation that finishes later, running from the moment it is created (spawn { ... }, or calling a function that returns one).

Reach for it wherever work should happen while the caller keeps going. map and flatMap mean the same as everywhere else and work on the finished value.

• Dropping the last handle does not stop the task: a task runs until it finishes or somebody calls Task.cancel.

• spawn - starts a task from a closure.
• both - waits for two tasks of different types at once; Task.all does the same for any number of the same type.

Runs the closure as a new task, in parallel. It gets copies of what it captures and cannot capture a var.

Waits for two tasks of different types at once: const (user, posts) = both(fetchUser(1), fetchPosts(1)).await(). Where one of them is cancelled, the other is cancelled too and this task ends as cancelled - and whoever awaits it with it.

It is both and not all: it takes exactly two tasks, each of its own type, while Task.all waits for a list of tasks of one type and Iterate.all asks a predicate of every item.

The worker pool of this process: how many operating-system threads run its tasks. A reading namespace - the count is decided before the first line of the program runs and never changes, because every worker owns a heap.

• spawn - a task an idle worker may take before it first runs.
• offload - a body that blocks, run on the blocking pool.

Puts this task at the back of the queue and lets every other ready task run first. It is what makes a long loop fair; a loop of a task is cancellable at every turn without it.

Runs body on a thread of the blocking pool instead of on a worker, so a call that blocks - reading a file, running a child process, a C library that waits - does not stall the other tasks of the worker that asked.

const text = offload({ File.readText("notes.txt") }).await()

Reach for it around one blocking call, not around a computation: a computation that is merely long belongs on the workers, with spawn or parallel(), because the pool has only Workers.blocking threads.

• The body moves to the pool only where the closure may cross to another thread: where it captures nothing counted, or only literals and other values nothing else holds a count of. A closure that captures a String built at run time, a list or a shared type object runs on the worker that asked - the same answer, but it blocks that worker as a direct call would (docs/design/CONCURRENCY.md section 16, "The blocking pool, as built").
• The body cannot await. Cancelling the task does not interrupt a body that already runs: it runs to its end on its thread, and what it answers is thrown away.

A stream in memory, of which one holder has both ends: a queue between two tasks.

const channel = Channel<Report>(capacity: 8)
const writer = spawn { channel.sink().fill(reports).await() }
const total = channel.source().count().await()

channel.source() and channel.sink() are a Source and a Sink and can be handed out separately, so a producer never sees the reading end and a consumer never sees the writing one. They are methods and not fields because they are computed, and because a field would have to be passed to the constructor. They answer the concrete ChannelSource and ChannelSink, so a call on one is a direct call; where a Source or a Sink is asked for, either of them is one.

Reading cannot fail: a closed channel is the end of the stream, not a failure, and a cancellation is passed on rather than answered. The writing end fails with ChannelClosed once the reader is gone, which is how a producer learns that nobody wants its items any more - the cancellation signal of Source.produce.

The reading end of a Channel, a Source<Item, Never>: every next() waits for the next item, and close() tells the writers to stop.

The writing end of a Channel, a Sink<Item, ChannelClosed>: add finishes once a reader took the item, end() and close() end the stream.

Nobody is reading any more: the reading end of the channel was closed. The only way a Channel's writing end fails, and a value rather than a panic, because a producer with nobody left to feed should stop, not crash.

A producer whose own failure is ChannelClosed needs no conversion to learn that nobody reads any more.

A task that stopped because somebody asked it to, as Task.result answers it. It carries no reason: who asked and why is the canceller's knowledge, and a deadline has a failure of its own, TimedOut. await() never answers it - a cancellation it meets is passed on to the waiter instead.

A deadline that passed: what Task.within answers when the limit came first.