Full observable cancellation signal. Extends CancelCheck with onCancel for listener registration — the mechanism implementations use to abort in-flight Futures mid-wait. Consumers receive one of these and can inspect it or register cleanup actions; they cannot trigger cancellation themselves — the CancelSource.cancel capability stays with the scope owner.
Cancellation is how a Future-returning API becomes abortable at all: Future has no cancel of its own, so the capability has to be passed in.
Register a callback. Fires exactly once — immediately and synchronously on the caller's thread if the token is already cancelled, otherwise on the first CancelSource.cancel.
Register a callback. Fires exactly once — immediately and synchronously on the caller's thread if the token is already cancelled, otherwise on the first CancelSource.cancel.
Listener exception policy: every thrown exception is logged via the source's configured logger and the cancel propagation continues — all listeners run, CancelSource.cancel never throws because of a buggy callback, and the log captures the full cause. This means a bug in one listener is debuggable (it's in the log) without breaking cascading cleanup elsewhere.
The returned Cancellable deregisters the listener from the source's listener list. Matters for long-lived tokens with many short-lived linked children: without deregistration, the parent's listener list would grow unboundedly with stale closures referencing already-cancelled children. CancelSource.linkedTo uses this to clean up after itself on child cancel.