Skip to content

std::tasks

Tasks: work running in parallel inside a concurrent block. Task.spawn starts one and Task.await waits for its value; Task.spawn_all and Task.await_all do the same for many at once, with a bound on how many run together. Task.outcome returns how a task ended as a value (Outcome: completed, cancelled or failed), and Task.cancel stops one. Where a task may be spawned, what may not escape its block, and how errors and cancellation travel are language rules (Concurrency).

Import with import std::tasks.

enum Failure
    Panicked String
    Errored String
end

Why a task failed. A cancelled task has not failed, so cancellation is not one of these: it is Outcome.Cancelled.

Variants

  • Panicked

    A fault in the runtime itself, with its text. No Nomi code causes one.

  • Errored

    A trap in the task’s body, with the fault’s text and line: line 5: `m` found nothing.

impl Debug for Failure

fn inspect(value: Failure) -> String

impl Debug.inspect

enum Outcome<T>
    Completed T
    Cancelled
    Failed Failure
end

How a task ended, as Task.outcome returns it.

An Err the body returned is a value, not a failure: that task is Completed and holds the Err. Failed is a trap in the body.

Variants

  • Completed

    The body returned this value.

  • Cancelled

    The task was cancelled before it finished.

  • Failed

    The body trapped.

impl Debug for Outcome<T>

fn inspect<T>(value: Outcome<T>) -> String where T: Debug

impl Debug.inspect

type Task<T>

The handle of a running or finished task. T is the type its body returns. A body that can fail returns a Result, and Task.await(task)? propagates its Err as any call’s.

A task belongs to the concurrent block it was spawned in, and the compiler holds it there. A Task.spawn that can run outside every block is an error. So is a task that is never passed to Task.await, Task.await_all or Task.outcome, and one that leaves its block by being returned or sent on a channel. _ = Task.await(t) waits for a task and discards its value.

fn spawn<T>(body: () -> T) -> Task<T>

type function on Task

Starts body as a task of the enclosing concurrent block and returns its handle at once. The body runs alongside the code that spawned it. A function that calls Task.spawn may be called from inside a block; a spawn that can run outside every block is a compile error.

value = concurrent
    task = Task.spawn(fn -> 42)
    Task.await(task)
end

assert value == 42
fn await<T>(task: Task<T>) -> T

type function on Task

Waits for task and returns its value.

An Err the body returned is a value and arrives here like any other, so Task.await(t)? propagates it.

A task that failed has no value, because its body trapped. Awaiting it traps with the task’s fault, as the trap would have ended the caller had the body run inline. Awaiting a cancelled task propagates the cancellation. Task.outcome returns either one as a value.

value = concurrent
    task = Task.spawn(fn -> "done")
    Task.await(task)
end

assert value == "done"
fn spawn_all<T, U>(source: Iter<T>, f: (T) -> U, max_running: PositiveInt) -> List<Task<U>>

type function on Task

Starts one task per item of source, each running f on its item, with at most max_running of them running at once. It returns a handle for each, in the source’s order.

max_running has no default. The limit protects what the tasks call: ten thousand items should not become ten thousand database queries at once, and only the program knows the right number.

It consumes the whole source and returns a List. As with Iter.to_list, a source that is Iter.is_infinite traps before any task is spawned, and one that never ends without saying so hangs.

results = concurrent
    [1, 2, 3]
    |> Task.spawn_all(&(&1 * 2), max_running: 2)
    |> Task.await_all()
end

assert results == [2, 4, 6]
fn await_all<U>(tasks: List<Task<U>>) -> List<U>

type function on Task

Waits for every task in tasks and returns their values, in the order of tasks.

An Err a body returned is a value. It stops nothing: the other tasks run to their end, and the result is a List<Result<U, E>> for the caller to handle.

A task that fails does stop the wait. await_all traps with that task’s fault as soon as it fails, without waiting for the tasks before it in the list. When two tasks fail, the fault is the one that happened first.

results = concurrent
    ["a", "b"]
    |> Task.spawn_all(&(&1 + "!"), max_running: 2)
    |> Task.await_all()
end

assert results == ["a!", "b!"]
fn outcome<T>(task: Task<T>) -> Outcome<T>

type function on Task

Waits for task, as Task.await does, and returns how it ended as a value: Completed with the body’s value, Cancelled, or Failed with the fault that ended the body. It never traps.

Use it to read a task you cancelled, and to report a task’s failure where Task.await would trap with it.

outcome = concurrent
    task = Task.spawn(fn -> 42)
    Task.outcome(task)
end

expected: Outcome<Int> = .Completed(42)
assert outcome == expected

// A body that traps is `Failed`, and the program carries on.
failed = concurrent
    task = Task.spawn(fn -> Iter.find([1, 2], &(&1 > 5))!)
    Task.outcome(task)
end

ending = case failed
    Outcome.Failed(_) -> "failed"
    _                 -> "other"
end

assert ending == "failed"
fn cancel<T>(task: Task<T>) -> Unit

type function on Task

Asks one task to stop and leaves the other tasks alone. The task stops at its next safe point and unwinds, running its deferred calls. A concurrent block inside it is cancelled too. It cancels a task of a concurrent block and a supervised task alike.

A cancelled task must still be awaited, and the wait ends once the task has stopped. Read it with Task.outcome, which returns Cancelled; Task.await would propagate the cancellation.

Cancelling a task twice, or one that has finished, does nothing.

impl Debug for Task<T>

fn inspect<T>(value: Task<T>) -> String where T: Debug

impl Debug.inspect