nish:async

Tasks for async functions: start one and go on, or await two to eight at once.

import {
  awaitAll,
  cancel,
  cancelAfter,
  cancelled,
  readable,
  readableWithin,
  sleep,
  spawn,
  taskId,
  writable,
  writableWithin,
} from "nish:async";
import { awaitAll, spawn } from "nish:async";

const double = async (x: i32): Promise<i32> => {
  return x * 2;
}

const log = async (x: i32): Promise<void> => {
  console.log(x);
}

const run = async (): Promise<void> => {
  const [c, d] = await awaitAll(double(1), double(2));
  spawn(log(c + d));
}

All five are reached only through the import. Each argument to awaitAll or spawn is a direct call to an async function, written where it is made, which the checker holds it to (src/async-check.ts); tsc sees ordinary promises. A spawned call's arguments are numbers, booleans, enums or strings (NL2673): the task outlives the function that spawned it.

sleep(ms), readable(fd) and writable(fd) are the waits a task makes on the executor, an epoll (kqueue on Darwin) loop that resumes ready tasks in the kernel's order and then expired timers by deadline:

import { readable, sleep } from "nish:async";

const tick = async (): Promise<void> => {
  await sleep(10);
  console.log("tick");
}

There is no async in a wasm build: under a wasm32 target or --profile wasi an async function is NL2652.

Under `--emit-ts`

nish:async is nish/runtime/async.mjs: awaitAll is Promise.all over its calls, and spawn starts its task without awaiting it and keeps it, for the launcher to wait on before it exits. The output resumes in Node's order, not the native one.

Rules: https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#async-functions-async-and-await

Functions

awaitAll

Wait for two calls at once. It is awaited into one name per call, const [a, b] = await awaitAll(...); one call, or an awaitAll not so destructured, is NL2647.

const awaitAll: <A, B>(
  a: Promise<A>,
  b: Promise<B>,
) => Promise<[A, B]>
aPromise<A>required

The first direct call to an async function.

bPromise<B>required

The next direct call to an async function.

returnsPromise<[A, B]>

The answers, in the order the calls are written.

Wait for three calls at once. It is awaited into one name per call, const [a, b, c] = await awaitAll(...); one call, or an awaitAll not so destructured, is NL2647.

const awaitAll: <A, B, C>(
  a: Promise<A>,
  b: Promise<B>,
  c: Promise<C>,
) => Promise<[A, B, C]>
aPromise<A>required

The first direct call to an async function.

bPromise<B>required

The next direct call to an async function.

cPromise<C>required

The next direct call to an async function.

returnsPromise<[A, B, C]>

The answers, in the order the calls are written.

Wait for four calls at once. It is awaited into one name per call, const [a, b, c, d] = await awaitAll(...); one call, or an awaitAll not so destructured, is NL2647.

const awaitAll: <A, B, C, D>(
  a: Promise<A>,
  b: Promise<B>,
  c: Promise<C>,
  d: Promise<D>,
) => Promise<[A, B, C, D]>
aPromise<A>required

The first direct call to an async function.

bPromise<B>required

The next direct call to an async function.

cPromise<C>required

The next direct call to an async function.

dPromise<D>required

The next direct call to an async function.

returnsPromise<[A, B, C, D]>

The answers, in the order the calls are written.

Wait for five calls at once. It is awaited into one name per call, const [a, b, c, d, e] = await awaitAll(...); one call, or an awaitAll not so destructured, is NL2647.

const awaitAll: <A, B, C, D, E>(
  a: Promise<A>,
  b: Promise<B>,
  c: Promise<C>,
  d: Promise<D>,
  e: Promise<E>,
) => Promise<[A, B, C, D, E]>
aPromise<A>required

The first direct call to an async function.

bPromise<B>required

The next direct call to an async function.

cPromise<C>required

The next direct call to an async function.

dPromise<D>required

The next direct call to an async function.

ePromise<E>required

The next direct call to an async function.

returnsPromise<[A, B, C, D, E]>

The answers, in the order the calls are written.

Wait for six calls at once. It is awaited into one name per call, const [a, b, c, d, e, f] = await awaitAll(...); one call, or an awaitAll not so destructured, is NL2647.

const awaitAll: <A, B, C, D, E, F>(
  a: Promise<A>,
  b: Promise<B>,
  c: Promise<C>,
  d: Promise<D>,
  e: Promise<E>,
  f: Promise<F>,
) => Promise<[A, B, C, D, E, F]>
aPromise<A>required

The first direct call to an async function.

bPromise<B>required

The next direct call to an async function.

cPromise<C>required

The next direct call to an async function.

dPromise<D>required

The next direct call to an async function.

ePromise<E>required

The next direct call to an async function.

fPromise<F>required

The next direct call to an async function.

returnsPromise<[A, B, C, D, E, F]>

The answers, in the order the calls are written.

Wait for seven calls at once. It is awaited into one name per call, const [a, b, c, d, e, f, g] = await awaitAll(...); one call, or an awaitAll not so destructured, is NL2647.

const awaitAll: <A, B, C, D, E, F, G>(
  a: Promise<A>,
  b: Promise<B>,
  c: Promise<C>,
  d: Promise<D>,
  e: Promise<E>,
  f: Promise<F>,
  g: Promise<G>,
) => Promise<[A, B, C, D, E, F, G]>
aPromise<A>required

The first direct call to an async function.

bPromise<B>required

