Skip to content

Task ​

tyrus:task provides cooperative cancellation, non-blocking delays, concurrent task spawning, typed channels between tasks, combinators for composing multiple tasks together, a mutex for protecting a value shared between tasks, a reader-writer lock for allowing multiple concurrent readers, and a semaphore for limiting concurrent access to a region of code.

Imports ​

Importsimport { cancel, isCancelled, sleep, sleepAsync, spawn, channel, joinAll, race, timeout, Mutex, RwLock, Semaphore, JoinHandle, Sender, Receiver } from "tyrus:task";

Exported Items ​

ItemSignaturePurpose
cancel<T>(promise: Promise<T>, reason: string, graceMillis?: u64) => booleanCooperatively cancels a pending Promise.
isCancelled() => booleanAnswers, inside a task, whether it was told to stop.
sleep(ms: u64) => voidBlocks the current thread for a delay.
sleepAsync(ms: u64) => Promise<void>Settles after a delay without blocking an executor thread.
spawn<T>(task: () => Promise<T>) => JoinHandle<T>Runs an async task concurrently and returns a handle to it.
channel<T>(capacity?: usize) => [Sender<T>, Receiver<T>]Creates a typed channel between concurrent tasks.
joinAll<T>(handles: JoinHandle<T>[]) => Promise<T[]>Waits for every handle in an array to settle.
race<T>(handles: JoinHandle<T>[]) => Promise<T>Resolves with whichever handle settles first, cancelling the rest.
timeout<T>(ms: u64, task: Promise<T>) => Promise<T>Bounds how long a Promise is allowed to take.
Mutex<T>(value: T) => Mutex<T>Protects exclusive access to a value shared between tasks.
RwLock<T>(value: T) => RwLock<T>Allows multiple concurrent readers or one exclusive writer over a shared value.
Semaphore(permits: usize) => SemaphoreLimits how many tasks enter a region of code at the same time.

JoinHandle<T>, the handle spawn returns, and Sender<T>/Receiver<T>, the pair channel returns, are exported by tyrus:task: a binding whose type is only inferred needs no import, but naming one of them in an annotation requires importing it, as in import { Sender, channel } from "tyrus:task";. Promise<T> is a native type and never needs to be imported. MutexGuard<T>, Mutex<T>.lock()/.tryLock()'s own return type, RwReadGuard<T>/RwWriteGuard<T>, RwLock<T>'s own guard types, and SemaphorePermit, Semaphore.acquire()/.tryAcquire()'s own return type, are native types too.

The Runtime ​

Every item here runs on a shared asynchronous runtime that needs no setup. Runtime covers what a project can decide about it: how many worker threads it may use, and what happens to a task still pending when main finishes.

Tasks and Promises ​

Promise.* and tyrus:task.* share four names and are not interchangeable. Tasks and Promises covers which to reach for, and why tyrus:task.race cancels the losers while Promise.race does not.