Documentation channel: current development main at compiler checkpoint 1d7e15e. The latest tagged release is v0.0.3; pages identify APIs that are not yet released.

Cancellation

Release status: Unreleased. This page documents the unified cancellation API at compiler checkpoint 1d7e15e; it is not part of the published v0.0.3 contract.

Cancellation is cooperative and subsystem-neutral. A source requests cancellation, while any number of copied tokens observe the same shared state. Process pipes, pseudo-terminals, HTTP operations, and application code use this one token type rather than defining per-subsystem cancellation objects.

API

cancellation_source source;
cancellation_token token := source.token();

bool requested := token.cancelled();
token.wait();
token.throw_if_cancelled(); // CancellationError

source.cancel();

cancelled() is a non-blocking observation. wait() sleeps without busy-spinning until cancellation is requested. throw_if_cancelled() returns normally before cancellation and otherwise raises the checked CancellationError with message operation cancelled.

Ownership and concurrency

Sources and tokens are cheap, copyable handles over reference-counted shared state. Every source copy can call cancel(); tokens can only observe. Destroying a source does not cancel, and tokens remain valid after all sources are destroyed. Cancellation is one-way, thread-safe, and idempotent: concurrent or repeated calls to cancel() produce the same terminal state and wake all waiters.

There is no reset operation, implicit process-global token, or thread-local current token. Pass a token explicitly to an operation that supports cancellation, or capture it in application work and check it at suitable cooperative boundaries.

Bound operations

Native facilities copy the token when an operation is created. Their public read, write, and wait methods do not take another token. A token passed to process wakes blocked process-pipe I/O with ExecError("process I/O cancelled", 125); it does not terminate or wait for the child. A token passed to pty_spawn also cancels blocked PTY I/O and PTY wait(), but does not signal the child. HTTP APIs retain their documented subsystem error type when cancellation is observed.

A token that is already cancelled fails before cancellable I/O begins. Native completion already observed in the same wake cycle wins over cancellation. Cancellation requests observation; it is not a timeout, EOF, peer close, process signal, or resource cleanup operation.

Lifetime producers

Runtime-owned lifetimes use the same token type. For example, each dispatched HTTP request has a fresh read-only request.cancellation token, cancelled when that request lifetime ends. Passing it to process or pty_spawn links blocked I/O to the request lifetime without granting the handler cancellation authority.