The next direct call to an async function.

cPromise<C>required

The next direct call to an async function.

dPromise<D>required

The next direct call to an async function.

ePromise<E>required

The next direct call to an async function.

fPromise<F>required

The next direct call to an async function.

gPromise<G>required

The next direct call to an async function.

returnsPromise<[A, B, C, D, E, F, G]>

The answers, in the order the calls are written.

Wait for eight calls at once. It is awaited into one name per call, const [a, b, c, d, e, f, g, h] = await awaitAll(...); one call, or an awaitAll not so destructured, is NL2647.

const awaitAll: <A, B, C, D, E, F, G, H>(
  a: Promise<A>,
  b: Promise<B>,
  c: Promise<C>,
  d: Promise<D>,
  e: Promise<E>,
  f: Promise<F>,
  g: Promise<G>,
  h: Promise<H>,
) => Promise<[A, B, C, D, E, F, G, H]>
aPromise<A>required

The first direct call to an async function.

bPromise<B>required

The next direct call to an async function.

cPromise<C>required

The next direct call to an async function.

dPromise<D>required

The next direct call to an async function.

ePromise<E>required

The next direct call to an async function.

fPromise<F>required

The next direct call to an async function.

gPromise<G>required

The next direct call to an async function.

hPromise<H>required

The next direct call to an async function.

returnsPromise<[A, B, C, D, E, F, G, H]>

The answers, in the order the calls are written.

cancel

Cancel a task: every sleep, readable or writable it is waiting on answers false at once, and so does every one it makes later, so it runs on to its end, its using bindings dispose and its region is freed. A task is never stopped in the middle of its code. Refused under --emit-ts (NL4018).

const cancel: (task: i64) => boolean
taski64required

A handle taskId() answered.

returnsboolean

true while the task is still running, so it is now cancelled (a second cancel of it answers true too); false for a task that has finished, or for main.

cancelAfter

Cancel a task ms milliseconds from now, unless it finishes first. A later call replaces the deadline; a negative ms removes it. Refused under --emit-ts (NL4018).

const cancelAfter: (task: i64, ms: i32) => boolean
taski64required

A handle taskId() answered.

msi32required

The milliseconds until the task is cancelled.

returnsboolean

true when the task is still running and the deadline is set (or removed); false for a task that has finished or is main.

cancelled

Whether the running task has been cancelled. Refused under --emit-ts (NL4018).

const cancelled: () => boolean
returnsboolean

true once cancel was called on it, or its cancelAfter deadline passed.

readable

Suspend the task until fd has bytes to read, or its peer has hung up, while the executor runs the others. Written only as await readable(fd) inside an async function (NL2671). Refused under --emit-ts (NL4017).

const readable: (fd: i32) => Promise<boolean>
fdi32required

An open descriptor: a socket, a pipe or a terminal.

returnsPromise<boolean>

true once fd is ready; false when the wait could not be made (an fd that is not open). A regular file is always ready.

readableWithin

Suspend the task until fd has bytes to read, or its peer has hung up, or ms milliseconds pass, whichever comes first. Written only as await readableWithin(fd, ms) inside an async function (NL2671). Refused under --emit-ts (NL4018).

const readableWithin: (fd: i32, ms: i32) => Promise<boolean>
fdi32required

An open descriptor: a socket, a pipe or a terminal.

msi32required

The most milliseconds to wait; a negative ms waits without a limit, as readable does.

returnsPromise<boolean>

true once fd is ready; false when ms passed first, when the wait could not be made, or when the task is cancelled.

sleep

Suspend the task for ms milliseconds while the executor runs the others. Written only as await sleep(ms) inside an async function (NL2671).

const sleep: (ms: i32) => Promise<boolean>
msi32required

The milliseconds to wait, an i32.

returnsPromise<boolean>

true once the time has passed; false at once for a negative ms, which makes no wait.

spawn

Start task as a task of its own and go on without waiting for it. It runs at once until it first waits on the outside world, then spawn returns; a task that never waits has finished before spawn returns.

const spawn: (task: Promise<void>) => void
taskPromise<void>required

A direct call to an async function (NL2644). Nothing reads its answer, so it answers void or a Result it reports itself (NL2646).

taskId

The running task's handle, to hand to cancel or cancelAfter. main's handle is 0, which no call cancels. Refused under --emit-ts (NL4018).

const taskId: () => i64
returnsi64

The handle, an i64 that names this task and no later one.

writable

Suspend the task until fd takes bytes without blocking, while the executor runs the others. Written only as await writable(fd) inside an async function (NL2671). Refused under --emit-ts (NL4017).

const writable: (fd: i32) => Promise<boolean>
fdi32required

An open descriptor: a socket, a pipe or a terminal.

returnsPromise<boolean>

true once fd is ready; false when the wait could not be made (an fd that is not open). A regular file is always ready.

writableWithin

Suspend the task until fd takes bytes without blocking, or ms milliseconds pass, whichever comes first. Written only as await writableWithin(fd, ms) inside an async function (NL2671). Refused under --emit-ts (NL4018).

const writableWithin: (fd: i32, ms: i32) => Promise<boolean>
fdi32required

An open descriptor: a socket, a pipe or a terminal.

msi32required

The most milliseconds to wait; a negative ms waits without a limit, as writable does.

returnsPromise<boolean>

true once fd is ready; false when ms passed first, when the wait could not be made, or when the task is cancelled.