@jbrowse/core 4.3.0 → 5.0.0-beta.2

package/esm/util/stopToken.d.ts

@@ -1,19 +1,211 @@
-export type StopToken = string;
-export declare function createStopTokenChecker(stopToken: StopToken | undefined): {
-    time: number;
-    iters: number;
-    stopToken: string | undefined;
-};
+import type { TimeGate } from './timeGate.ts';
+/**
+ * Stop tokens cancel long-running work wherever an RPC method runs — a web
+ * worker, or in-band on the main thread under `MainThreadRpcDriver`.
+ *
+ * Stopping a token records its id locally and posts it to every booted worker,
+ * whose `RpcServer` records it too, so a check is a set lookup — free, exact,
+ * and asking nothing of the deployment. A worker delivers that message whenever
+ * it yields, so this covers any check reached after a *macrotask-yielding*
+ * await; awaiting an already-resolved promise only drains microtasks, which is
+ * the same distinction `abortBreakPoint` in `aborting.ts` exists for.
+ *
+ * A loop that never yields can be interrupted only by something it can read
+ * *synchronously*, which the message path by definition cannot offer. Two
+ * mechanisms cover that, in {@link checkStopTokenThrottled}:
+ *
+ * - an atomic flag in a `SharedArrayBuffer` token, where the page happens to be
+ *   cross-origin isolated. Cheap, but never assume it: SAB needs COOP/COEP on
+ *   the top-level document, which an embeddable library cannot require of its
+ *   host page. **In practice our deployments do not set those headers, so the
+ *   string path below is not the fallback — it is the path.** Judge any
+ *   cancellation bug by what it does to a string token, and don't spend
+ *   complexity optimizing the SAB branch: a lost cancellation that "only"
+ *   affects string tokens affects everybody.
+ * - otherwise a revocable blob URL probed by synchronous XHR, throttled because
+ *   it is expensive (https://yoyo-code.com/how-to-stop-synchronous-web-worker/,
+ *   (c) 2022 Matyáš Racek, MIT).
+ *
+ * **The blob probe was deleted once and had to be restored — don't repeat it.**
+ * `website/scripts/cancel-bench.ts` measured it at zero (median 513 ms settle
+ * either way over a 2000x BAM cancel burst) and that measurement was sound but
+ * scoped: every loop on the alignments path is already chunked by awaits at
+ * region granularity, so there was nothing there for an intra-loop probe to
+ * interrupt. The counter-example is `getLDMatrix.ts`'s O(n²) Float32Array fill —
+ * millions of pair computations with no await anywhere, where this probe is the
+ * only thing that can stop the work, and which that bench never exercises. Any
+ * future attempt to delete this needs a cancel measurement on an
+ * await-free workload (LD or multi-sample-variant), not on a pileup.
+ *
+ * ## Which path runs where
+ *
+ * | realm | isolated? | token | what a non-yielding loop can read |
+ * | --- | --- | --- | --- |
+ * | jbrowse-web / jbrowse.org | no, by decision (ADR-056) | string | stopped-id set + blob probe |
+ * | embedded (`@jbrowse/react-*`) | only if the HOST sets COOP/COEP | string | stopped-id set + blob probe |
+ * | jbrowse-desktop, packaged + dev | no — measured, see the gate | string | stopped-id set + blob probe |
+ * | jest | no | string | stopped-id set only |
+ * | an isolated embedding host | yes | SharedArrayBuffer | atomic read |
+ *
+ * The blob probe is the half that needs a worker (`probeBlobUrl` gates on
+ * `isWebWorker()` and a `blob:` id), which is why jest reads the set alone —
+ * and why a cancellation that only a probe could catch has no test covering it.
+ *
+ * **So nothing we ship mints a `SharedArrayBuffer` token.** The last row is the
+ * whole of the SAB branch's reach: a host page that isolates itself gets the
+ * fast path for free, which is why ADR-056 kept the code and why
+ * `website/scripts/coi-probe.ts` exists to prove it still works. Every SAB arm
+ * below is marked, and each one is dead in every configuration we control.
+ *
+ * Two consequences worth stating, because both have bitten:
+ *
+ * - **Judge every cancellation change by the string path.** A bug that "only"
+ *   affects string tokens affects everybody.
+ * - **Don't spend complexity on the SAB arms** — no caching, no fast paths, no
+ *   cleverness. They are correctness-only, and their cost is that every reader
+ *   of a `StopToken` has to know a token might not be a string.
+ */
+export type StopToken = string | SharedArrayBuffer;
+/**
+ * Narrow an untyped RPC argument to a StopToken, so a caller holding
+ * `Record<string, unknown>` can check one without a cast.
+ */
+export declare function isStopToken(value: unknown): value is StopToken;
+export declare const hasSharedArrayBuffer: boolean;
+/**
+ * Record that a string token has been stopped, and abort any {@link
+ * stopTokenSignal} taken against it. Called locally by {@link stopStopToken},
+ * and in a worker by `RpcServer` when the main thread posts a stopped id.
+ */
+export declare function markStopTokenStopped(id: string): void;
+type StopTokenBroadcaster = (id: string) => void;
+/**
+ * Register a transport that forwards a stopped token's id to wherever the work
+ * is running. Drivers owning a worker pool register at construction and drop it
+ * on destroy; `MainThreadRpcDriver` needs none — its work shares this module
+ * instance and reads `stoppedIds` directly, which is why main-thread RPC gets
+ * exact cancellation without any message at all.
+ */
+export declare function registerStopTokenBroadcaster(fn: StopTokenBroadcaster): () => void;
+/**
+ * Mint a token. **The right-hand branch is the one that runs** — see "Which
+ * path runs where"; `hasSharedArrayBuffer` is false in everything we ship.
+ */
 export declare function createStopToken(): StopToken;
