Fut

value class Fut<vault T>

The Fut (rhymes with "cute") type represents the eventual completion and output of an asynchronous task. It is essentially a write-once container for a single object of type T.

You can schedule continuations with the then family of methods, which will run a task when the Fut is completed. Continuations will have access to the value stored in the Fut when they run.

When Fut is initially constructed, it is in the incomplete state. Once during the object's lifetime, the Fut can be completed by supplying a value of type T. Once the Fut reaches the complete state, any scheduled continuations will run. Any continuations that are scheduled after completion will run immediately.

There are multiple pathways for a Fut to be completed:

• A Fut constructed in user code must be explicitly completed by calling the complete method.
• A Fut constructed implicitly by the compiler for an async function must be explicitly completed by async return or async done.
• A Fut returned from a standard Guardian function (e.g., Guard::runCondition) will be completed automatically by the runtime.

Failure

Instead of being completed with a value, a Fut can fail. This happens when the task which would have completed it fails with a runtime error, such as an out-of-bounds index. A failure propagates like a value does: the continuations of a failed Fut don't run, and the Futs they would have completed fail with the same error. Because of the must-consume rule, a failure keeps propagating until it reaches the entry function, where join reports it and ends the program. When the entry function returns a Fut, it is joined automatically.

A failure doesn't affect unrelated tasks, and guards are always released, so tasks waiting on the same guards still run.

Fut is in the Prelude, meaning it is always available and does not need to be imported.

API Reference

Constructors

new()

Constructs a new Fut in the incomplete state.

Methods

then(task: () -> void) -> Fut<void>

Schedules task to be run when the Fut is completed. Returns a new Fut that will be completed when task returns.

then<O>(task: (T) -> O) -> Fut<O>

Schedules task to be run when the Fut is completed. The task will have access to the value stored in the Fut. Returns a new Fut that will be completed with the return value of task.

thenCompose<O>(task: (T) -> Fut<O>) -> Fut<O>

Schedules task to be run when the Fut is completed. The task will have access to the value stored in the Fut. Returns a new Fut that represents the completion of the Fut returned by task, with the same value.

complete(val: T) -> void

Completes the Fut with the given value.

join() -> T 🛑

Blocks until the Fut is completed, then returns the value. If the Fut failed, the program ends with its error instead.

Blocking functions are only allowed in the entry function.

Static Methods

all<T>(futs: ValueArray<Fut<T>>) -> Fut<Array<T>>

Returns a new Fut that, upon completion of every Fut in futs, will be completed with an array of the values of each Fut.

completed<T>(val: T) -> Fut<T>

Returns a new Fut in the complete state with the given value.

completed() -> Fut<void>

Returns a new Fut<void> in the complete state.