1
>
/*---------------------------------------------------------------------------------------------
processor.ts
2
>
* Copyright (c) Microsoft Corporation. All rights reserved.
3
>
* Licensed under the MIT License. See License.txt in the project root for license information.
4
>
*--------------------------------------------------------------------------------------------*/
5
>
6
>
import { CancellationToken } from '../../../common/cancellation.js';
7
>
import { Disposable, DisposableStore, IDisposable } from '../../../common/lifecycle.js';
8
>
import { Embedding, nextMacrotask } from './embedding.js';
9
>
import { TimeApi } from './timeApi.js';
10
>
import { ROOT_TRACE, TraceContext } from './trace.js';
11
>
import { EventSource, VirtualClock, VirtualEvent, VirtualTime } from './virtualClock.js';
12
>
13
>
// ============================================================================
14
>
// Termination policy
15
>
// ============================================================================
16
>
17
>
/**
18
>
* When a {@link Run} should terminate.
19
>
*
20
>
* Greenfield design choice: termination is *always* explicit. There is no
21
>
* "bare run()" that terminates on first empty queue, because that creates a
22
>
* race with the caller's microtask chain (the run can resolve before the
23
>
* caller's `.then` has had a chance to schedule).
24
>
*/
25
>
export type TerminationPolicy =
26
>
/** Resolve as soon as the virtual queue is empty. */
27
>
| { readonly kind: 'idle' }
28
>
/** Resolve when the token is cancelled AND the queue is empty. */
29
>
| { readonly kind: 'token'; readonly token: CancellationToken }
30
>
/** Resolve when virtual time has reached `time` and all events scheduled
31
>
* at or before `time` have been processed. A sentinel event at `time`
32
>
* is scheduled by the processor so virtual time always reaches it. */
33
>
| { readonly kind: 'time'; readonly time: VirtualTime };
34
>
35
>
export const untilIdle: TerminationPolicy = { kind: 'idle' };
36
>
export function untilToken(token: CancellationToken): TerminationPolicy { return { kind: 'token', token }; }
37
>
export function untilTime(time: VirtualTime): TerminationPolicy { return { kind: 'time', time }; }
38
>
39
>
export interface RunOptions {
40
>
readonly until: TerminationPolicy;
41
>
/** Maximum number of virtual events this run will execute. Default: 100. */
42
>
readonly maxEvents?: number;
43
>
/** Maximum causal-trace depth this run will tolerate. Useful for catching
44
>
* runaway self-rescheduling timers. */
45
>
readonly maxTraceDepth?: number;
46
>
}
47
>
48
>
// ============================================================================
49
>
// Run — internal state for a single processor.run() invocation
50
>
// ============================================================================
51
>
52
>
type RunStatus = 'continue' | 'done' | { readonly error: Error };
53
>
54
>
class Run {
55
>
private static _idCounter = 0;
56
>
public readonly id = ++Run._idCounter;
57
>
58
>
public readonly promise: Promise<void>;
59
>
private _resolve!: () => void;
60
>
private _reject!: (e: Error) => void;
61
>
private _settled = false;
62
>
public get settled(): boolean { return this._settled; }
63
>
64
>
constructor(
65
public readonly options: RunOptions,
66
public readonly executedAtStart: number,