+/**
+ * Stop a token: every check against it now throws, every {@link
+ * stopTokenSignal} taken against it aborts, and workers are told so their
+ * in-flight calls do the same.
+ *
+ * Call it when an operation ends, not only when cancelling one — a completed
+ * fetch's token otherwise pins its signal controllers until the next fetch
+ * supersedes it.
+ */
 export declare function stopStopToken(stopToken?: StopToken): void;
-export declare function checkStopToken(stopToken: StopToken | undefined): void;
-export interface LastStopTokenCheck {
-    time: number;
-    iters: number;
-    backoff?: boolean;
-    checkInterval?: number;
-    checkIters?: number;
+/**
+ * Whether this token has been stopped, without throwing. Prefer {@link
+ * checkStopToken} where an abort should unwind the operation; use this to bail
+ * out cleanly instead of throwing and catching one frame up.
+ */
+export declare function isStopped(stopToken?: StopToken): boolean;
+/**
+ * Throw an AbortError if this token has been stopped. Place at await
+ * boundaries; this costs an atomic load or a set lookup, never a probe.
+ */
+export declare function checkStopToken(stopToken?: StopToken): void;
+/**
+ * Run an awaited stage under a stop token: checked before it starts, and again
+ * once it settles. Prefer this to hand-placing {@link checkStopToken} around an
+ * await — the point is that the check *after* comes with the one before, and the
+ * one after is always the one that gets left out.
+ *
+ * It reads as sufficient to check at the top of an operation, because at the
+ * time you write it the await below is not yet the slow part. `BaseRpcDriver`
+ * checked at entry and then awaited `serializeArguments`, which resolves the
+ * refName map, which downloads the adapter's index — and for an in-memory
+ * adapter the whole file. A stop landing in that window woke a worker anyway.
+ *
+ * {@link updateStatus} and {@link withProgress} in `progress.ts` are this same
+ * shape for a stage that also has something to say on the status channel; reach
+ * for one of those when there is a label, and this when there isn't. What you
+ * should not reach for is a bare `checkStopToken` sprinkled at a boundary you
+ * happened to think of — the periodic in-loop case is
+ * {@link checkStopTokenThrottled}, and it is driven by `createProgressReporter`
+ * for the same reason.
+ *
+ * **Checking twice costs nothing, and it is worth knowing why**, because the
+ * cost of a stop-token check is otherwise easy to remember backwards. The
+ * expensive one is the synchronous XHR blob probe, which runs at up to ~10ms a
+ * call — and it is reached ONLY from {@link checkStopTokenThrottled}, behind a
+ * wall-clock gate with linear backoff, precisely because of that. This path is
+ * {@link isStopped}: an atomic load for a SAB token, a `Map.has` for a string
+ * one. So an extra boundary check here is free, and a per-item one in a tight
+ * loop is not — which is the split the two functions exist to keep.
+ */
+export declare function withStopTokenCheck<T>(stopToken: StopToken | undefined, fn: () => T | Promise<T>): Promise<T>;
+export interface StopTokenSignal {
+    signal: AbortSignal;
+    dispose: () => void;
+}
+/**
+ * An `AbortSignal` wired to a stop token, so a canceled operation drops its
+ * in-flight HTTP reads at the socket instead of downloading them to completion
+ * and discarding the result. Call it where the work runs (worker-side for
+ * worker RPC) and pass `signal` down through `BaseOptions`, which the gmod
+ * readers already forward to `fetch`.
+ *
+ * No polling and no synchronous probe: a string token aborts off the same
+ * posted id the await-boundary check reads, and a SharedArrayBuffer token off
+ * `Atomics.waitAsync`, woken by the `Atomics.notify` in {@link stopStopToken}
+ * — that one lands a turn or two after the notify rather than synchronously
+ * with it, which costs nothing when the point is to stop a download.
+ *
+ * `dispose()` in a `finally` — an undisposed entry pins its controller until
+ * the token is stopped.
+ */
+export declare function stopTokenSignal(stopToken?: StopToken): StopTokenSignal;
+/**
+ * Run `fn` with an `AbortSignal` wired to this stop token, releasing the signal
+ * afterwards however `fn` settles. The shape to reach for at an adapter's read
+ * call — {@link stopTokenSignal} directly is for the rare case that outlives one
+ * awaited call, and it then owns remembering to dispose.
+ */
+export declare function withStopTokenSignal<T>(stopToken: StopToken | undefined, fn: (signal: AbortSignal) => Promise<T>): Promise<T>;
+/**
+ * Detects synchronously whether a string token has been stopped, for use where
+ * no message can be delivered. Returns false when it cannot tell.
+ *
+ * A seam on the checker rather than a bare call, because the production
+ * implementation only works in a worker on a `blob:` token, and is therefore
+ * **inert under jest**. That inertness is not hypothetical: it let a deletion of
+ * this whole mechanism pass all 6000+ unit tests. Overriding
+ * `checker.syncProbe` is how a test asserts the loop consults it at all.
+ */
+export type SyncStopProbe = (stopToken: string) => boolean;
+export interface StopTokenChecker {
     stopToken?: StopToken;
+    sabView?: Int32Array;
+    iters: number;
+    checkInterval: number;
+    checkDue: TimeGate;
+    syncProbe: SyncStopProbe;
 }
-export declare function checkStopToken2(lastCheck?: LastStopTokenCheck): void;
-export declare function forEachWithStopTokenCheck<T>(iter: Iterable<T>, stopToken: StopToken | undefined, arg: (arg: T, idx: number) => void, durationMs?: number, checkIters?: number, backoff?: boolean): void;
+export declare function createStopTokenChecker(stopToken: StopToken | undefined): StopTokenChecker;
+/**
+ * The in-loop counterpart to {@link checkStopToken}, throttled so a
+ * million-iteration loop doesn't pay per item.
+ *
+ * Reads the stopped-id set *and* the synchronous probe, because a loop that
+ * awaits between items can see the first and a loop that never yields can only
+ * see the second. Both are behind the same wall-clock gate, so the per-item cost
+ * is one counter bump.
+ */
+export declare function checkStopTokenThrottled(checker?: StopTokenChecker): void;
+/**
+ * Former name of {@link StopTokenChecker}. Still the primary spelling in several
+ * in-tree RPC argument types (the three variants methods, `WiggleRPC/types.ts`)
+ * as well as in external consumers, so it is a live alias rather than a
+ * deprecation shim — renaming those is a wire-type edit with no behavior in it.
+ */
+export type LastStopTokenCheck = StopTokenChecker;
+export {};