Runtime
Every task a program spawns runs on a shared asynchronous runtime. Nothing has to be started or configured for it to work: the runtime starts the first time a program awaits something, sizes itself to the machine, and stops when the program ends. This page covers the two things a project can decide about it, how much of the machine it may use, and what its ending means for work still in flight.
Worker Threads
By default the runtime uses one worker thread per logical CPU. A project that wants a different number sets it in tyrus.json:
{
"runtime": {
"workerThreads": 4
}
}The value is baked into the compiled program, so it travels with the binary and does not need tyrus.json next to it at run time. A count below 1 is a build error: the program would have no way to make progress, and rejecting it at build time is better than shipping a binary that cannot run.
The TYRUS_WORKER_THREADS environment variable overrides that value at startup:
TYRUS_WORKER_THREADS=2 ./target/my-projectPrecedence is TYRUS_WORKER_THREADS, then runtime.workerThreads, then one worker per logical CPU. The environment variable wins so a deployment can fit a program to the machine it actually landed on without rebuilding it.
TIP
A value well above the number of logical CPUs the runtime detects is honoured, but reported on stderr. Oversubscribing a machine is occasionally deliberate, so this is a warning about a likely mistake rather than a limit the runtime enforces. A value that is not a positive integer is ignored the same way, with a warning, never fatally.
Shutdown
A program's asynchronous lifetime is main's. When main settles, the runtime stops and every task still pending is cancelled rather than awaited, there is no detached task that outlives the program.
import { sleepAsync, spawn } from "tyrus:task";
async function main(): Promise<void> {
const abandoned = spawn(async (): Promise<void> => {
await sleepAsync(60000);
print("never printed");
});
print("done");
}That program prints done and exits. The spawned task is cancelled where it stood. Run it with TYRUS_REPORT_PENDING_TASKS=1 and the runtime says so on stderr:
tyrus runtime: 1 asynchronous task still pending when `main` finished; cancelled without completingThe way to keep a task alive is to wait for it before returning:
import { sleepAsync, spawn } from "tyrus:task";
async function main(): Promise<void> {
const handle = spawn(async (): Promise<void> => {
await sleepAsync(10);
print("finished");
});
await handle.join();
}TIP
The report is opt-in rather than a default warning, because a correct program can end with pending tasks by design: race and timeout cancel the tasks they did not pick. Turn it on when a task seems not to have run at all, that is almost always a forgotten join. Like every runtime report it goes to stderr, so stdout stays exactly what the program printed.
Loops That Never Yield
A worker thread runs one task at a time. A loop that can neither end nor await keeps its thread for as long as the program lives, and every other task assigned to that thread waits behind it. The compiler warns about the obvious shape (E3032): a loop in an async function whose condition is the literal true and whose body has no await, break, return or throw.
async function main(): Promise<void> {
let total: i32 = 0;
while (true) {
total += 1;
}
}await sleepAsync(0) is enough to hand the thread back once per iteration. A loop with a real condition is left alone, even when it turns out to run forever: a lint that fires on ordinary counting loops is one people turn off.
