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
import { cancel, isCancelled, sleep, sleepAsync, spawn, channel, joinAll, race, timeout, Mutex, RwLock, Semaphore, JoinHandle, Sender, Receiver } from "tyrus:task";Exported Items
| Item | Signature | Purpose |
|---|---|---|
cancel | <T>(promise: Promise<T>, reason: string, graceMillis?: u64) => boolean | Cooperatively cancels a pending Promise. |
isCancelled | () => boolean | Answers, inside a task, whether it was told to stop. |
sleep | (ms: u64) => void | Blocks 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) => Semaphore | Limits 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.
