std/task

NAME

std/task - task helpers for async ZuzuScript code.

SYNOPSIS

  from std/task import all, race, sleep, yield, timeout, Channel, CancellationSource;

  async function __main__ () {
    let a := spawn { await { sleep(0.1); }; "a"; };
    let b := spawn { await { sleep(0.1); }; "b"; };
    return await { all( [ a, b ] ); };
  }

IMPLEMENTATION SUPPORT

This module is supported by all implementations of ZuzuScript.

DESCRIPTION

This runtime-supported module provides the task type, cancellation objects, channels, timers, and combinators used with the await { ... } and spawn { ... } language forms.

The Phase A model follows JavaScript promises closely: creating a task starts independent work, and a spawned task's failure is observed only when the task is awaited or passed to a combinator such as all, race, or timeout. Unawaited spawned tasks are detached background work until the runtime shuts down. Async script entrypoints should be written as async function __main__ ( argv ) { ... }; the CLI awaits that function after loading the script.

EXPORTS

Classes

Task
The runtime task type.

Tasks are awaitable values. Awaiting a fulfilled task returns its result. Awaiting a rejected task throws the rejection value. Awaiting a cancelled task throws CancelledException or the stored cancellation reason.
- task.status()
  Parameters: none. Returns: String. Returns pending, running, sleeping, waiting, fulfilled, rejected, or cancelled.
- task.done()
  Parameters: none. Returns: Boolean. Returns true when the task has fulfilled, rejected, or been cancelled.
- task.poll()
  Parameters: none. Returns: Boolean. Makes one non-blocking progress check and returns whether the task has completed.
- task.cancel(reason?)
  Parameters: reason is an optional cancellation reason. Returns: Task. Cancels the task and returns the task.
Channel
Construct with new Channel(). Returns a simple channel object with send, recv, and close. send returns an immediately completed task for the buffered first version, or fails with ChannelClosedException if the channel is closed. recv returns a pending task when no message is available and resolves to null once a closed channel has been drained.

null is the documented end-of-stream result for an empty closed channel.
- channel.send(value)
  Parameters: value is any value that may be sent through the channel. Returns: Task. Sends a value or fails if the channel is closed.
- channel.recv()
  Parameters: none. Returns: Task. Resolves to the next value, or to null after a closed channel has drained.
- channel.close()
  Parameters: none. Returns: null. Closes the channel.
CancellationToken
Cancellation signal object.
- token.cancelled()
  Parameters: none. Returns: Boolean. Returns true when cancellation has been requested.
- token.reason()
  Parameters: none. Returns: value or null. Returns the cancellation reason.
- token.throw_if_cancelled()
  Parameters: none. Returns: null. Throws when cancellation has been requested.
- token.watch(task)
  Parameters: task is a Task. Returns: Task. Registers task for cancellation when the token is cancelled.
CancellationSource
Construct with new CancellationSource(). Calling source.cancel(reason) marks its token as cancelled, stores the cancellation reason, and cancels tasks registered with source.token().watch(task).
- source.token()
  Parameters: none. Returns: CancellationToken. Returns the source's token.
- source.cancel(reason?)
  Parameters: reason is an optional cancellation reason. Returns: null. Marks the token cancelled and cancels watched tasks.
- source.cancelled()
  Parameters: none. Returns: Boolean. Returns true when the source has been cancelled.
- source.reason()
  Parameters: none. Returns: value or null. Returns the stored cancellation reason.

Functions

resolved(value)
Parameters: value is any value. Returns: Task. Returns a task that resolves to value.
failed(message)
Parameters: message is a failure value. Returns: Task. Returns a task that fails with message.
sleep(seconds)
Parameters: seconds is a delay in seconds. Returns: Task. Returns a task that completes after the requested delay.
yield()
Parameters: none. Returns: Task. Returns a task that completes after yielding back to the async scheduler once.
all(tasks)
Parameters: tasks is an array of tasks. Returns: Task. Returns a task that awaits all tasks and resolves to an array of results in input order.

If any input task rejects or is cancelled, the all task rejects or is cancelled with that same failure.
race(tasks)
Parameters: tasks is an array of tasks. Returns: Task. Returns a task that resolves or fails with the first completed input task and cancels unfinished losing tasks.

Loser cancellation is part of the public contract. Keep task handles and await them separately if later completion is important.
timeout(seconds, task)
Parameters: seconds is a timeout in seconds and task is the task to await. Returns: Task. Returns a task that fails with TimeoutException if task does not complete before the timeout.

COPYRIGHT AND LICENCE

std/task is copyright Toby Inkster.

It is free software; you may redistribute it and/or modify it under the terms of either the Artistic License 1.0 or the GNU General Public License version 2.

Module