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.
Exports
Section titled “Exports”enum Failure
Section titled “enum Failure”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
-
PanickedA fault in the runtime itself, with its text. No Nomi code causes one.
-
ErroredA trap in the task’s body, with the fault’s text and line:
line 5: `m` found nothing.
Failure.inspect
Section titled “Failure.inspect”impl Debug for Failure
fn inspect(value: Failure) -> String
impl Debug.inspect
enum Outcome
Section titled “enum Outcome”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
-
CompletedThe body returned this value.
-
CancelledThe task was cancelled before it finished.
-
FailedThe body trapped.
Outcome.inspect
Section titled “Outcome.inspect”impl Debug for Outcome<T>
fn inspect<T>(value: Outcome<T>) -> String where T: Debug
impl Debug.inspect
type Task
Section titled “type Task”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.
Task.spawn
Section titled “Task.spawn”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
Task.await
Section titled “Task.await”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"
Task.spawn_all
Section titled “Task.spawn_all”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]
Task.await_all
Section titled “Task.await_all”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!"]
Task.outcome
Section titled “Task.outcome”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"
Task.cancel
Section titled “Task.cancel”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.
Task.inspect
Section titled “Task.inspect”impl Debug for Task<T>
fn inspect<T>(value: Task<T>) -> String where T: Debug
impl Debug.inspect