refactor(codemode): run every job on the machine and drive it from a thin Effect loop

The machine now owns the scheduler: job queue, inbox, parked awaits, unhandled
rejections, and promise operations. An await cuts the stack at the innermost
async boundary (the program's frame or an async function's call frame) and
parks the frames on the promise as data. Host calls are HostCall records the
machine hands to the driver at its stops; blocking host work is a blocking
HostCall. The generator evaluator, runner.ts, and CODEMODE_EVALUATOR are gone.
This commit is contained in:
James Long
2026-11-04 21:10:43 +00:00
Unverified
parent 1dd74883d6
commit ad4fd72c55
35 changed files with 1476 additions and 2797 deletions
+1 -2
View File
@@ -24,8 +24,7 @@
"pack": "bun run script/pack.ts",
"typecheck": "bun check --no-script",
"typecheck:tsc": "tsc --noEmit",
"test": "bun test && bun run test:machine",
"test:machine": "CODEMODE_EVALUATOR=machine bun test"
"test": "bun test"
},
"dependencies": {
"acorn": "8.15.0",
+2 -2
View File
@@ -21,7 +21,7 @@ import {
HeadersObj,
} from "./interpreter/objects.js"
import { typeofValue } from "./interpreter/references.js"
import { type Eval, Slice } from "./interpreter/runner.js"
import { type Eval, Slice } from "./interpreter/signals.js"
export type Json = Schema.Json
@@ -50,7 +50,7 @@ const walk = <R>(
const stack = new Set<object>()
const visit = function* (holder: Obj, key: string, depth: number): Eval<Json | undefined> {
// Shared references expand into a tree, so the work is not bounded by the value's size or depth.
if (ctx.runner.tick()) yield Slice
if (ctx.machine.tick()) yield Slice
if (depth > MAX_VALUE_DEPTH) throw rangeError(`Value exceeds the maximum depth of ${MAX_VALUE_DEPTH}.`)
const raw = get(holder, key)
if (raw instanceof PromiseObj && !boundary) {
+378
View File
@@ -0,0 +1,378 @@
import type { Expression } from "acorn"
import { ToolReference } from "../tool-runtime.js"
import { locate } from "./errors.js"
import type { Interpreter } from "./interpreter.js"
import type { Builtins } from "./intrinsics.js"
import { type AstNode, AsyncIteratorSymbol, GeneratorReturn, IteratorSymbol, Throw, typeError } from "./model.js"
import { native } from "./native.js"
import {
Builtin,
type Cursor,
define,
Fn,
get,
hidden,
IteratorObj,
iteratorResult,
type NativeCall,
type NativeResult,
Obj,
type PromiseObj,
type Step,
type Value,
} from "./objects.js"
import {
builtinCursor,
type CustomIterator,
notAFunction,
requireIteratorMethod,
requireIteratorObject,
} from "./operations.js"
import { capability } from "./promises.js"
import { describeValue } from "./references.js"
import {
Await,
type Eval,
type GeneratorRequest,
Interruption,
Invoke,
isEval,
normal,
Slice,
Yield,
} from "./signals.js"
/**
* Interpreter work for the built-ins that still run as host generators in native frames: calls into the program,
* iterating, `yield*`, and the async-from-sync iterator adapter. A program function it calls is an `Invoke` the
* machine runs on its own stack.
*
* Phase 2c moves `yield*` and the async-from-sync adapter onto machine frames, and phase 3 replaces the built-ins that
* call program code with the prelude, after which this goes away.
*/
export class Bridge<R> {
constructor(private readonly ctx: Interpreter<R>) {}
/** Await: suspends the innermost async body until `value` settles. */
*awaitValue(value: Value, node?: AstNode): Eval<Value> {
return (yield new Await(value, node)) as Value
}
*call(callable: Value, thisValue: Value, args: Array<Value>, node?: AstNode, callee?: Expression): Eval<Value> {
const result = this.dispatch(callable, thisValue, args, node, callee)
if (isEval(result)) return yield* result
return result instanceof Invoke ? ((yield result) as Value) : result
}
// The single dispatch for every call a built-in makes. A program function is an `Invoke` for the machine to run on
// its stack; a built-in that returns a value needs no generator.
private dispatch(
callable: Value,
thisValue: Value,
args: Array<Value>,
node?: AstNode,
callee?: Expression,
): Value | Eval<Value> | Invoke {
if (callable instanceof Fn) return new Invoke(callable, thisValue, args, node)
if (callable instanceof Builtin) {
const ctx = this.ctx
// A loop made only of built-in calls has no program call or loop back-edge to count, so count the call.
if (ctx.machine.tick())
return afterSlice(() => this.native(() => callable.invoke(ctx, thisValue, args, node), node))
return this.native(() => callable.invoke(ctx, thisValue, args, node), node)
}
if (callable instanceof ToolReference) {
if (callable.path.length === 0) {
throw typeError("The tools root is not callable.", callee ?? node)
}
return this.ctx.toolCall(callable.path, args, node)
}
throw notAFunction(callee, node)
}
// Built-ins throw without a location, synchronously or inside their work; the call site supplies it.
private native(body: () => NativeResult, node?: AstNode): Value | Eval<Value> {
let result: NativeResult
try {
result = body()
} catch (error) {
throw locate(error, node)
}
return isEval(result) ? located(result, node) : result
}
// CreateAsyncFromSyncIterator: an async iterator over a synchronous one. Each `next()` promise settles a job after
// the value does, and a rejected value closes the synchronous iterator first; `return()` calls the synchronous
// iterator's own `return`, or settles at once when it has none.
asyncFromSync(
builtin: Cursor | undefined,
custom: CustomIterator | undefined,
node: AstNode | undefined,
): CustomIterator {
const ctx = this.ctx
const machine = ctx.machine
const builtins = ctx.builtins
const result = (value: Value, done: boolean) => iteratorResult(builtins.Object, value, done)
const self = this
// IteratorNext passes the value `next` received, when it received one.
const syncNext = function* (args: Array<Value>): Eval<Step> {
if (!custom) return yield* builtin!.next()
const object = requireIteratorObject(
yield* self.call(custom.next, custom.iterator, args, node),
"Iterator next() result",
node,
)
return { done: Boolean(get(object, "done")), value: get(object, "value") }
}
// The synchronous iterator's `return`, looked up when it is needed; built-in collection iterators have none.
const syncReturn = (): Value => (custom ? get(custom.iterator, "return") : undefined)
const settle = (step: Step, closeOnRejection: boolean, made: ReturnType<typeof capability>) => {
const rejected = (reason: unknown) => {
if (step.done || !closeOnRejection || reason instanceof Interruption) return made.reject(reason)
const body = function* (): Eval<void> {
try {
if (custom) yield* self.closeIterator(custom, node)
else yield* builtin!.close()
} catch {
// The rejection wins over a failing close.
}
made.reject(reason)
}
return body()
}
let wrapper: PromiseObj
try {
wrapper = machine.promiseResolve(step.value)
} catch (error) {
const body = rejected(error)
if (body !== undefined)
machine.enqueue({ kind: "resume", frames: [machine.job(body)], input: normal(undefined) })
return
}
machine.then(wrapper, {
kind: "callback",
run: (settled) =>
settled.ok ? made.resolve(result(settled.value as Value, step.done)) : rejected(settled.error),
})
}
const next = asyncFromSyncMethod(builtins, "next", function* (_, args) {
const made = capability(ctx, node)
try {
settle(yield* syncNext(args), true, made)
} catch (error) {
made.reject(error)
}
return made.promise
})
const close = asyncFromSyncMethod(builtins, "return", function* (_, args) {
const made = capability(ctx, node)
try {
const method = syncReturn()
if (method === undefined || method === null) {
if (builtin !== undefined) yield* builtin.close()
made.resolve(result(args[0], true))
return made.promise
}
const returned = requireIteratorObject(
yield* self.call(requireIteratorMethod(method, "Iterator return", node), custom!.iterator, args, node),
"Iterator return() result",
node,
)
settle({ done: Boolean(get(returned, "done")), value: get(returned, "value") }, false, made)
} catch (error) {
made.reject(error)
}
return made.promise
})
const raise = asyncFromSyncMethod(builtins, "throw", function* (_, args) {
const made = capability(ctx, node)
try {
const method = custom ? get(custom.iterator, "throw") : undefined
if (method === undefined || method === null) {
if (custom) yield* self.closeIterator(custom, node)
else yield* builtin!.close()
made.reject(typeError("The delegated iterator does not provide a throw() method.", node))
return made.promise
}
const thrown = requireIteratorObject(
yield* self.call(requireIteratorMethod(method, "Iterator throw", node), custom!.iterator, args, node),
"Iterator throw() result",
node,
)
settle({ done: Boolean(get(thrown, "done")), value: get(thrown, "value") }, true, made)
} catch (error) {
made.reject(error)
}
return made.promise
})
const adapter = new Obj(builtins.Object)
define(adapter, "next", next, hidden)
define(adapter, "return", close, hidden)
define(adapter, "throw", raise, hidden)
return { iterator: adapter, next, asynchronous: true }
}
*iterate(value: Value, node?: AstNode): Eval<Cursor | undefined> {
const cursor = builtinCursor(this.ctx.builtins, value)
if (cursor !== undefined) return cursor
const iterator = yield* this.customIterator(value, node, false)
return iterator === undefined ? undefined : this.customCursor(iterator, node)
}
/** GetIteratorDirect: drive an iterator by its own `next`, without asking for `[Symbol.iterator]`. */
iterateDirect(value: Value, node?: AstNode): Cursor {
if (value instanceof IteratorObj) return value.cursor
if (!(value instanceof Obj)) {
throw typeError(`An iterator must be an object, received ${describeValue(value)}.`, node)
}
return this.customCursor(
{
iterator: value,
next: requireIteratorMethod(get(value, "next"), "Iterator next", node),
asynchronous: false,
},
node,
)
}
private customCursor(iterator: CustomIterator, node: AstNode | undefined): Cursor {
return {
next: () => this.nextIteratorResult(iterator, node),
close: () => this.closeIterator(iterator, node),
}
}
private *customIterator(
value: Value,
node: AstNode | undefined,
allowAsync = true,
): Eval<CustomIterator | undefined> {
if (!(value instanceof Obj)) return undefined
const asyncMethod = allowAsync ? get(value, AsyncIteratorSymbol) : undefined
const method = asyncMethod ?? get(value, IteratorSymbol)
if (method === undefined || method === null) return undefined
const iterator = yield* this.call(requireIteratorMethod(method, "Iterator method", node), value, [], node)
const object = requireIteratorObject(iterator, "Iterator method result", node)
return {
iterator: object,
next: requireIteratorMethod(get(object, "next"), "Iterator next", node),
asynchronous: asyncMethod !== undefined && asyncMethod !== null,
}
}
private *nextIteratorResult(iterator: CustomIterator, node: AstNode | undefined): Eval<Step> {
const called = yield* this.call(iterator.next, iterator.iterator, [], node)
const object = requireIteratorObject(
iterator.asynchronous ? yield* this.awaitValue(called, node) : called,
"Iterator next() result",
node,
)
return { done: Boolean(get(object, "done")), value: get(object, "value") }
}
private *closeIterator(iterator: CustomIterator, node: AstNode | undefined): Eval<void> {
const close = get(iterator.iterator, "return")
if (close === undefined || close === null) return
const method = requireIteratorMethod(close, "Iterator return", node)
const called = yield* this.call(method, iterator.iterator, [], node)
requireIteratorObject(
iterator.asynchronous ? yield* this.awaitValue(called, node) : called,
"Iterator return() result",
node,
)
}
// Yield `value` and continue with the request that resumes the body: `next` supplies the value of the `yield`,
// `throw` throws there, and `return` unwinds through `finally` blocks (an async generator awaits the value first).
private *suspendGenerator(value: Value, asynchronous: boolean): Eval<Value> {
const request = (yield new Yield(value)) as GeneratorRequest
if (request.kind === "next") return request.value
if (request.kind === "throw") throw new Throw(request.value)
throw new GeneratorReturn(asynchronous ? yield* this.awaitValue(request.value) : request.value)
}
*delegateYield(value: Value, node: AstNode, asynchronous: boolean): Eval<Value> {
const builtin = builtinCursor(this.ctx.builtins, value)
if (builtin !== undefined && !asynchronous) {
while (true) {
const step = yield* builtin.next()
if (step.done) return undefined
try {
yield* this.suspendGenerator(step.value, asynchronous)
} catch (error) {
if (error instanceof GeneratorReturn) {
yield* builtin.close()
throw error
}
if (error instanceof Throw) {
yield* builtin.close()
throw typeError("The delegated iterator does not provide a throw() method.", node)
}
throw error
}
}
}
const custom = builtin === undefined ? yield* this.customIterator(value, node, asynchronous) : undefined
if (builtin === undefined && !custom) throw typeError("yield* requires a compatible iterable value.", node)
// An async generator delegates to a synchronous iterator through CreateAsyncFromSyncIterator, as JS does.
const iterator = asynchronous && !custom?.asynchronous ? this.asyncFromSync(builtin, custom, node) : custom!
let kind: GeneratorRequest["kind"] = "next"
let input: Value = undefined
while (true) {
const method = kind === "next" ? iterator.next : get(iterator.iterator, kind)
if (method === undefined || method === null) {
if (kind === "return") throw new GeneratorReturn(asynchronous ? yield* this.awaitValue(input, node) : input)
yield* this.closeIterator(iterator, node)
throw typeError("The delegated iterator does not provide a throw() method.", node)
}
const called = yield* this.call(
requireIteratorMethod(method, `Iterator ${kind}`, node),
iterator.iterator,
[input],
node,
)
const result = requireIteratorObject(
iterator.asynchronous ? yield* this.awaitValue(called, node) : called,
`Iterator ${kind}() result`,
node,
)
const done = Boolean(get(result, "done"))
const resultValue = get(result, "value")
if (done) {
if (kind === "return") throw new GeneratorReturn(resultValue)
return resultValue
}
try {
// Delegated values are yielded as they are; an async generator's inner promise already settled them.
input = yield* this.suspendGenerator(resultValue, asynchronous)
kind = "next"
} catch (error) {
if (!(error instanceof GeneratorReturn) && !(error instanceof Throw)) throw error
kind = error instanceof GeneratorReturn ? "return" : "throw"
input = error.value
}
}
}
}
// The async-from-sync adapter still keeps its iterator in host closures, so its methods are made per iteration.
const asyncFromSyncMethod = (builtins: Builtins, name: string, call: NativeCall) =>
native(builtins, { name, length: 1, call, runtime: "async-from-sync" })
// Finishes a built-in's work, locating a failure at the call that started it.
function* located(work: Eval<Value>, node: AstNode | undefined): Eval<Value> {
try {
return yield* work
} catch (error) {
throw locate(error, node)
}
}
// Lets the host run first, then starts the work.
function* afterSlice(start: () => Value | Eval<Value>): Eval<Value> {
yield Slice
const result = start()
return isEval(result) ? yield* result : result
}
@@ -14,7 +14,7 @@ import {
type Value,
} from "./objects.js"
import { isOpaque, typeofValue } from "./references.js"
import { type Eval, Interruption, isEval } from "./runner.js"
import { type Eval, Interruption, isEval } from "./signals.js"
/** IteratorClose: a consumer failure closes the iterator and wins over any close failure, except that a generator's
* return() is a return completion, so a failing close wins over it, as after `break`. */
+128
View File
@@ -0,0 +1,128 @@
import { Cause, type Context, Effect, Exit, Fiber } from "effect"
import type { Machine } from "../machine/machine.js"
import type { HostCall } from "../machine/scheduler.js"
import type { ToolRuntime } from "../tool-runtime.js"
import { locate } from "./errors.js"
import { PendingThrow } from "./model.js"
import { abrupt, type Completion, Interruption, normal } from "./signals.js"
/**
* Runs a machine in Effect: the only place program execution meets the host. It calls `machine.run` until the program
* ends, and does what each stop asks: yields to the Effect scheduler for a slice, and starts the host calls the machine
* queued, as fibers with the caller's services, reporting each outcome back with `machine.complete`. Fibers live only
* here, by host call id, and never become part of the machine's state.
*/
export class Driver<R> {
private readonly fibers = new Map<number, Fiber.Fiber<unknown, unknown>>()
private wake: (() => void) | undefined
private stopping = false
constructor(
private readonly machine: Machine,
private readonly tools: ToolRuntime<R>,
/** The services host work runs with: the caller's, so tools see its context, tracing, and clock. */
private readonly services: Context.Context<R>,
) {}
/**
* Runs the machine until the program's body completes, then returns how it ended. Host work it started may still be
* running; `interrupt` stops it. Host work interrupted on its own that reaches the program's body, or blocking host
* work that is interrupted, interrupts the execution.
*/
run(): Effect.Effect<Completion, unknown, R> {
const self = this
const machine = this.machine
return Effect.gen(function* () {
while (true) {
const stop = machine.run()
if (stop.kind === "slice") {
yield* Effect.yieldNow
continue
}
if (stop.kind === "host") {
if (stop.calls.length === 0) {
yield* self.settled
continue
}
for (const call of stop.calls) {
if (!call.blocking) {
self.start(call)
continue
}
const exit = yield* Effect.exit(self.work(call))
if (Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)) return yield* Effect.failCause(exit.cause)
machine.complete(call.id, Exit.isSuccess(exit) ? normal(exit.value) : abrupt(Cause.squash(exit.cause)))
}
continue
}
if (stop.kind === "stuck") {
return abrupt(
new PendingThrow(
"Error",
"The program is waiting on a promise that can never settle: nothing else is running, so nothing can resolve it. Code Mode has no timers or sleep, so don't wait or poll inside a program.",
stop.node,
),
)
}
const outcome = stop.completion
if (!outcome.ok && outcome.error instanceof Interruption) return yield* Effect.failCause(outcome.error.cause)
return outcome
}
})
}
/** Stops host work still running, waiting for its cleanup. */
interrupt(): Effect.Effect<void> {
const self = this
return Effect.gen(function* () {
self.stopping = true
while (self.fibers.size > 0) yield* Fiber.interruptAll([...self.fibers.values()])
})
}
private work(call: HostCall): Effect.Effect<unknown, unknown, R> {
const request = call.request
if (request.kind === "tool") return this.tools.execute(request.path, request.args)
if (request.kind === "search") return this.tools.search(request.args)
// An extension's work, made by the extension bridge with the program's services in its requirements.
return request.effect as Effect.Effect<unknown, unknown, R>
}
// Starts concurrent host work now; its outcome goes back to the machine's inbox, in completion order.
private start(call: HostCall): void {
// Starts synchronously, so admission and hooks happen before the machine runs another job.
const fiber = Effect.runForkWith(this.services)(this.work(call))
this.fibers.set(call.id, fiber)
fiber.addObserver((exit) => {
this.fibers.delete(call.id)
// Interrupted by the program ending: nothing is left to settle.
if (this.stopping) return
this.machine.complete(
call.id,
Exit.isSuccess(exit)
? normal(exit.value)
: abrupt(
Cause.hasInterruptsOnly(exit.cause)
? new Interruption(exit.cause)
: Cause.hasDies(exit.cause)
? locate(Cause.squash(exit.cause), call.site)
: Cause.squash(exit.cause),
),
)
this.wake?.()
})
}
private get settled(): Effect.Effect<void> {
return Effect.callback<void>((resume) => {
if (this.machine.ready) return resume(Effect.void)
this.wake = () => {
this.wake = undefined
resume(Effect.void)
}
return Effect.sync(() => {
this.wake = undefined
})
})
}
}
+1 -1
View File
@@ -19,7 +19,7 @@ import {
type Value,
} from "./objects.js"
import type { Interpreter } from "./interpreter.js"
import type { Eval } from "./runner.js"
import type { Eval } from "./signals.js"
import { toPrimitiveString } from "./callback.js"
import { formatValue } from "../stdlib/console.js"
+13 -15
View File
@@ -7,9 +7,9 @@ import { createBuiltins } from "./intrinsics.js"
import { Interpreter } from "./interpreter.js"
import type { Value } from "./objects.js"
import { formatLocation, sourceLocation } from "./model.js"
import type { Runner } from "./runner.js"
import { Driver } from "./driver.js"
import type { Machine } from "../machine/machine.js"
import { Source } from "./source.js"
import type { Evaluator } from "../machine/machine.js"
export const executeProgram = <R>(
code: string,
@@ -33,24 +33,25 @@ export const executeProgram = <R>(
const logs: Array<string> = []
const logged = () => (logs.length > 0 ? { logs: [...logs] } : {})
// Set only after copy-out so timeouts cannot report invalid values as completed.
let returned: { value: DataValue; runner: Runner<R> } | undefined
let runner: Runner<R> | undefined
let returned: { value: DataValue; machine: Machine } | undefined
let driver: Driver<R> | undefined
const base = Effect.gen(function* () {
const parsed = parseProgram(code)
if (!parsed.ok) return { ok: false, error: parsed.error, toolCalls: [] } satisfies Result
const services = yield* Effect.context<R>()
const ctx = new Interpreter<R>({ tools, services, builtins, logs, globals, evaluator: evaluator() })
runner = ctx.runner
const outcome = yield* runner.run(ctx.main(parsed.source))
const ctx = new Interpreter<R>({ tools, builtins, logs, globals })
ctx.start(parsed.source)
driver = new Driver(ctx.machine, tools, services)
const outcome = yield* driver.run()
if (!outcome.ok) {
return { ok: false, error: normalizeError(outcome.error), ...logged(), toolCalls: tools.calls } satisfies Result
}
const result = (outcome.value as DataValue | undefined) ?? null
returned = { value: result, runner }
returned = { value: result, machine: ctx.machine }
// Host work the program left running is interrupted, not awaited.
yield* runner.interrupt()
const warnings = runner.diagnostics()
yield* driver.interrupt()
const warnings = ctx.machine.diagnostics()
return {
ok: true,
value: result,
@@ -58,7 +59,7 @@ export const executeProgram = <R>(
...logged(),
toolCalls: tools.calls,
} satisfies Result
}).pipe(Effect.ensuring(Effect.suspend(() => runner?.interrupt() ?? Effect.void)))
}).pipe(Effect.ensuring(Effect.suspend(() => driver?.interrupt() ?? Effect.void)))
const timeoutMs = limits.timeoutMs
const operation =
timeoutMs === undefined
@@ -85,7 +86,7 @@ export const executeProgram = <R>(
kind: "TimeoutExceeded",
message: `The program returned, but background work was still running at the ${timeoutMs}ms timeout and was interrupted. Await all started promises.`,
},
...returned.runner.diagnostics(),
...returned.machine.diagnostics(),
],
...logged(),
toolCalls: tools.calls,
@@ -112,9 +113,6 @@ export const executeProgram = <R>(
})
}
// Internal while the machine evaluator is ported: `CODEMODE_EVALUATOR=machine` runs programs on it.
const evaluator = (): Evaluator => (process.env.CODEMODE_EVALUATOR === "machine" ? "machine" : "legacy")
export const parseProgram = (
code: string,
): { ok: true; program: Program; source: Source } | { ok: false; error: Diagnostic } => {
@@ -28,6 +28,7 @@ import {
type Value,
} from "./objects.js"
import { describeValue, isOpaque } from "./references.js"
import { Host } from "./signals.js"
/**
* The global bindings of one run's extensions. Everything crossing the boundary is converted: plain data and built-in
@@ -184,18 +185,18 @@ export const extensionGlobals = <R>(
label,
site,
)
if (before) yield ctx.runner.blocking(before)
if (before) yield new Host({ kind: "effect", effect: before })
const host = callHost<R>(value, args)
if (host.async) return pending(settle(host.effect), label, site)
return (yield ctx.runner.blocking(settle(host.effect))) as Value
return (yield new Host({ kind: "effect", effect: settle(host.effect) })) as Value
},
})
}
// An asynchronous host call: the program holds a promise that settles when the host's work does.
const pending = (work: Effect.Effect<Value, Throw, R>, label: string, site: AstNode | undefined) => {
const resolving = ctx.runner.resolving(ctx.runner.newPromise(), site)
ctx.runner.host(work, { label, result: "value", resolving, site })
const resolving = ctx.machine.resolving(ctx.machine.newPromise(), site)
ctx.machine.host({ kind: "effect", effect: work }, { label, result: "value", resolving, site })
return resolving.promise
}
+18 -19
View File
@@ -5,13 +5,14 @@ import type { Interpreter } from "./interpreter.js"
import {
abrupt,
type Boundary,
Call,
type Completion,
Enter,
type Entry,
type Eval,
type GeneratorRequest,
normal,
} from "./runner.js"
} from "./signals.js"
import type { Frame } from "../machine/frame.js"
/** `next`/`return`/`throw` on the generator prototypes; async generators answer with promises. */
export const generatorGlobals = <R>(ctx: Interpreter<R>): void => {
@@ -49,17 +50,15 @@ export const generatorGlobals = <R>(ctx: Interpreter<R>): void => {
const result = <R>(ctx: Interpreter<R>, value: Value, done: boolean) => iteratorResult(ctx.builtins.Object, value, done)
// Puts the suspended body back on the stack and continues it with `request`; the boundary answers the caller when
// the body next yields or ends.
const resume = <R>(ctx: Interpreter<R>, generator: GeneratorObj, request: GeneratorRequest): Enter => {
// Starts the body behind its boundary, or puts the suspended body's frames back on the stack and continues it with
// `request`; the boundary answers the caller when the body next yields or ends.
const resume = <R>(ctx: Interpreter<R>, generator: GeneratorObj, request: GeneratorRequest): Call | Enter => {
const started = generator.state !== "suspendedStart"
generator.state = "executing"
if (!started) {
return new Enter([{ body: generator.body, boundary: new GeneratorBoundary(ctx, generator) }], normal(undefined))
}
const entries = generator.entries!
generator.entries = undefined
return new Enter(entries, normal(request))
if (!started) return new Call(generator.body, new GeneratorBoundary(ctx, generator))
const frames = generator.frames!
generator.frames = undefined
return new Enter(frames, normal(request))
}
// A synchronous generator step: the body runs on the caller's stack until it yields, returns, or throws.
@@ -76,9 +75,9 @@ function* step<R>(ctx: Interpreter<R>, generator: GeneratorObj, kind: GeneratorR
// AsyncGenerator.prototype.next/return/throw: queue the request with its promise, and run the body now if it is
// waiting for one. A request that arrives while the body runs is answered when the body reaches it.
function* request<R>(ctx: Interpreter<R>, thisValue: Value, kind: GeneratorRequestKind, value: Value): Eval<Value> {
const runner = ctx.runner
const promise = runner.newPromise()
const resolving = runner.resolving(promise)
const machine = ctx.machine
const promise = machine.newPromise()
const resolving = machine.resolving(promise)
if (!(thisValue instanceof GeneratorObj) || !thisValue.asynchronous) {
resolving.reject(typeError(`AsyncGenerator.prototype.${kind} called on incompatible receiver.`))
return promise
@@ -138,9 +137,9 @@ const drainQueue = <R>(ctx: Interpreter<R>, generator: GeneratorObj) => {
// AsyncGeneratorAwaitReturn: a `return(value)` on an ended or unstarted generator settles once `value` does.
const awaitReturn = <R>(ctx: Interpreter<R>, generator: GeneratorObj) => {
const runner = ctx.runner
const machine = ctx.machine
try {
runner.then(runner.promiseResolve(generator.queue[0]!.request.value), { kind: "awaitReturn", generator })
machine.then(machine.promiseResolve(generator.queue[0]!.request.value), { kind: "awaitReturn", generator })
} catch (error) {
finishAwaitReturn(ctx, generator, abrupt(error))
}
@@ -179,10 +178,10 @@ class GeneratorBoundary<R> implements Boundary {
return normal(undefined)
}
yielded(value: Value, split: () => Array<Entry>): Completion {
yielded(value: Value, split: () => Array<Frame>): Completion {
const generator = this.target
if (!generator.asynchronous) {
generator.entries = split()
generator.frames = split()
generator.state = "suspendedYield"
return normal(result(this.ctx, value, false))
}
@@ -190,7 +189,7 @@ class GeneratorBoundary<R> implements Boundary {
completeStep(this.ctx, generator, normal(value), false)
const next = generator.queue[0]
if (next !== undefined) return normal(next.request)
generator.entries = split()
generator.frames = split()
generator.state = "suspendedYield"
return normal(undefined)
}
File diff suppressed because it is too large Load Diff
+5 -3
View File
@@ -12,7 +12,9 @@ import {
Throw,
typeError,
} from "./model.js"
import type { Entry, Eval, GeneratorRequest, Reaction, Resolving } from "./runner.js"
import type { Eval, GeneratorRequest } from "./signals.js"
import type { Frame } from "../machine/frame.js"
import type { Reaction, Resolving } from "../machine/scheduler.js"
import { OrderedTable, type TableCursor } from "./table.js"
/** Property attributes, as in a JS property descriptor. */
@@ -347,8 +349,8 @@ export type GeneratorState =
export class GeneratorObj extends Opaque {
override readonly tag = "Generator"
state: GeneratorState = "suspendedStart"
/** The suspended body's activations, kept while it waits for the next request. */
entries: Array<Entry> | undefined
/** The suspended body's frames, kept while it waits for the next request. */
frames: Array<Frame> | undefined
/** An async generator's requests, oldest first, each with the functions that settle its promise. */
readonly queue: Array<{ readonly request: GeneratorRequest; readonly resolving: Resolving }> = []
constructor(
+49 -33
View File
@@ -5,17 +5,8 @@ import { createAggregateErrorValue, materialize } from "./errors.js"
import { describeValue, typeofValue } from "./references.js"
import { isSupportedCallback } from "./callback.js"
import type { Interpreter } from "./interpreter.js"
import {
type Combination,
type Completion,
type Eval,
Interruption,
normal,
type Reaction,
type Resolving,
type Start,
Task,
} from "./runner.js"
import { type Completion, type Eval, Interruption } from "./signals.js"
import type { Combination, Reaction, Resolving } from "../machine/scheduler.js"
import { finishAwaitReturn } from "./generators.js"
// A `resolve`/`reject` handed to an executor or thenable: calling it settles the capability.
@@ -29,18 +20,18 @@ const resolvingFunctions = <R>(ctx: Interpreter<R>, resolving: Resolving) => ({
* it is located at `site`, the call that created it.
*/
export const capability = <R>(ctx: Interpreter<R>, site: AstNode | undefined): Resolving =>
ctx.runner.resolving(ctx.runner.newPromise(), site)
ctx.machine.resolving(ctx.machine.newPromise(), site)
/** Settles `resolving` with a completion: a fulfillment value is resolved, so a thenable is adopted. */
const settleWith = (resolving: Resolving, completion: Completion) =>
completion.ok ? resolving.resolve(completion.value as Value) : resolving.reject(completion.error)
/** Runs a settled promise's reaction as a job: it finishes at once, or returns the task that calls program code. */
/** Runs a settled promise's reaction as a job: it finishes at once, or returns the work that calls program code. */
export const react = <R>(
ctx: Interpreter<R>,
reaction: Exclude<Reaction, { readonly kind: "await" }>,
settled: Completion,
): Start | void => {
): Eval<void> | void => {
switch (reaction.kind) {
case "settle":
return settleWith(reaction.target, settled)
@@ -61,8 +52,33 @@ export const react = <R>(
}
}
/** A task that runs `body` as its own job. */
const job = (body: Eval<void>): Start => ({ task: new Task([{ body, boundary: undefined }]), input: normal(undefined) })
/**
* NewPromiseResolveThenableJob: the work that calls the thenable's `then`. Adopting a native promise through the
* intrinsic `then` takes the same jobs as calling it, and keeps the rejection as thrown so its diagnostic survives.
*/
export const adoptThenable = <R>(
ctx: Interpreter<R>,
promise: PromiseObj,
thenable: Obj,
then: Value,
): Eval<void> | void => {
const machine = ctx.machine
const resolving = machine.resolving(promise)
if (then === machine.intrinsicThen && thenable instanceof PromiseObj) {
machine.then(thenable, { kind: "settle", target: resolving })
return
}
const proto = ctx.builtins.Function
const resolve = new Resolver(proto, "", resolving, "resolve")
const reject = new Resolver(proto, "", resolving, "reject")
return (function* (): Eval<void> {
try {
yield* ctx.call(then, thenable, [resolve, reject])
} catch (error) {
resolving.reject(error)
}
})()
}
// A `then`/`catch` reaction calls program code: the handler runs as a job, and its result or failure settles the
// derived promise. A missing handler passes the outcome through.
@@ -70,7 +86,7 @@ const handle = <R>(
ctx: Interpreter<R>,
reaction: Extract<Reaction, { readonly kind: "handler" }>,
settled: Completion,
): Start | void => {
): Eval<void> | void => {
const handler = settled.ok ? reaction.onFulfilled : reaction.onRejected
const derived = reaction.derived
if (handler === undefined || (!settled.ok && settled.error instanceof Interruption)) {
@@ -87,7 +103,7 @@ const handle = <R>(
}
derived.resolve(result)
}
return job(body())
return body()
}
const promiseStatics = ["all", "allSettled", "race", "any", "resolve", "reject", "withResolvers", "try"] as const
@@ -98,8 +114,8 @@ function* invokePromiseMethod<R>(
args: Array<Value>,
site: AstNode | undefined,
): Eval<Value> {
const runner = ctx.runner
if (name === "resolve") return runner.promiseResolve(args[0])
const machine = ctx.machine
if (name === "resolve") return machine.promiseResolve(args[0])
if (name === "reject") {
const made = capability(ctx, site)
made.reject(new Throw(args[0]))
@@ -134,7 +150,7 @@ function* combinator<R>(
iterable: Value,
site: AstNode | undefined,
): Eval<Value> {
const runner = ctx.runner
const machine = ctx.machine
const made = capability(ctx, site)
try {
const cursor = yield* ctx.iterate(iterable)
@@ -146,13 +162,13 @@ function* combinator<R>(
while (true) {
const step = yield* cursor.next()
if (step.done) break
const item = runner.promiseResolve(step.value)
const item = machine.promiseResolve(step.value)
const reaction: Reaction = { kind: "combinator", combination, index: index++, called: false }
combination.values.push(undefined)
combination.reasons.push(undefined)
combination.remaining++
combination.attached.push([item, reaction])
runner.then(item, reaction)
machine.then(item, reaction)
}
if (name === "race" && index === 0) {
throw typeError("Promise.race([]) would never settle; provide at least one promise or value.")
@@ -203,7 +219,7 @@ const combine = <R>(
}
const detachAll = <R>(ctx: Interpreter<R>, combination: Combination) => {
for (const [item, reaction] of combination.attached) ctx.runner.detach(item, reaction)
for (const [item, reaction] of combination.attached) ctx.machine.detach(item, reaction)
}
const finishCombination = <R>(ctx: Interpreter<R>, combination: Combination) => {
@@ -230,7 +246,7 @@ const instanceMethod = <R>(
const onFulfilled = name === "then" ? reactionHandler(args[0], method) : undefined
const onRejected = reactionHandler(name === "then" ? args[1] : args[0], method)
const made = capability(ctx, site)
ctx.runner.then(promise, { kind: "handler", onFulfilled, onRejected, derived: made })
ctx.machine.then(promise, { kind: "handler", onFulfilled, onRejected, derived: made })
return made.promise
}
@@ -243,7 +259,7 @@ const chainFinally = <R>(
site: AstNode | undefined,
): PromiseObj => {
const made = capability(ctx, site)
ctx.runner.then(
ctx.machine.then(
source,
cleanup === undefined ? { kind: "settle", target: made } : { kind: "finally", cleanup, target: made, site },
)
@@ -255,7 +271,7 @@ const cleanUp = <R>(
reaction: Extract<Reaction, { readonly kind: "finally" }>,
settled: Completion,
) => {
const runner = ctx.runner
const machine = ctx.machine
const made = reaction.target
if (!settled.ok && settled.error instanceof Interruption) return made.reject(settled.error)
const cleanup = reaction.cleanup
@@ -269,17 +285,17 @@ const cleanUp = <R>(
}
let after: PromiseObj
try {
after = runner.promiseResolve(result)
after = machine.promiseResolve(result)
} catch (error) {
made.reject(error)
return
}
// The spec chains `then(valueThunk)` onto the cleanup's promise: one more job before the outcome passes.
const derived = capability(ctx, reaction.site)
runner.then(after, { kind: "finallyCleaned", target: derived })
runner.then(derived.promise, { kind: "finallyOutcome", target: made, outcome: settled })
machine.then(after, { kind: "finallyCleaned", target: derived })
machine.then(derived.promise, { kind: "finallyOutcome", target: made, outcome: settled })
}
return job(body())
return body()
}
const reactionHandler = (value: Value, method: string): Callable | undefined => {
@@ -321,7 +337,7 @@ const promiseLikeMethods = <R>(ctx: Interpreter<R>) => {
const source = receiver(Obj, thisValue, name)
const copy = new Obj(ctx.builtins.Object)
for (const [key, slot] of source.props) copy.props.set(key, { ...slot })
return ctx.runner.promiseResolve(copy)
return ctx.machine.promiseResolve(copy)
}
methods(
ctx.builtins,
@@ -363,7 +379,7 @@ export const promiseGlobal = <R>(ctx: Interpreter<R>) => {
["finally", 1, (thisValue, args, site) => instanceMethod(ctx, "finally", thisValue, args, site)],
])
const then = get(proto, "then")
if (then instanceof Callable) ctx.runner.intrinsicThen = then
if (then instanceof Callable) ctx.machine.intrinsicThen = then
promiseLikeMethods(ctx)
return promise
}
-590
View File
@@ -1,590 +0,0 @@
import { Cause, type Context, Effect, Exit, Fiber } from "effect"
import type { Diagnostic } from "../codemode.js"
import { locate, normalizeError } from "./errors.js"
import type { Interpreter } from "./interpreter.js"
import { MAX_PENDING_PROMISES } from "./limits.js"
import { type AstNode, PendingThrow, rangeError, typeError } from "./model.js"
import { type Callable, type GeneratorObj, get, Obj, PromiseObj, Resolver, type Value } from "./objects.js"
import { react } from "./promises.js"
import { fromJson, type Json } from "../data.js"
import { typeofValue } from "./references.js"
export {
abrupt,
AsyncBoundary,
type Body,
type Boundary,
Call,
type Completion,
Enter,
type Entry,
type Eval,
Await,
generatorBody,
type GeneratorRequest,
Host,
Interruption,
Invoke,
isEval,
MAX_CALL_DEPTH,
normal,
type Signal,
Slice,
Task,
Yield,
} from "./signals.js"
import {
abrupt,
AsyncBoundary,
Await,
type Body,
Call,
type Completion,
Enter,
type Eval,
Host,
Interruption,
Invoke,
normal,
type Signal,
Task,
Yield,
} from "./signals.js"
export type Start = { readonly task: Task; readonly input: Completion }
/** What the member reactions of one `Promise.all`/`allSettled`/`race`/`any` share. */
export type Combination = {
readonly name: "all" | "allSettled" | "race" | "any"
/** Settles the combinator's result. */
readonly made: Resolving
readonly values: Array<Value>
readonly reasons: Array<Value>
/** Members still to settle, plus one until iteration ends. */
remaining: number
/** Every member's reaction, detached once the result is decided. */
readonly attached: Array<readonly [PromiseObj, Reaction]>
}
/**
* A settled promise's reaction, as data. It runs as a job (see `react` in promises.ts) and either finishes at once or
* starts a task. The kinds:
* - `await`: resume the async body parked on the promise.
* - `settle`: pass the outcome on to `target`.
* - `handler`: `then`/`catch` handlers; the handler's result settles `derived`.
* - `combinator`: one member of a `Promise` combinator.
* - `finally`, `finallyCleaned`, `finallyOutcome`: the steps of `Promise.prototype.finally` with a cleanup.
* - `awaitReturn`: an async generator's `return(value)` once `value` settles.
* - `callback`: a host closure, still used by the async-from-sync iterator adapter.
*/
export type Reaction =
| { readonly kind: "await"; readonly task: Task }
| { readonly kind: "settle"; readonly target: Resolving }
| {
readonly kind: "handler"
readonly onFulfilled: Callable | undefined
readonly onRejected: Callable | undefined
readonly derived: Resolving
}
| { readonly kind: "combinator"; readonly combination: Combination; readonly index: number; called: boolean }
| {
readonly kind: "finally"
readonly cleanup: Callable
readonly target: Resolving
readonly site: AstNode | undefined
}
| { readonly kind: "finallyCleaned"; readonly target: Resolving }
| { readonly kind: "finallyOutcome"; readonly target: Resolving; readonly outcome: Completion }
| { readonly kind: "awaitReturn"; readonly generator: GeneratorObj }
| { readonly kind: "callback"; readonly run: (settled: Completion) => Start | void }
/** One queued job, as data: run a settled promise's reaction, resume a task, or adopt a thenable. */
export type Job =
| { readonly kind: "reaction"; readonly reaction: Reaction; readonly settled: Completion }
| { readonly kind: "resume"; readonly task: Task; readonly input: Completion }
| { readonly kind: "thenable"; readonly promise: PromiseObj; readonly thenable: Obj; readonly then: Value }
/**
* Host work the program waits on: a tool or extension call, running as a fiber the runner keeps by `id`. Its outcome
* arrives as an inbox record and settles the call's promise in a later job.
*/
export class HostCall {
status: "inFlight" | "completed" = "inFlight"
constructor(
readonly id: number,
/** What runs: a tool path, or an extension function's label. */
readonly label: string,
/** A tool's arguments, as they crossed. */
readonly args: ReadonlyArray<Json | undefined> | undefined,
/** How the result becomes a program value: a tool's crosses as JSON, an extension's is already one. */
readonly result: "json" | "value",
readonly resolving: Resolving,
/** The call that started the work, where a defect it raises is located. */
readonly site: AstNode | undefined,
) {}
}
/** A host call's outcome, waiting to be delivered. */
type Delivery = { readonly call: HostCall; readonly completion: Completion }
/**
* CreateResolvingFunctions as data: settles one promise at most once, however many `Resolver`s share it. `reject` takes
* the failure as thrown; one without a location is located at `site`, the call that created the promise.
*/
export class Resolving {
done = false
constructor(
private readonly runner: Pick<Runner<unknown>, "resolveWith" | "reject">,
readonly promise: PromiseObj,
readonly site: AstNode | undefined,
) {}
resolve(resolution: Value): void {
if (this.done) return
this.done = true
this.runner.resolveWith(this.promise, resolution, this.site)
}
reject(reason: unknown): void {
if (this.done) return
this.done = true
this.runner.reject(this.promise, locate(reason, this.site))
}
}
type Pause =
| { readonly kind: "slice"; readonly input: Completion }
| { readonly kind: "host"; readonly effect: Effect.Effect<unknown, unknown> }
/** Interpreter steps between clock checks, and how long one slice may run before the host gets a turn. */
const FUEL = 64
const SLICE_MS = 1
/**
* One execution's job queue. Program code runs only inside a job, one job at a time and each to completion, as in a
* JavaScript engine: promise reactions and resumed awaits queue in order, host work runs concurrently and settles its
* promise as a later job, and the program is stuck exactly when no job is queued and no host work is running.
*/
export class Runner<R> {
/** The intrinsic `Promise.prototype.then`, so adopting a native promise skips exposing its rejection first. */
intrinsicThen: Callable | undefined
private readonly queue: Array<Job> = []
private head = 0
private current: Task | undefined
private fuel = FUEL
private sliceStart = 0
private pending = 0
private nextID = 0
private nextHostID = 0
/** Rejections nothing handled yet, described when they happened so reporting them at the end is cheap. */
private readonly unhandled = new Map<PromiseObj, Diagnostic>()
/** Bodies suspended at an `await` and the promise each waits on, so a stall can point at the one that is stuck. */
private readonly parked = new Map<Task, { readonly promise: PromiseObj; readonly node: AstNode | undefined }>()
/** Running host work by `HostCall` id; fibers stay here and never become part of the program's state. */
private readonly fibers = new Map<number, Fiber.Fiber<unknown, unknown>>()
private readonly inbox: Array<Delivery> = []
private wake: (() => void) | undefined
private stopping = false
constructor(
private readonly ctx: Interpreter<R>,
/** The services host work runs with: the caller's, so tools see its context, tracing, and clock. */
private readonly services: Context.Context<R>,
) {}
/** Activations on the running task's stack. */
get depth(): number {
return this.current?.stack.length ?? 0
}
/**
* Runs the program as the first job until its body completes, then returns how it ended. Host work it started may
* still be running; `interrupt` stops it.
*/
run(main: Body): Effect.Effect<Completion, unknown, R> {
const self = this
return Effect.gen(function* () {
let outcome: Completion | undefined
let start: Start | undefined = {
task: new Task([
{
body: main,
boundary: new AsyncBoundary((completion) => {
outcome = completion
}, undefined),
},
]),
input: normal(undefined),
}
self.sliceStart = performance.now()
while (outcome === undefined) {
if (start === undefined) {
const job = self.dequeue()
if (job !== undefined) {
start = self.runJob(job) ?? undefined
if (start === undefined && self.tick()) yield* self.yieldToHost
continue
}
const delivery = self.inbox.shift()
if (delivery !== undefined) {
self.deliver(delivery)
continue
}
if (self.fibers.size > 0) {
yield* self.hostSettled
continue
}
return abrupt(
new PendingThrow(
"Error",
"The program is waiting on a promise that can never settle: nothing else is running, so nothing can resolve it. Code Mode has no timers or sleep, so don't wait or poll inside a program.",
self.stuckAwait(),
),
)
}
const pause = self.drive(start.task, start.input)
if (pause === undefined) {
start = undefined
if (self.tick()) yield* self.yieldToHost
continue
}
if (pause.kind === "slice") {
start = { task: start.task, input: pause.input }
yield* self.yieldToHost
continue
}
const exit = yield* Effect.exit(pause.effect)
if (Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause)) return yield* Effect.failCause(exit.cause)
start = {
task: start.task,
input: Exit.isSuccess(exit) ? normal(exit.value) : abrupt(Cause.squash(exit.cause)),
}
}
if (!outcome.ok && outcome.error instanceof Interruption) return yield* Effect.failCause(outcome.error.cause)
return outcome
})
}
/** Stops host work still running, waiting for its cleanup. */
interrupt(): Effect.Effect<void> {
const self = this
return Effect.gen(function* () {
self.stopping = true
while (self.fibers.size > 0) yield* Fiber.interruptAll([...self.fibers.values()])
})
}
/**
* Rejections no handler observed, in the order their promises were created. Host work that finished before the
* program did settles first, so its failures count even though no later job ran.
*/
diagnostics(): Array<Diagnostic> {
for (let delivery = this.inbox.shift(); delivery !== undefined; delivery = this.inbox.shift())
this.deliver(delivery)
return [...this.unhandled].sort(([left], [right]) => left.id - right.id).map(([, diagnostic]) => diagnostic)
}
/** Counts one interpreter step; true when the slice is over and the caller should yield `Slice`. */
tick(): boolean {
if (--this.fuel > 0) return false
this.fuel = FUEL
return performance.now() - this.sliceStart >= SLICE_MS
}
/** A blocking host call, with the caller's services provided so the runner can run it as is. */
blocking<A, E>(effect: Effect.Effect<A, E, R>): Host {
return new Host(Effect.provideContext(effect, this.services))
}
enqueue(job: Job): void {
this.queue.push(job)
}
/**
* Starts host work now, settling `resolving`'s promise in a later job, in completion order. A defect is located at
* `site`, the call that started the work.
*/
host(
effect: Effect.Effect<unknown, unknown, R>,
call: {
readonly label: string
readonly args?: ReadonlyArray<Json | undefined>
readonly result: "json" | "value"
readonly resolving: Resolving
readonly site: AstNode | undefined
},
): HostCall {
const record = new HostCall(this.nextHostID++, call.label, call.args, call.result, call.resolving, call.site)
// Starts synchronously, so admission and hooks happen at the call site.
const fiber = Effect.runForkWith(this.services)(effect)
this.fibers.set(record.id, fiber)
fiber.addObserver((exit) => {
this.fibers.delete(record.id)
// Interrupted by the program ending: nothing is left to settle.
if (this.stopping) return
this.inbox.push({
call: record,
completion: Exit.isSuccess(exit)
? normal(exit.value)
: abrupt(
Cause.hasInterruptsOnly(exit.cause)
? new Interruption(exit.cause)
: Cause.hasDies(exit.cause)
? locate(Cause.squash(exit.cause), record.site)
: Cause.squash(exit.cause),
),
})
this.wake?.()
})
return record
}
private deliver(delivery: Delivery): void {
const call = delivery.call
const completion = delivery.completion
call.status = "completed"
if (!completion.ok) return call.resolving.reject(completion.error)
call.resolving.resolve(
call.result === "json" ? fromJson(this.ctx, completion.value as Json | undefined) : (completion.value as Value),
)
}
// --- Promise abstract operations ---
newPromise(): PromiseObj {
if (this.pending >= MAX_PENDING_PROMISES) {
throw rangeError(
`Too many pending promises (limit ${MAX_PENDING_PROMISES}); await promises before creating more.`,
)
}
this.pending++
return new PromiseObj(this.ctx.builtins.Promise, this.nextID++)
}
/** CreateResolvingFunctions for `promise`; a failure without a location is located at `site`. */
resolving(promise: PromiseObj, site?: AstNode): Resolving {
return new Resolving(this, promise, site)
}
/** PerformPromiseThen with one reaction for either outcome; marks the promise handled. */
then(promise: PromiseObj, reaction: Reaction): void {
if (promise.state === "pending") promise.reactions.push(reaction)
else {
if (promise.state === "rejected") this.unhandled.delete(promise)
const settled = promise.state === "fulfilled" ? normal(promise.result) : abrupt(promise.result)
this.enqueue({ kind: "reaction", reaction, settled })
}
promise.handled = true
}
/** Removes a reaction an internal consumer no longer needs, so a long-pending promise does not keep it. */
detach(promise: PromiseObj, reaction: Reaction): void {
const index = promise.reactions.indexOf(reaction)
if (index >= 0) promise.reactions.splice(index, 1)
}
/** PromiseResolve(%Promise%, value). */
promiseResolve(value: Value): PromiseObj {
if (value instanceof PromiseObj) return value
const promise = this.newPromise()
this.resolveWith(promise, value)
return promise
}
/** Rejects `promise` with a failure as thrown. */
reject(promise: PromiseObj, reason: unknown): void {
this.settle(promise, abrupt(reason))
}
private settle(promise: PromiseObj, completion: Completion): void {
if (promise.state !== "pending") return
this.pending--
promise.state = completion.ok ? "fulfilled" : "rejected"
promise.result = completion.ok ? completion.value : completion.error
const reactions = promise.reactions
promise.reactions = []
if (!completion.ok && !promise.handled && !(completion.error instanceof Interruption)) {
const failure = normalizeError(completion.error)
this.unhandled.set(promise, {
...failure,
message: `Unhandled rejection from an un-awaited promise: ${failure.message}`,
})
}
for (const reaction of reactions) this.enqueue({ kind: "reaction", reaction, settled: completion })
}
/** ResolvePromise: adopts a thenable, otherwise fulfills. */
resolveWith(promise: PromiseObj, resolution: Value, site?: AstNode): void {
if (resolution === promise) {
const cycle = typeError("Chaining cycle detected: a promise cannot resolve with itself.", site)
return this.settle(promise, abrupt(cycle))
}
if (!(resolution instanceof Obj)) return this.settle(promise, normal(resolution))
const then = get(resolution, "then")
if (typeofValue(then) !== "function") return this.settle(promise, normal(resolution))
this.enqueue({ kind: "thenable", promise, thenable: resolution, then })
}
// NewPromiseResolveThenableJob. Adopting a native promise through the intrinsic `then` takes the same jobs as
// calling it, and keeps the rejection as thrown so its diagnostic survives.
private thenableJob(promise: PromiseObj, thenable: Obj, then: Value): Start | void {
const resolving = this.resolving(promise)
if (then === this.intrinsicThen && thenable instanceof PromiseObj) {
this.then(thenable, { kind: "settle", target: resolving })
return
}
const proto = this.ctx.builtins.Function
const resolve = new Resolver(proto, "", resolving, "resolve")
const reject = new Resolver(proto, "", resolving, "reject")
const ctx = this.ctx
const body = function* (): Eval<void> {
try {
yield* ctx.call(then, thenable, [resolve, reject])
} catch (error) {
resolving.reject(error)
}
}
return { task: new Task([{ body: body(), boundary: undefined }]), input: normal(undefined) }
}
private runJob(job: Job): Start | void {
if (job.kind === "resume") return { task: job.task, input: job.input }
if (job.kind === "thenable") return this.thenableJob(job.promise, job.thenable, job.then)
const reaction = job.reaction
if (reaction.kind !== "await") return react(this.ctx, reaction, job.settled)
this.parked.delete(reaction.task)
return { task: reaction.task, input: job.settled }
}
// --- Driver ---
// Runs a task until its stack empties or it pauses for a slice or host work, which resumes it before any other job.
private drive(task: Task, input: Completion): Pause | undefined {
const stack = task.stack
this.current = task
let completion = input
while (stack.length > 0) {
const entry = stack[stack.length - 1]!
let step: IteratorResult<Signal, unknown>
try {
step = completion.ok ? entry.body.next(completion.value) : entry.body.throw(completion.error)
} catch (error) {
stack.pop()
completion = entry.boundary === undefined ? abrupt(error) : entry.boundary.finish(abrupt(error))
continue
}
if (step.done) {
stack.pop()
completion = entry.boundary === undefined ? normal(step.value) : entry.boundary.finish(normal(step.value))
continue
}
const signal = step.value
if (signal instanceof Call) {
stack.push({ body: signal.body, boundary: signal.boundary })
completion = normal(undefined)
if (this.tick()) return { kind: "slice", input: completion }
continue
}
if (signal instanceof Invoke) {
let call: Call
try {
call = this.ctx.enter(signal)
} catch (error) {
completion = abrupt(error)
continue
}
stack.push({ body: call.body, boundary: call.boundary })
completion = normal(undefined)
if (this.tick()) return { kind: "slice", input: completion }
continue
}
if (signal instanceof Enter) {
for (const saved of signal.entries) stack.push(saved)
completion = signal.input
if (this.tick()) return { kind: "slice", input: completion }
continue
}
if (signal instanceof Await) {
const index = stack.findLastIndex((item) => item.boundary?.async === true)
if (index < 0) {
completion = abrupt(typeError("await is only valid in async functions."))
continue
}
let promise: PromiseObj
try {
promise = this.promiseResolve(signal.value)
} catch (error) {
completion = abrupt(error)
continue
}
const boundary = stack[index]!.boundary!
const continuation = new Task(stack.splice(index))
this.parked.set(continuation, { promise, node: signal.node })
this.then(promise, { kind: "await", task: continuation })
completion = boundary.suspended()
continue
}
if (signal instanceof Yield) {
const index = stack.findLastIndex((item) => item.boundary?.generator === true)
if (index < 0) {
completion = abrupt(typeError("yield is only valid inside a generator."))
continue
}
completion = stack[index]!.boundary!.yielded(signal.value, () => stack.splice(index))
continue
}
if (signal instanceof Host) return { kind: "host", effect: signal.effect }
return { kind: "slice", input: normal(undefined) }
}
this.current = undefined
if (!completion.ok) throw completion.error
return undefined
}
// The innermost stuck `await`: an outer one waits on the result of a parked async body, so prefer one that does not.
// Bodies that wait on each other in a cycle leave no such await; any located one is then as good as another.
private stuckAwait(): AstNode | undefined {
const results = new Set<Value>()
for (const task of this.parked.keys()) {
const boundary = task.stack[0]?.boundary
if (boundary instanceof AsyncBoundary) results.add(boundary.result)
}
const located = [...this.parked.values()].filter((parked) => parked.node !== undefined)
return (located.find((parked) => !results.has(parked.promise)) ?? located[0])?.node
}
private dequeue(): Job | undefined {
if (this.head === this.queue.length) {
if (this.head > 0) {
this.queue.length = 0
this.head = 0
}
return undefined
}
const job = this.queue[this.head++]
if (this.head > 4096 && this.head * 2 > this.queue.length) {
this.queue.splice(0, this.head)
this.head = 0
}
return job
}
private get yieldToHost(): Effect.Effect<void> {
return Effect.map(Effect.yieldNow, () => {
this.sliceStart = performance.now()
})
}
private get hostSettled(): Effect.Effect<void> {
return Effect.callback<void>((resume) => {
if (this.inbox.length > 0) return resume(Effect.void)
this.wake = () => {
this.wake = undefined
resume(Effect.void)
}
return Effect.sync(() => {
this.wake = undefined
})
})
}
}
+28 -37
View File
@@ -1,14 +1,15 @@
import type { Cause, Effect } from "effect"
import type { Cause } from "effect"
import type { Frame } from "../machine/frame.js"
import type { HostRequest, Resolving } from "../machine/scheduler.js"
import { type AstNode, GeneratorReturn, type GeneratorRequestKind, typeError } from "./model.js"
import type { Value } from "./objects.js"
// The signals interpreter work sends its driver, and the activation records the driver keeps. Nothing here needs
// Effect at run time, so the machine can use them too.
// The signals interpreter work (a built-in's host generator) sends the machine. Nothing here needs Effect at run time.
/**
* Interpreter work: a generator that yields signals to the driver and returns its result. Work inside one activation
* composes with `yield*`; a program call is a `Call`, so program recursion lives on the explicit stack below and never
* grows the host stack.
* Interpreter work: a generator that yields signals to the machine and returns its result. It runs in a native frame;
* a program call is an `Invoke`, which the machine runs as frames on its own stack, so program recursion never grows
* the host stack.
*/
export type Eval<A> = Generator<Signal, A, unknown>
@@ -19,16 +20,13 @@ export type Completion =
export const normal = (value: unknown): Completion => ({ ok: true, value })
export const abrupt = (error: unknown): Completion => ({ ok: false, error })
/**
* What an activation's body is: interpreter work, or a machine task (`src/machine`), which answers the same `next` and
* `throw` as a generator.
*/
/** What a native frame runs: interpreter work, or a machine task (a generator's body), which answers the same calls. */
export interface Body {
next(input?: unknown): IteratorResult<Signal, unknown>
throw(error: unknown): IteratorResult<Signal, unknown>
}
/** Run `body` as a new activation; a boundary marks where a suspended body splits off the stack. */
/** Run `body` in a native frame of its own; a boundary marks where the stack splits when the body above suspends. */
export class Call {
constructor(
readonly body: Body,
@@ -36,10 +34,10 @@ export class Call {
) {}
}
/** Push saved activations back on the stack and continue the top one with `input`. */
/** Push saved frames back on the stack and continue the top one with `input`. */
export class Enter {
constructor(
readonly entries: Array<Entry>,
readonly frames: Array<Frame>,
readonly input: Completion,
) {}
}
@@ -59,7 +57,7 @@ export class Yield {
/** Block the current job on host work: no other job runs until it ends, as with a synchronous host call. */
export class Host {
constructor(readonly effect: Effect.Effect<unknown, unknown>) {}
constructor(readonly request: HostRequest) {}
}
/**
@@ -74,10 +72,7 @@ export class Interruption {
/** Let the host run; the current job continues before any other job. */
export const Slice: unique symbol = Symbol("codemode.slice")
/**
* Call a program function from inside interpreter work. The machine evaluator answers it on its own stack; the
* runner, when it reaches it, starts the call as a new activation.
*/
/** Call a program function from inside interpreter work; the machine runs the call as frames on its own stack. */
export class Invoke {
constructor(
readonly callable: Value,
@@ -100,40 +95,36 @@ export interface Boundary {
readonly generator: boolean
/** The body above returned or threw. */
finish(completion: Completion): Completion
/** The body above suspended at an `await`; its activations are saved in the continuation. */
/** The body above suspended at an `await`; its frames are parked on the awaited promise. */
suspended(): Completion
/** The body above yielded; `split` takes its activations off the stack when it suspends. */
yielded(value: Value, split: () => Array<Entry>): Completion
/** The body above yielded; `split` takes its frames off the stack when it suspends. */
yielded(value: Value, split: () => Array<Frame>): Completion
}
/** The boundary of an async body: the body's completion settles it, and the caller receives `result` at once. */
/**
* The boundary of host work that crosses its arguments first (a tool call): the caller receives the call's promise
* at once, and a failure while crossing rejects it. Once the work starts, its outcome settles the promise.
*/
export class AsyncBoundary implements Boundary {
readonly async = true
readonly generator = false
constructor(
private readonly settle: (completion: Completion) => void,
readonly result: Value,
) {}
constructor(readonly resolving: Resolving) {}
get result(): Value {
return this.resolving.promise
}
finish(completion: Completion): Completion {
this.settle(completion)
return normal(this.result)
if (!completion.ok) this.resolving.reject(completion.error)
return normal(this.resolving.promise)
}
suspended(): Completion {
return normal(this.result)
return normal(this.resolving.promise)
}
yielded(): Completion {
return abrupt(typeError("yield is only valid inside a generator."))
}
}
export type Entry = { readonly body: Body; readonly boundary: Boundary | undefined }
/** Paused or running program code: activations on an explicit stack, innermost last. */
export class Task {
constructor(readonly stack: Array<Entry>) {}
}
/** Most activations one task may hold, as the call-stack limit. */
/** Most activations one stack may hold, as the call-stack limit. */
export const MAX_CALL_DEPTH = 10_000
// Program values never have a `next` method of their own: an object's properties live in its property map.
+75 -62
View File
@@ -30,19 +30,22 @@ import {
import { isOpaque } from "../interpreter/references.js"
import { ScopeStack } from "../interpreter/scope.js"
import {
AsyncBoundary,
Call,
abrupt,
type Body,
type Boundary,
type Completion,
type Eval,
generatorBody,
Invoke,
isEval,
MAX_CALL_DEPTH,
normal,
type Signal,
} from "../interpreter/signals.js"
import type { Resolving } from "./scheduler.js"
import type { StatementResult } from "../interpreter/model.js"
import { Frame, kind, type Out, PENDING, type Pending } from "./frame.js"
import { ev } from "./expressions.js"
import type { Machine } from "./machine.js"
import { bind, declaring } from "./patterns.js"
import { blockStatement } from "./statements.js"
import { MachineTask } from "./task.js"
@@ -59,7 +62,7 @@ export function dispatch(
if (callable instanceof Fn) return invoke(task, callable, thisValue, args, node)
if (callable instanceof Builtin) {
// A loop made only of built-in calls has no program call or loop back-edge to count, so count the call.
if (task.ctx.runner.tick()) task.slice = true
if (task.machine.tick()) task.slice = true
// A bound function calls its target directly, so a program target runs as a frame rather than inside a native.
if (callable instanceof BoundFn) {
return dispatch(task, callable.target, callable.boundThis, [...callable.boundArgs, ...args], node)
@@ -79,67 +82,36 @@ export function dispatch(
throw notAFunction(callee, node)
}
// A program call: a synchronous body runs as a counted `Call` frame on this stack. An async body runs as a task of its
// own behind an async boundary, as the runner keeps it today, and the caller receives its promise; a generator call
// binds its parameters on this stack and returns the generator.
// A program call runs as a counted `Call` frame on this stack. An async function's frame is an async boundary: an
// `await` in its body cuts the stack there and the caller receives its promise, which the body's completion settles.
// A generator call binds its parameters on this stack and returns the generator.
function invoke(task: MachineTask, fn: Fn, thisValue: Value, args: Array<Value>, node: AstNode | undefined) {
const machine = task.machine
const runner = task.ctx.runner
if (runner.depth + machine.calls > MAX_CALL_DEPTH) throw rangeError("Maximum call stack size exceeded", node)
if (runner.tick()) task.slice = true
if (fn.async && !fn.generator) return task.request(asyncCall(machine, fn, thisValue, args, node), fn.body)
if (machine.depth > MAX_CALL_DEPTH) throw rangeError("Maximum call stack size exceeded", node)
if (machine.tick()) task.slice = true
const resolving = fn.async && !fn.generator ? machine.resolving(machine.newPromise()) : undefined
const counted = !fn.generator
if (counted) machine.calls++
return task.push(CallKind, fn.body, [fn, thisValue, args, node, counted, undefined, 0])
}
/** A program call the runner starts as its own activation, so its frame is not counted again. */
export function enter(machine: Machine, invocation: Invoke): Call {
const fn = invocation.callable as Fn
const runner = machine.ctx.runner
if (runner.depth + machine.calls > MAX_CALL_DEPTH) {
throw rangeError("Maximum call stack size exceeded", invocation.site)
}
if (fn.async && !fn.generator) return asyncCall(machine, fn, invocation.thisValue, invocation.args, invocation.site)
return new Call(callTask(machine, fn, invocation.thisValue, invocation.args, invocation.site))
}
const callTask = (machine: Machine, fn: Fn, thisValue: Value, args: Array<Value>, site: AstNode | undefined) => {
const task = new MachineTask(machine, new ScopeStack([], fn))
task.stack.push(new Frame(CallKind, fn.body, 0, task.scopes, [fn, thisValue, args, site, false, undefined, 0]))
return task
}
// An async function's body is a task behind an async boundary: its completion settles the promise the caller gets.
const asyncCall = (machine: Machine, fn: Fn, thisValue: Value, args: Array<Value>, site: AstNode | undefined) => {
const body = callTask(machine, fn, thisValue, args, site)
const runner = machine.ctx.runner
const promise = runner.newPromise()
const resolving = runner.resolving(promise)
return new Call(
body,
new AsyncBoundary(
(completion) =>
completion.ok ? resolving.resolve(completion.value as Value) : resolving.reject(completion.error),
promise,
),
)
if (counted) machine.depth++
return task.push(CallKind, fn.body, [fn, thisValue, args, node, counted, undefined, 0, resolving])
}
// The phases of a `Call` frame: bind the parameters (resuming at the slot index after a pattern finishes), make the
// generator or start the body, and receive the body's result. A generator's own body task starts at `RUN`.
// generator or start the body, and receive the body's result. A generator's own body task starts at `RUN`. An async
// function's frame that took a throw has `SETTLED` its promise with it.
const ENTER = 0
const BIND = 1
const BODY = 2
const RUN = 3
const RESULT = 4
const SETTLED = 5
// Slots: fn, this, args, call site, whether the frame counts toward the depth limit, the parameter scope, and the
// next parameter to bind.
// Slots: fn, this, args, call site, whether the frame counts toward the depth limit, the parameter scope, the next
// parameter to bind, and for an async function what settles its promise.
function callStep(task: MachineTask, frame: Frame, _node: AstNode, input: unknown): Out<Value> {
const slots = frame.slots
const fn = slots[0] as Fn
let phase = frame.phase
if (phase === SETTLED) return (slots[7] as Resolving).promise
if (phase === ENTER) {
const scopes = activate(task, fn, slots[1] as Value, slots[2] as Array<Value>)
frame.scope = scopes
@@ -168,10 +140,16 @@ function callStep(task: MachineTask, frame: Frame, _node: AstNode, input: unknow
input = result
}
}
if (slots[4]) task.machine.calls--
if (fn.body.type !== "BlockStatement") return input as Value
const result = input as StatementResult
return result.kind === "return" ? result.value : undefined
const result =
fn.body.type !== "BlockStatement"
? (input as Value)
: (input as StatementResult).kind === "return"
? (input as Extract<StatementResult, { kind: "return" }>).value
: undefined
const resolving = slots[7] as Resolving | undefined
if (resolving === undefined) return result
resolving.resolve(result)
return resolving.promise
}
// The activation's scope chain: the closure's scopes and a parameter scope holding `this`, `arguments`, and the
@@ -249,10 +227,19 @@ const generator = (task: MachineTask, fn: Fn, frame: Frame): GeneratorObj => {
}
export const CallKind = kind("Call", callStep, {
unwind: (task, frame) => {
if (frame.slots[4]) task.machine.calls--
return false
// An async function's body that throws rejects its promise; the caller still receives the promise.
unwind: (_task, frame, error) => {
const resolving = frame.slots[7] as Resolving | undefined
if (resolving === undefined || frame.phase === SETTLED) return false
resolving.reject(error)
frame.phase = SETTLED
return true
},
cut: (frame) => {
const resolving = frame.slots[7] as Resolving | undefined
return resolving === undefined ? undefined : normal(resolving.promise)
},
counts: (frame) => frame.slots[4] === true,
})
// The phases of a native frame: running (or receiving the answer it waits for), throwing a failure into the work, done.
@@ -262,10 +249,10 @@ const FINISHED = 2
/**
* Runs a built-in's interpreter work as a native frame: program calls it makes (`Invoke`) run as frames on this stack,
* and anything else it asks for goes to the driver. The frame holds a host generator, so it is opaque.
* and anything else it asks for is answered by the step loop. The frame holds a host generator, so it is opaque.
*/
export function native<A>(task: MachineTask, work: Eval<A>, site: AstNode | undefined, located: boolean): Out<A> {
const frame = new Frame(Native, site, RUNNING, task.scopes, [work, located, undefined])
const frame = new Frame(Native, site, RUNNING, task.scopes, [work, located, undefined, undefined, false])
task.stack.push(frame)
let out: Out<A>
try {
@@ -278,25 +265,41 @@ export function native<A>(task: MachineTask, work: Eval<A>, site: AstNode | unde
return out
}
// Slots: the work, whether its failures are located at the call site, and a failure to throw into it.
/**
* A native frame for a body that runs as an activation of its own: a job's work, or a body a built-in starts behind a
* boundary (`Call`). It counts toward the depth limit; the boundary decides what its completion gives the frame below.
*/
export const nativeFrame = (scopes: ScopeStack, body: Body, boundary: Boundary | undefined, counted: boolean): Frame =>
new Frame(Native, undefined, RUNNING, scopes, [body, false, undefined, boundary, counted])
/** The boundary a native frame's body runs behind, if any. */
export const boundaryOf = (frame: Frame): Boundary | undefined =>
frame.kind === Native ? (frame.slots[3] as Boundary | undefined) : undefined
// Slots: the work, whether its failures are located at the call site, a failure to throw into it, the boundary it
// runs behind, and whether it counts toward the depth limit.
function nativeStep(task: MachineTask, frame: Frame, site: AstNode | undefined, input: unknown): Out<Value> {
const slots = frame.slots
const work = slots[0] as Eval<Value>
const work = slots[0] as Body
let ok = frame.phase !== THROWING
let value = ok ? input : slots[2]
slots[2] = undefined
frame.phase = RUNNING
while (true) {
let result: IteratorResult<Signal, Value>
let result: IteratorResult<Signal, unknown>
try {
result = ok ? work.next(value) : work.throw(value)
} catch (error) {
frame.phase = FINISHED
const boundary = slots[3] as Boundary | undefined
if (boundary !== undefined) return outcome(boundary.finish(abrupt(error)))
throw slots[1] ? locate(error, site) : error
}
if (result.done) {
frame.phase = FINISHED
return result.value
const boundary = slots[3] as Boundary | undefined
if (boundary !== undefined) return outcome(boundary.finish(normal(result.value)))
return result.value as Value
}
const signal = result.value
if (!(signal instanceof Invoke)) {
@@ -317,6 +320,11 @@ function nativeStep(task: MachineTask, frame: Frame, site: AstNode | undefined,
}
}
const outcome = (completion: Completion): Value => {
if (!completion.ok) throw completion.error
return completion.value as Value
}
export const Native = kind("Native", nativeStep, {
opaque: true,
unwind: (_task, frame, error) => {
@@ -325,6 +333,11 @@ export const Native = kind("Native", nativeStep, {
frame.slots[2] = error
return true
},
cut: (frame) => {
const boundary = frame.slots[3] as Boundary | undefined
return boundary?.async ? boundary.suspended() : undefined
},
counts: (frame) => frame.slots[4] === true,
})
export type Hint = "number" | "string" | "default"
+13 -1
View File
@@ -1,5 +1,6 @@
import type { AstNode } from "../interpreter/model.js"
import type { ScopeStack } from "../interpreter/scope.js"
import type { Completion } from "../interpreter/signals.js"
import type { MachineTask } from "./task.js"
/**
@@ -26,6 +27,13 @@ export type Kind = {
// Method syntax, so each kind's step can name the node type it evaluates and the input it receives.
step(task: MachineTask, frame: Frame | undefined, node: AstNode | undefined, input: unknown): unknown
unwind?(task: MachineTask, frame: Frame, error: unknown): boolean
/**
* Whether the frame is an async boundary, where an `await` above cuts the stack: what the frame below receives once
* the frames from this one up are parked on the awaited promise, or undefined when the frame is no boundary.
*/
cut?(frame: Frame): Completion | undefined
/** Whether the frame counts toward the call-depth limit while it is on the stack. */
counts?(frame: Frame): boolean
/** A frame of this kind holds a host generator (a built-in that calls program code), so it cannot be saved. */
readonly opaque?: boolean
}
@@ -47,7 +55,11 @@ export class Frame {
) {}
}
export const kind = (name: string, step: Kind["step"], options?: Pick<Kind, "unwind" | "opaque">): Kind => ({
export const kind = (
name: string,
step: Kind["step"],
options?: Pick<Kind, "unwind" | "cut" | "counts" | "opaque">,
): Kind => ({
name,
step,
...options,
+348 -18
View File
@@ -1,34 +1,364 @@
import type { Diagnostic } from "../codemode.js"
import { fromJson, type Json } from "../data.js"
import { normalizeError } from "../interpreter/errors.js"
import type { Interpreter } from "../interpreter/interpreter.js"
import { MAX_PENDING_PROMISES } from "../interpreter/limits.js"
import { type AstNode, rangeError, typeError } from "../interpreter/model.js"
import { type Callable, get, Obj, PromiseObj, type Value } from "../interpreter/objects.js"
import { adoptThenable, react } from "../interpreter/promises.js"
import { typeofValue } from "../interpreter/references.js"
import { ScopeStack } from "../interpreter/scope.js"
import {
abrupt,
Await,
type Completion,
type Eval,
Host,
Interruption,
normal,
Slice,
Yield,
} from "../interpreter/signals.js"
import type { Source } from "../interpreter/source.js"
import type { Call, Invoke } from "../interpreter/signals.js"
import { nativeFrame } from "./calls.js"
import { Frame } from "./frame.js"
import { enter } from "./calls.js"
import { HostCall, type HostRequest, type Job, type Reaction, Resolving, type Stop } from "./scheduler.js"
import { ProgramKind } from "./statements.js"
import { MachineTask } from "./task.js"
/** Which evaluator runs program code: the machine (`src/machine`) or the generator evaluator in `interpreter.ts`. */
export type Evaluator = "machine" | "legacy"
/** Interpreter steps between clock checks, and how long one slice may run before the host gets a turn. */
const FUEL = 64
const SLICE_MS = 1
/** A host call's outcome, waiting to be delivered. */
type Delivery = { readonly call: HostCall; readonly completion: Completion }
/** Frames parked on a promise at an `await`, and what the frame below their boundary received when they were cut. */
type Parked = { readonly promise: PromiseObj; readonly node: AstNode | undefined; readonly result: Value }
/**
* The machine evaluator for one execution. Program code runs as explicit frames on `MachineTask` stacks, stepped by a
* loop, instead of host generators. Until the scheduler moves onto the machine too, each task is an activation body
* the runner drives: the program, an async function's body, a generator's body, or a call the runner starts.
* One execution's machine: program code runs as explicit frames on a stack, stepped by a loop, and the job queue,
* promises, and host calls it waits on are data it keeps. Program code runs only inside a job, one job at a time and
* each to completion, as in a JavaScript engine: promise reactions and resumed awaits queue in order, host work runs
* outside and settles its promise as a later job, and the program is stuck exactly when no job is queued and no host
* work is running.
*
* `run` steps until the machine has to stop, and says why (`Stop`); the driver (`driver.ts`) does what the stop asks
* and calls `run` again. Nothing here runs host work or knows about Effect.
*/
export class Machine {
/** Program calls on the running task's machine stacks, counted toward the call-depth limit with the runner's. */
calls = 0
/** Activations on the stack that count toward the call-depth limit. */
depth = 0
/** The intrinsic `Promise.prototype.then`, so adopting a native promise skips exposing its rejection first. */
intrinsicThen: Callable | undefined
/** The stack every job runs on. */
readonly root: MachineTask
/** How the program's body ended, once it has. */
outcome: Completion | undefined
/** Frames suspended at an `await`, by the slice cut off the stack, so a stall can point at the one that is stuck. */
readonly parked = new Map<Array<Frame>, Parked>()
constructor(readonly ctx: Interpreter<unknown>) {}
private readonly queue: Array<Job> = []
private head = 0
private fuel = FUEL
private sliceStart = 0
private pending = 0
private nextID = 0
private nextHostID = 0
/** Rejections nothing handled yet, described when they happened so reporting them at the end is cheap. */
private readonly unhandled = new Map<PromiseObj, Diagnostic>()
/** Host calls queued since the last stop, for the driver to start. */
private queued: Array<HostCall> = []
/** Host calls the driver is running, by id. */
private readonly running = new Map<number, HostCall>()
private readonly inbox: Array<Delivery> = []
/** What the root stack continues with: the job in progress was paused, or has just started. */
private input: Completion | undefined
/** A slice is due once the queued host calls are handed over. */
private sliced = false
/** The program's body as a task: it runs the program, adopts a returned thenable, and copies the result out. */
program(source: Source): MachineTask {
const task = new MachineTask(this, this.ctx.programScopes())
task.stack.push(new Frame(ProgramKind, source.program, 0, task.scopes, []))
return task
constructor(readonly ctx: Interpreter<unknown>) {
this.root = new MachineTask(this, new ScopeStack([]))
}
/** A call the runner reached (a built-in called a program function outside any task), as its own activation. */
enter(invoke: Invoke): Call {
return enter(this, invoke)
/** Queues the program's body as the first job. */
start(source: Source): void {
this.root.enter([new Frame(ProgramKind, source.program, 0, this.ctx.programScopes(), [])])
this.input = normal(undefined)
}
/** Steps until the machine has to stop: see `Stop`. A throw no frame handles escapes as a defect. */
run(): Stop {
this.sliceStart = performance.now()
while (true) {
if (this.queued.length > 0) {
const calls = this.queued
this.queued = []
for (const call of calls) {
call.status = "inFlight"
this.running.set(call.id, call)
}
return { kind: "host", calls }
}
if (this.sliced) {
this.sliced = false
return { kind: "slice" }
}
const input = this.input
if (input !== undefined) {
this.input = undefined
this.continue(input)
continue
}
// A blocking call is running: the job that made it continues once it completes.
if (this.root.stack.length > 0) return { kind: "host", calls: [] }
if (this.outcome !== undefined) return { kind: "done", completion: this.outcome }
const job = this.dequeue()
if (job !== undefined) {
this.begin(job)
if (this.input === undefined && this.tick()) this.sliced = true
continue
}
const delivery = this.inbox.shift()
if (delivery !== undefined) {
this.deliver(delivery)
continue
}
if (this.running.size > 0) return { kind: "host", calls: [] }
return { kind: "stuck", node: this.stuckAwait() }
}
}
/**
* Reports how host work handed over by a stop ended. A blocking call's outcome continues the job that made it; a
* concurrent call's waits in the inbox and settles its promise in a later job, in completion order.
*/
complete(id: number, completion: Completion): void {
const call = this.running.get(id)
if (call === undefined) return
this.running.delete(id)
if (call.blocking) {
call.status = "completed"
this.input = completion
return
}
this.inbox.push({ call, completion })
}
/** Whether a host call's outcome is waiting to be delivered. */
get ready(): boolean {
return this.inbox.length > 0 || this.input !== undefined
}
/**
* Rejections no handler observed, in the order their promises were created. Host work that finished before the
* program did settles first, so its failures count even though no later job ran.
*/
diagnostics(): Array<Diagnostic> {
for (let delivery = this.inbox.shift(); delivery !== undefined; delivery = this.inbox.shift())
this.deliver(delivery)
return [...this.unhandled].sort(([left], [right]) => left.id - right.id).map(([, diagnostic]) => diagnostic)
}
/** Counts one interpreter step; true when the slice is over and the host should get a turn. */
tick(): boolean {
if (--this.fuel > 0) return false
this.fuel = FUEL
return performance.now() - this.sliceStart >= SLICE_MS
}
enqueue(job: Job): void {
this.queue.push(job)
}
/**
* Queues concurrent host work, settling `resolving`'s promise in a later job, in completion order. The driver starts
* it at the next stop, before any other job runs. A defect is located at `site`, the call that started the work.
*/
host(
request: HostRequest,
call: {
readonly label: string
readonly result: "json" | "value"
readonly resolving: Resolving
readonly site: AstNode | undefined
},
): HostCall {
const record = new HostCall(this.nextHostID++, request, call.label, false, call.result, call.resolving, call.site)
this.queued.push(record)
return record
}
/** A native frame that runs `body` as a job of its own. */
job(body: Eval<void>): Frame {
return nativeFrame(this.root.scopes, body, undefined, true)
}
/** Parks frames cut off the stack at an `await` on the awaited promise; they resume as a job once it settles. */
park(frames: Array<Frame>, promise: PromiseObj, node: AstNode | undefined, result: Value): void {
this.parked.set(frames, { promise, node, result })
this.then(promise, { kind: "await", frames })
}
// --- Promise abstract operations ---
newPromise(): PromiseObj {
if (this.pending >= MAX_PENDING_PROMISES) {
throw rangeError(
`Too many pending promises (limit ${MAX_PENDING_PROMISES}); await promises before creating more.`,
)
}
this.pending++
return new PromiseObj(this.ctx.builtins.Promise, this.nextID++)
}
/** CreateResolvingFunctions for `promise`; a failure without a location is located at `site`. */
resolving(promise: PromiseObj, site?: AstNode): Resolving {
return new Resolving(this, promise, site)
}
/** PerformPromiseThen with one reaction for either outcome; marks the promise handled. */
then(promise: PromiseObj, reaction: Reaction): void {
if (promise.state === "pending") promise.reactions.push(reaction)
else {
if (promise.state === "rejected") this.unhandled.delete(promise)
const settled = promise.state === "fulfilled" ? normal(promise.result) : abrupt(promise.result)
this.enqueue({ kind: "reaction", reaction, settled })
}
promise.handled = true
}
/** Removes a reaction an internal consumer no longer needs, so a long-pending promise does not keep it. */
detach(promise: PromiseObj, reaction: Reaction): void {
const index = promise.reactions.indexOf(reaction)
if (index >= 0) promise.reactions.splice(index, 1)
}
/** PromiseResolve(%Promise%, value). */
promiseResolve(value: Value): PromiseObj {
if (value instanceof PromiseObj) return value
const promise = this.newPromise()
this.resolveWith(promise, value)
return promise
}
/** Rejects `promise` with a failure as thrown. */
reject(promise: PromiseObj, reason: unknown): void {
this.settle(promise, abrupt(reason))
}
/** ResolvePromise: adopts a thenable, otherwise fulfills. */
resolveWith(promise: PromiseObj, resolution: Value, site?: AstNode): void {
if (resolution === promise) {
const cycle = typeError("Chaining cycle detected: a promise cannot resolve with itself.", site)
return this.settle(promise, abrupt(cycle))
}
if (!(resolution instanceof Obj)) return this.settle(promise, normal(resolution))
const then = get(resolution, "then")
if (typeofValue(then) !== "function") return this.settle(promise, normal(resolution))
this.enqueue({ kind: "thenable", promise, thenable: resolution, then })
}
private settle(promise: PromiseObj, completion: Completion): void {
if (promise.state !== "pending") return
this.pending--
promise.state = completion.ok ? "fulfilled" : "rejected"
promise.result = completion.ok ? completion.value : completion.error
const reactions = promise.reactions
promise.reactions = []
if (!completion.ok && !promise.handled && !(completion.error instanceof Interruption)) {
const failure = normalizeError(completion.error)
this.unhandled.set(promise, {
...failure,
message: `Unhandled rejection from an un-awaited promise: ${failure.message}`,
})
}
for (const reaction of reactions) this.enqueue({ kind: "reaction", reaction, settled: completion })
}
// --- Jobs ---
// Starts a job on the root stack: parked frames resume with how their promise settled, and a reaction or thenable
// that calls program code runs its work in a native frame. One that finishes at once leaves the stack empty.
private begin(job: Job): void {
if (job.kind === "resume") return this.resume(job.frames, job.input)
if (job.kind === "thenable") return this.work(adoptThenable(this.ctx, job.promise, job.thenable, job.then))
const reaction = job.reaction
if (reaction.kind !== "await") return this.work(react(this.ctx, reaction, job.settled))
this.parked.delete(reaction.frames)
this.resume(reaction.frames, job.settled)
}
private resume(frames: Array<Frame>, input: Completion): void {
this.root.enter(frames)
this.input = input
}
private work(body: Eval<void> | void): void {
if (body === undefined) return
this.root.enter([this.job(body)])
this.input = normal(undefined)
}
// Continues the job on the root stack. It ends when the stack empties, or pauses for a slice or a blocking host call;
// either way it continues before any other job.
private continue(input: Completion): void {
const root = this.root
const result = root.drive(input.ok, input.ok ? input.value : input.error)
if (result.done) {
if (this.tick()) this.sliced = true
return
}
const signal = result.value
if (signal === Slice) {
this.input = normal(undefined)
this.sliced = true
return
}
if (signal instanceof Host) {
const call = new HostCall(this.nextHostID++, signal.request, "", true, "value", undefined, undefined)
this.queued.push(call)
return
}
// Nothing on the stack can take an `await` or `yield`: the frame that asked receives the failure.
if (signal instanceof Await) this.input = abrupt(typeError("await is only valid in async functions."))
else if (signal instanceof Yield) this.input = abrupt(typeError("yield is only valid inside a generator."))
else this.input = abrupt(new TypeError("The machine cannot answer this signal here."))
}
private deliver(delivery: Delivery): void {
const call = delivery.call
const completion = delivery.completion
call.status = "completed"
const resolving = call.resolving!
if (!completion.ok) return resolving.reject(completion.error)
resolving.resolve(
call.result === "json" ? fromJson(this.ctx, completion.value as Json | undefined) : (completion.value as Value),
)
}
// The innermost stuck `await`: an outer one waits on the result of a parked async body, so prefer one that does not.
// Bodies that wait on each other in a cycle leave no such await; any located one is then as good as another.
private stuckAwait(): AstNode | undefined {
const results = new Set<Value>()
for (const parked of this.parked.values()) if (parked.result instanceof PromiseObj) results.add(parked.result)
const located = [...this.parked.values()].filter((parked) => parked.node !== undefined)
return (located.find((parked) => !results.has(parked.promise)) ?? located[0])?.node
}
private dequeue(): Job | undefined {
if (this.head === this.queue.length) {
if (this.head > 0) {
this.queue.length = 0
this.head = 0
}
return undefined
}
const job = this.queue[this.head++]
if (this.head > 4096 && this.head * 2 > this.queue.length) {
this.queue.splice(0, this.head)
this.head = 0
}
return job
}
}
+136
View File
@@ -0,0 +1,136 @@
import type { Json } from "../data.js"
import { locate } from "../interpreter/errors.js"
import type { AstNode } from "../interpreter/model.js"
import type { Callable, GeneratorObj, Obj, PromiseObj, Value } from "../interpreter/objects.js"
import type { Completion, Eval } from "../interpreter/signals.js"
import type { Frame } from "./frame.js"
// The scheduler's records: jobs, reactions, resolvers, and host calls. All of them are data the machine keeps, so a
// run's queue and the work it waits on can be read (and later saved) at any step boundary.
/** What the member reactions of one `Promise.all`/`allSettled`/`race`/`any` share. */
export type Combination = {
readonly name: "all" | "allSettled" | "race" | "any"
/** Settles the combinator's result. */
readonly made: Resolving
readonly values: Array<Value>
readonly reasons: Array<Value>
/** Members still to settle, plus one until iteration ends. */
remaining: number
/** Every member's reaction, detached once the result is decided. */
readonly attached: Array<readonly [PromiseObj, Reaction]>
}
/**
* A settled promise's reaction, as data. It runs as a job (see `react` in promises.ts) and either finishes at once or
* starts interpreter work. The kinds:
* - `await`: resume the frames parked on the promise, cut off the stack at an `await`.
* - `settle`: pass the outcome on to `target`.
* - `handler`: `then`/`catch` handlers; the handler's result settles `derived`.
* - `combinator`: one member of a `Promise` combinator.
* - `finally`, `finallyCleaned`, `finallyOutcome`: the steps of `Promise.prototype.finally` with a cleanup.
* - `awaitReturn`: an async generator's `return(value)` once `value` settles.
* - `callback`: a host closure, still used by the async-from-sync iterator adapter.
*/
export type Reaction =
| { readonly kind: "await"; readonly frames: Array<Frame> }
| { readonly kind: "settle"; readonly target: Resolving }
| {
readonly kind: "handler"
readonly onFulfilled: Callable | undefined
readonly onRejected: Callable | undefined
readonly derived: Resolving
}
| { readonly kind: "combinator"; readonly combination: Combination; readonly index: number; called: boolean }
| {
readonly kind: "finally"
readonly cleanup: Callable
readonly target: Resolving
readonly site: AstNode | undefined
}
| { readonly kind: "finallyCleaned"; readonly target: Resolving }
| { readonly kind: "finallyOutcome"; readonly target: Resolving; readonly outcome: Completion }
| { readonly kind: "awaitReturn"; readonly generator: GeneratorObj }
| { readonly kind: "callback"; readonly run: (settled: Completion) => Eval<void> | void }
/** One queued job, as data: run a settled promise's reaction, resume parked frames, or adopt a thenable. */
export type Job =
| { readonly kind: "reaction"; readonly reaction: Reaction; readonly settled: Completion }
| { readonly kind: "resume"; readonly frames: Array<Frame>; readonly input: Completion }
| { readonly kind: "thenable"; readonly promise: PromiseObj; readonly thenable: Obj; readonly then: Value }
/**
* What host work a call asks for. A tool call or a search is data; an extension's work is a live host value the driver
* runs as it is.
*/
export type HostRequest =
| { readonly kind: "tool"; readonly path: ReadonlyArray<string>; readonly args: Array<Json | undefined> }
| { readonly kind: "search"; readonly args: Array<Json | undefined> }
| { readonly kind: "effect"; readonly effect: unknown }
/**
* Host work the program waits on. The machine queues it and hands it to the driver at its next stop; the driver runs
* it and reports how it ended with `Machine.complete`. A concurrent call's outcome waits in the inbox and settles its
* promise in a later job; a blocking call stops the machine, and no other job runs until it ends.
*/
export class HostCall {
status: "queued" | "inFlight" | "completed" = "queued"
constructor(
readonly id: number,
readonly request: HostRequest,
/** What runs: a tool path, or an extension function's label. */
readonly label: string,
/** The running job waits for it: its outcome continues the frame that asked, before any other job. */
readonly blocking: boolean,
/** How a concurrent call's result becomes a program value: a tool's crosses as JSON, an extension's is one. */
readonly result: "json" | "value",
/** Settles a concurrent call's promise. */
readonly resolving: Resolving | undefined,
/** The call that started the work, where a defect it raises is located. */
readonly site: AstNode | undefined,
) {}
}
/**
* CreateResolvingFunctions as data: settles one promise at most once, however many `Resolver`s share it. `reject` takes
* the failure as thrown; one without a location is located at `site`, the call that created the promise.
*/
export class Resolving {
done = false
constructor(
private readonly scheduler: Settles,
readonly promise: PromiseObj,
readonly site: AstNode | undefined,
) {}
resolve(resolution: Value): void {
if (this.done) return
this.done = true
this.scheduler.resolveWith(this.promise, resolution, this.site)
}
reject(reason: unknown): void {
if (this.done) return
this.done = true
this.scheduler.reject(this.promise, locate(reason, this.site))
}
}
type Settles = {
resolveWith(promise: PromiseObj, resolution: Value, site?: AstNode): void
reject(promise: PromiseObj, reason: unknown): void
}
/**
* Why `Machine.run` stopped:
* - `done`: the program's body ended, with its completion.
* - `host`: start `calls`, newly queued host work, in order (a blocking call is last, and the machine continues only
* once it completes). With no calls, the machine waits for host work already running to complete.
* - `slice`: the step budget is used up; let the host run, then continue.
* - `stuck`: nothing can run or settle any more; `node` is the `await` that waits forever, when one is known.
*/
export type Stop =
| { readonly kind: "done"; readonly completion: Completion }
| { readonly kind: "host"; readonly calls: ReadonlyArray<HostCall> }
| { readonly kind: "slice" }
| { readonly kind: "stuck"; readonly node: AstNode | undefined }
+26 -5
View File
@@ -49,7 +49,7 @@ import {
predeclarePattern,
} from "../interpreter/operations.js"
import { describeValue } from "../interpreter/references.js"
import { Await, Interruption } from "../interpreter/signals.js"
import { abrupt, Await, Interruption, normal } from "../interpreter/signals.js"
import { type Frame, kind, type Out, PENDING, type Pending } from "./frame.js"
import { ev, named } from "./expressions.js"
import { type Iter, iteratorClose, iteratorStep, openIterator } from "./iteration.js"
@@ -357,7 +357,7 @@ const Labeled = kind("LabeledStatement", labeledStatement)
// The machine checks for a slice at each loop back-edge, so a long loop lets the host run.
const backEdge = (task: MachineTask, frame: Frame, phase: number): boolean => {
if (!task.ctx.runner.tick() && !task.slice) return false
if (!task.machine.tick() && !task.slice) return false
task.slice = true
frame.phase = phase
return true
@@ -866,10 +866,15 @@ const Try = kind("TryStatement", tryStatement, {
// Slots: the statement running and the value of the last expression statement. Phases: 1 has a statement's result,
// 2 has the last expression's value, 3 has a returned thenable settled, 4 has the result copied out.
// The phases of the program's frame: 0 starts, 1 has a statement's result, 2 has the body's value, 3 has it adopted,
// 4 has it copied out, and `ENDED` has ended the program, its outcome recorded on the machine.
const ENDED = 5
function programStep(task: MachineTask, frame: Frame, node: Program, input: unknown) {
const slots = frame.slots
const body = node.body
let phase = frame.phase
if (phase === ENDED) return undefined
let value: Value = undefined
let index = 0
if (phase === 0) {
@@ -930,9 +935,12 @@ function programStep(task: MachineTask, frame: Frame, node: Program, input: unkn
}
if (phase === 3) {
frame.phase = 4
return task.native(toBoundary(task.ctx, input as Value), node, false)
const copied = task.native(toBoundary(task.ctx, input as Value), node, false)
if (copied === PENDING) return PENDING
input = copied
}
return input
task.machine.outcome = normal(input)
return undefined
}
const outsideLoop = (result: StatementResult, statement: Statement | ModuleDeclaration) => {
@@ -941,4 +949,17 @@ const outsideLoop = (result: StatementResult, statement: Statement | ModuleDecla
}
}
export const ProgramKind = kind("Program", programStep)
/**
* The program's body, the first job. It is an async boundary: an `await` in it parks the whole body, and how the body
* ends, normally or by a throw, is the program's outcome.
*/
export const ProgramKind = kind("Program", programStep, {
unwind: (task, frame, error) => {
if (frame.phase === ENDED) return false
task.machine.outcome = abrupt(error)
frame.phase = ENDED
return true
},
cut: () => normal(undefined),
counts: () => true,
})
+97 -10
View File
@@ -3,24 +3,40 @@ import type { Interpreter } from "../interpreter/interpreter.js"
import type { AstNode } from "../interpreter/model.js"
import type { Value } from "../interpreter/objects.js"
import type { ScopeStack } from "../interpreter/scope.js"
import { type Eval, type Signal, Slice } from "../interpreter/signals.js"
import {
abrupt,
Await,
Call,
type Completion,
Enter,
type Eval,
normal,
type Signal,
Slice,
Yield,
} from "../interpreter/signals.js"
import { Frame, type Kind, PASS, PENDING, type Pending } from "./frame.js"
import { dispatch, native } from "./calls.js"
import { boundaryOf, dispatch, native, nativeFrame } from "./calls.js"
import type { Machine } from "./machine.js"
/** Steps run by every machine task in this process, so tests can see that a program ran on the machine. */
export const stats = { steps: 0 }
/**
* A stack of machine frames and the loop that steps it. To the runner it is an activation body, like interpreter
* work: `next` and `throw` run it until it finishes or needs the driver (`Await`, `Yield`, a host call, a slice, or a
* call it cannot make on its own stack), and the driver's answer resumes the frame that asked.
* A stack of machine frames and the loop that steps it. The machine runs every job on its root task. A generator's
* body is a task of its own for now, run by a native frame on the stack that resumes it; to that frame it answers
* `next` and `throw` like interpreter work.
*
* The loop answers what frames ask for on the stack itself: an `await` cuts the stack at the innermost async boundary
* and parks the frames it cut on the promise, a `yield` splits it at the innermost generator body, and a body a
* built-in starts (`Call`) or a generator resumes (`Enter`) is pushed. What it cannot answer (host work, a slice, or an
* `await` or `yield` with no boundary on this stack) it hands to whoever runs it.
*/
export class MachineTask {
readonly stack: Array<Frame> = []
/** The scope chain of the frame running now. */
scopes: ScopeStack
/** What the running frame asked the driver for; the step loop hands it over once the frame parks. */
/** What the running frame asked for; the step loop answers it once the frame parks. */
signal: Signal | undefined = undefined
/** The host should get a turn at the next step boundary. */
slice = false
@@ -103,15 +119,28 @@ export class MachineTask {
return native(this, work, site, locate)
}
/** Asks the driver for `signal`; its answer (or failure) is the result of the frame this pushes. */
/** Asks for `signal`; its answer (or failure) is the result of the frame this pushes. */
request(signal: Signal, node: AstNode | undefined): Pending {
this.signal = signal
this.stack.push(new Frame(passKind, node, PASS, this.scopes, []))
return PENDING
}
private drive(ok: boolean, input: unknown): IteratorResult<Signal, Value> {
/** Puts frames taken off a stack back on this one, counting their calls again. */
enter(frames: ReadonlyArray<Frame>): void {
for (const frame of frames) {
this.stack.push(frame)
if (frame.kind.counts?.(frame)) this.machine.depth++
}
}
/**
* Runs the stack from the top frame with `input` until it empties (its last result) or a frame asks for something
* this stack cannot answer (the signal). A throw that unwinds past the bottom frame is thrown.
*/
drive(ok: boolean, input: unknown): IteratorResult<Signal, Value> {
const stack = this.stack
const machine = this.machine
let value = input
while (true) {
stats.steps++
@@ -130,6 +159,7 @@ export class MachineTask {
}
}
stack.pop()
if (frame.kind.counts?.(frame)) machine.depth--
}
ok = true
value = undefined
@@ -151,6 +181,7 @@ export class MachineTask {
}
if (out !== PENDING) {
stack.pop()
if (frame.kind.counts?.(frame)) machine.depth--
value = out
continue
}
@@ -158,7 +189,11 @@ export class MachineTask {
const signal = this.signal
if (signal !== undefined) {
this.signal = undefined
return { done: false, value: signal }
const answer = this.answer(signal)
if (answer === undefined) return { done: false, value: signal }
ok = answer.ok
value = answer.ok ? answer.value : answer.error
continue
}
if (this.slice) {
this.slice = false
@@ -166,7 +201,59 @@ export class MachineTask {
}
}
}
// Answers a signal on this stack, giving what the top frame continues with; undefined hands the signal on.
private answer(signal: Signal): Completion | undefined {
const machine = this.machine
if (signal instanceof Call) {
this.stack.push(nativeFrame(this.scopes, signal.body, signal.boundary, true))
machine.depth++
if (machine.tick()) this.slice = true
return normal(undefined)
}
if (signal instanceof Enter) {
this.enter(signal.frames)
if (machine.tick()) this.slice = true
return signal.input
}
if (signal instanceof Await) return this.await(signal)
if (signal instanceof Yield) {
const stack = this.stack
for (let index = stack.length - 1; index >= 0; index--) {
const boundary = boundaryOf(stack[index]!)
if (boundary?.generator) return boundary.yielded(signal.value, () => this.split(index))
}
}
return undefined
}
// Cuts the stack at the innermost async boundary and parks the frames cut off on the awaited promise; the frame
// below the boundary continues with what the boundary gives it (an async function's promise, say).
private await(signal: Await): Completion | undefined {
const stack = this.stack
for (let index = stack.length - 1; index >= 0; index--) {
const frame = stack[index]!
const cut = frame.kind.cut?.(frame)
if (cut === undefined) continue
let promise
try {
promise = this.machine.promiseResolve(signal.value)
} catch (error) {
return abrupt(error)
}
this.machine.park(this.split(index), promise, signal.node, cut.ok ? (cut.value as Value) : undefined)
return cut
}
return undefined
}
// Takes the frames from `index` up off the stack; their calls no longer count toward its depth.
private split(index: number): Array<Frame> {
const frames = this.stack.splice(index)
for (const frame of frames) if (frame.kind.counts?.(frame)) this.machine.depth--
return frames
}
}
// A frame waiting on the driver's answer to a request; the answer passes straight to the frame below.
// A frame waiting on the answer to a request; the answer passes straight to the frame below.
const passKind: Kind = { name: "Request", step: (_task, _frame, _node, input) => input }
+1 -1
View File
@@ -1,4 +1,4 @@
import type { Eval } from "../interpreter/runner.js"
import type { Eval } from "../interpreter/signals.js"
import { constructor, type Method, methods, prototypeFrom, receiver } from "../interpreter/native.js"
import { checkArrayLength, checkStringLength, MAX_ARRAY_LENGTH } from "../interpreter/limits.js"
import { invalidData, IteratorSymbol, rangeError, typeError } from "../interpreter/model.js"
+1 -1
View File
@@ -1,4 +1,4 @@
import type { Eval } from "../interpreter/runner.js"
import type { Eval } from "../interpreter/signals.js"
import { checkArrayLength, checkStringLength } from "../interpreter/limits.js"
import { constructor, methods, prototypeFrom, receiver, requiresNew } from "../interpreter/native.js"
import { IteratorSymbol, rangeError, syntaxError, typeError } from "../interpreter/model.js"
+1 -1
View File
@@ -1,4 +1,4 @@
import type { Eval } from "../interpreter/runner.js"
import type { Eval } from "../interpreter/signals.js"
import { constructor, fn, type Method, methods, prototypeFrom, receiver, requiresNew } from "../interpreter/native.js"
import { invalidData, IteratorSymbol, typeError } from "../interpreter/model.js"
import {
+1 -1
View File
@@ -1,4 +1,4 @@
import type { Eval } from "../interpreter/runner.js"
import type { Eval } from "../interpreter/signals.js"
import { constructor, type Method, methods, prototypeFrom, receiver } from "../interpreter/native.js"
import { rangeError } from "../interpreter/model.js"
import { DateObj, Obj, coerceToNumber, coerceToString, type Value } from "../interpreter/objects.js"
+1 -1
View File
@@ -1,4 +1,4 @@
import type { Eval } from "../interpreter/runner.js"
import type { Eval } from "../interpreter/signals.js"
import { constructor, methods, prototypeFrom, receiver, requiresNew } from "../interpreter/native.js"
import { IteratorSymbol, typeError } from "../interpreter/model.js"
import {
+1 -1
View File
@@ -16,7 +16,7 @@ import {
type Value,
} from "../interpreter/objects.js"
import { describeValue } from "../interpreter/references.js"
import { type Eval, Interruption } from "../interpreter/runner.js"
import { type Eval, Interruption } from "../interpreter/signals.js"
const finished: Step = { done: true, value: undefined }
+1 -1
View File
@@ -1,4 +1,4 @@
import type { Eval } from "../interpreter/runner.js"
import type { Eval } from "../interpreter/signals.js"
import { methods } from "../interpreter/native.js"
import { applyCollectionCallback } from "../interpreter/callback.js"
import type { Interpreter } from "../interpreter/interpreter.js"
+1 -1
View File
@@ -3,7 +3,7 @@ import { typeError } from "../interpreter/model.js"
import { Obj, coerceToNumber } from "../interpreter/objects.js"
import { preserveConsumerError, withPrimitives } from "../interpreter/callback.js"
import type { Interpreter } from "../interpreter/interpreter.js"
import type { Eval } from "../interpreter/runner.js"
import type { Eval } from "../interpreter/signals.js"
// Bun exposes ES2026 Math.sumPrecise before TypeScript's standard library types.
declare global {
+1 -1
View File
@@ -1,4 +1,4 @@
import type { Eval } from "../interpreter/runner.js"
import type { Eval } from "../interpreter/signals.js"
import { constructor, methods, receiver } from "../interpreter/native.js"
import { type AstNode, AsyncIteratorSymbol, invalidData, IteratorSymbol, typeError } from "../interpreter/model.js"
import {
+1 -1
View File
@@ -1,4 +1,4 @@
import type { Eval } from "../interpreter/runner.js"
import type { Eval } from "../interpreter/signals.js"
import { constructor, fn, type Impl, type Method, methods } from "../interpreter/native.js"
import { checkArrayLength, checkStringLength } from "../interpreter/limits.js"
import { invalidData, IteratorSymbol, rangeError, typeError } from "../interpreter/model.js"
+1 -1
View File
@@ -1,4 +1,4 @@
import type { Eval } from "../interpreter/runner.js"
import type { Eval } from "../interpreter/signals.js"
import { constructor, fn, type Method, methods, prototypeFrom, receiver, requiresNew } from "../interpreter/native.js"
import { IteratorSymbol, PendingThrow, typeError, uriError } from "../interpreter/model.js"
import {
+1 -1
View File
@@ -91,7 +91,7 @@ describe("the host stays in control", () => {
}),
)
expect(result).toMatchObject({ ok: true, value: 999_999 })
// The loop takes well over 10 ms anywhere, and the runner yields to the host every millisecond; a job that kept
// The loop takes well over 10 ms anywhere, and the machine yields to the host every millisecond; a job that kept
// the thread for its whole run would let the counter tick at most a couple of times around it.
expect(ticks).toBeGreaterThan(10)
})
+98 -38
View File
@@ -2,59 +2,65 @@ import { describe, expect, test } from "bun:test"
import { Glob } from "bun"
import { Effect, Schema } from "effect"
import { CodeMode, Tool } from "../src/index.js"
import { parseProgram } from "../src/interpreter/execute.js"
import { Interpreter } from "../src/interpreter/interpreter.js"
import { createBuiltins } from "../src/interpreter/intrinsics.js"
import { normal } from "../src/interpreter/signals.js"
import { Frame } from "../src/machine/frame.js"
import type { Machine } from "../src/machine/machine.js"
import { stats } from "../src/machine/task.js"
import { ToolRuntime } from "../src/tool-runtime.js"
// The machine evaluator (`src/machine`) runs programs as explicit frames. These run each program on both evaluators,
// check the machine really ran it, and check both give the same result.
// The machine (`src/machine`) runs programs as explicit frames, and keeps the jobs, promises, and host calls they wait
// on as data. The Effect driver only does what the machine's stops ask.
const runtime = CodeMode.make({
tools: {
echo: Tool.make({
description: "Echo a value",
input: Schema.Struct({ value: Schema.Number }),
output: Schema.Number,
execute: ({ value }) => Effect.succeed(value),
}),
},
})
const run = async (code: string, evaluator: "machine" | "legacy") => {
const previous = process.env.CODEMODE_EVALUATOR
process.env.CODEMODE_EVALUATOR = evaluator
try {
return await Effect.runPromise(runtime.execute(code))
} finally {
if (previous === undefined) delete process.env.CODEMODE_EVALUATOR
else process.env.CODEMODE_EVALUATOR = previous
}
const runtimeTools = {
echo: Tool.make({
description: "Echo a value",
input: Schema.Struct({ value: Schema.Number }),
output: Schema.Number,
execute: ({ value }) => Effect.succeed(value),
}),
}
const both = async (code: string) => {
const legacy = await run(code, "legacy")
const before = stats.steps
const machine = await run(code, "machine")
expect(stats.steps).toBeGreaterThan(before)
expect(machine).toEqual(legacy)
return machine
}
const runtime = CodeMode.make({ tools: runtimeTools })
const run = (code: string) => Effect.runPromise(runtime.execute(code))
const value = async (code: string) => {
const result = await both(code)
const before = stats.steps
const result = await run(code)
expect(stats.steps).toBeGreaterThan(before)
if (!result.ok) throw new Error(`expected success, got ${result.error.kind}: ${result.error.message}`)
return result.value
}
const error = async (code: string) => {
const result = await both(code)
const result = await run(code)
if (result.ok) throw new Error(`expected failure, got value ${JSON.stringify(result.value)}`)
return result.error
}
describe("machine evaluator", () => {
test("runs programs as frames, and the generator evaluator runs none", async () => {
const before = stats.steps
await run(`return 1 + 2`, "legacy")
expect(stats.steps).toBe(before)
// A machine for `code`, stepped by hand instead of by the Effect driver.
const machineFor = (code: string) => {
const parsed = parseProgram(code)
if (!parsed.ok) throw new Error(parsed.error.message)
const tools = ToolRuntime.make(ToolRuntime.prepare(runtimeTools), undefined, {})
const ctx = new Interpreter({ tools, builtins: createBuiltins() })
ctx.start(parsed.source)
return ctx.machine
}
// The next stop that is not a slice.
const stop = (machine: Machine) => {
for (;;) {
const next = machine.run()
if (next.kind !== "slice") return next
}
}
describe("machine", () => {
test("runs programs as frames", async () => {
expect(await value(`const f = (n) => (n < 2 ? n : f(n - 1) + f(n - 2)); return f(12)`)).toBe(144)
})
@@ -151,12 +157,66 @@ describe("machine evaluator", () => {
])
})
test("runaway recursion stops at the same depth with the same location", async () => {
test("runaway recursion stops with the location of the call that overflowed", async () => {
expect((await error(`const f = (n) => f(n + 1); return f(0)`)).message).toBe(
"RangeError: Maximum call stack size exceeded (line 1, col 18)",
)
})
test("concurrent tool calls stop the machine once, with every call in one batch", () => {
const machine = machineFor(`return await Promise.all([1, 2, 3].map((value) => tools.echo({ value })))`)
const started = stop(machine)
if (started.kind !== "host") throw new Error(`expected a host stop, got ${started.kind}`)
expect(
started.calls.map((call) => ({ request: call.request, blocking: call.blocking, status: call.status })),
).toEqual(
[1, 2, 3].map((value) => ({
request: { kind: "tool", path: ["echo"], args: [{ value }] },
blocking: false,
status: "inFlight",
})),
)
// Nothing else can run until host work completes.
expect(stop(machine)).toEqual({ kind: "host", calls: [] })
for (const [index, call] of [...started.calls.entries()].reverse())
machine.complete(call.id, normal((index + 1) * 10))
expect(stop(machine)).toEqual({ kind: "done", completion: normal([10, 20, 30]) })
expect(started.calls.map((call) => call.status)).toEqual(["completed", "completed", "completed"])
})
test("a blocking host call stops the job that made it until it completes", () => {
const machine = machineFor(`const found = search({ query: "echo" }); return found.items.length`)
const started = stop(machine)
if (started.kind !== "host") throw new Error(`expected a host stop, got ${started.kind}`)
expect(started.calls.map((call) => [call.request.kind, call.blocking])).toEqual([["search", true]])
expect(stop(machine)).toEqual({ kind: "host", calls: [] })
machine.complete(started.calls[0]!.id, normal({ items: [1, 2], remaining: 0, next: null }))
expect(stop(machine)).toEqual({ kind: "done", completion: normal(2) })
})
test("await parks the frames it cuts off the stack as data on the promise", () => {
const machine = machineFor(`
const inner = async (x) => { const y = x + 1; return await new Promise(() => {}) }
const outer = async () => [await inner(1)]
return await outer()
`)
const stuck = stop(machine)
expect(stuck.kind).toBe("stuck")
const slices = [...machine.parked.keys()]
expect(slices.length).toBe(3)
for (const frames of slices) {
expect(Array.isArray(frames)).toBe(true)
for (const frame of frames) {
expect(frame).toBeInstanceOf(Frame)
expect(frame.kind.opaque).toBeUndefined()
}
}
// Each slice starts at its async boundary: the program's body, or an async function's call.
expect(slices.map((frames) => frames[0]!.kind.name).sort()).toEqual(["Call", "Call", "Program"])
expect(machine.depth).toBe(0)
expect(machine.root.stack).toEqual([])
})
test("the machine does not import Effect", async () => {
const files = await Array.fromAsync(new Glob("src/machine/*.ts").scan({ cwd: `${import.meta.dir}/..` }))
expect(files.length).toBeGreaterThan(0)
+1 -1
View File
@@ -1344,7 +1344,7 @@ describe("promise construction", () => {
})
describe("jobs run to completion", () => {
// The runner pauses a long job to let the host run; the paused job still finishes before any other job starts.
// The machine pauses a long job to let the host run; the paused job still finishes before any other job starts.
test("updates to shared state between awaits are not lost", async () => {
expect(
await value(`
-2
View File
@@ -1,5 +1,4 @@
import { describe, expect, test } from "bun:test"
import { Context } from "effect"
import { parseProgram } from "../src/interpreter/execute.js"
import { Interpreter } from "../src/interpreter/interpreter.js"
import { createBuiltins } from "../src/interpreter/intrinsics.js"
@@ -14,7 +13,6 @@ import { nodeId, sourceOf } from "../src/interpreter/source.js"
const interpreter = () =>
new Interpreter<never>({
tools: ToolRuntime.make(ToolRuntime.prepare<never>({}), undefined, {}),
services: Context.empty(),
builtins: createBuiltins(),
})