Documentation
¶
Overview ¶
Package jsloop holds the ordering primitives that stand in for the one JavaScript thread Pi runs on. Pi's callbacks, RPC writes and extension handlers run on one event loop, so which of two things happens first is a language fact that Pi never writes down. PiG runs the same code on goroutines, threads and processes, and each place that touches the extension boundary has to state the order. Each type here names one of those orders; do not write another goroutine, mutex or channel pattern for it.
extensions/sdk/internal/jsloop is a verbatim copy for the SDK module, which cannot import the root module. TestSDKCopy keeps the two identical.
Index ¶
- func WithTurns(ctx context.Context, turns *Turns) context.Context
- type Lane
- type Loop
- func (l *Loop) Begin()
- func (l *Loop) End()
- func (l *Loop) Hops(n int, fn func())
- func (l *Loop) Idle() <-chan struct{}
- func (l *Loop) Macrotask(fn func())
- func (l *Loop) Microtask(fn func())
- func (l *Loop) Microtasks(fns ...func())
- func (l *Loop) Queued() (microtasks, macrotasks int)
- func (l *Loop) SetBatchObserver(fn func(open bool))
- type Place
- type SettleGate
- type SettleSlot
- type Turns
- func (t *Turns) Arm(ctx context.Context) (end func())
- func (t *Turns) Chain() (end func())
- func (t *Turns) Command() (end func())
- func (t *Turns) Held() int
- func (t *Turns) Macrotask(fn func())
- func (t *Turns) MacrotaskDone(fn func(done func()))
- func (t *Turns) MacrotaskDoneFor(owner any, fn func(done func()))
- func (t *Turns) ObserveDefer(fn func(deferring bool), applied func(ctx context.Context))
- func (t *Turns) Release(owner any)
- func (t *Turns) Tick(origin string, fn func(done func()))
- func (t *Turns) Ticked(toolCallID string)
- func (t *Turns) ToolStarted(toolCallID string)
- func (t *Turns) Turn()
- func (t *Turns) Wait() (done func())
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Lane ¶
type Lane struct {
// contains filtered or unexported fields
}
Lane keeps the calls of one destination in source order up to the point each issues its request. Pi runs the synchronous prefix of every call of `Promise.all(xs.map(f))` in source order, so f(a) issues its request before f(b). Go starts a goroutine per call and the scheduler may run the later one first, so the caller reserves each call's place in source order before it starts any goroutine, and a call issues its request only after every earlier place was released.
The zero value is ready to use.
func (*Lane) Reserve ¶
Reserve takes the next place in the lane. It must run in source order, before any of the calls runs.
func (*Lane) ReserveInto ¶
ReserveInto is Reserve for a caller that holds the place's storage, such as a field of a struct it allocates anyway: p must be the zero Place, and it is the new place.
type Loop ¶
type Loop struct {
// contains filtered or unexported fields
}
Loop serializes callbacks the way one JavaScript thread runs them, with Node's two queues. A microtask is the continuation of an await that settles without the event loop turning. A macrotask is the continuation of an await whose work ran elsewhere (Node delivers it from a later event-loop task), a timer, or a new input line. One callback runs at a time. Every queued microtask, including those a callback queues, runs before the next macrotask, so a goroutine that finishes early cannot overtake a microtask the running callback queues later.
A producer that finds the loop idle runs the queued callbacks on its own goroutine; there is no drainer goroutine. A busy loop owns the queued work, and its producers never block, because the running callback can be joining the operation that just completed. A callback must not wait for anything the loop will later produce: work that has to wait runs on its own goroutine and re-enters with Macrotask when it is done.
An input batch holds the loop between Begin and End: callbacks queued meanwhile run when End drains them.
The zero value is ready to use.
func (*Loop) Begin ¶
func (l *Loop) Begin()
Begin enters the loop for an input batch: it waits for the callback that is running, and holds the loop until End.
func (*Loop) End ¶
func (l *Loop) End()
End drains the queued callbacks with the loop held and then leaves it. Unlocking execution while mu is still held makes idle publication atomic with producer admission; no callback can be stranded between the empty check and the unlock. Callbacks can queue more work without recursively acquiring execution.
func (*Loop) Idle ¶
func (l *Loop) Idle() <-chan struct{}
Idle reports when the admitted input and its queued callbacks drain. It does not join suspended commands, which may still be waiting for input.
func (*Loop) Macrotask ¶
func (l *Loop) Macrotask(fn func())
Macrotask queues the continuation of work that completed outside the loop. It runs after every queued microtask, and after the microtasks that a callback it ran queues.
func (*Loop) Microtask ¶
func (l *Loop) Microtask(fn func())
Microtask queues the continuation of an await that settles without the event loop turning.
func (*Loop) Microtasks ¶
func (l *Loop) Microtasks(fns ...func())
Microtasks queues fns, in order, as microtasks.
func (*Loop) Queued ¶
Queued reports how many microtasks and macrotasks wait to run. A test uses it to know that a goroutine delivered its completion.
func (*Loop) SetBatchObserver ¶
SetBatchObserver registers fn, which runs with true once Begin holds the loop and with false once the loop drained and left the batch End ends. A callback queued by a producer, with no Begin, is no batch. D189: the batch is Pi's iteration that reads one stdin chunk, whose microtasks no timer callback interleaves with.
type Place ¶
type Place struct {
// contains filtered or unexported fields
}
Place is one call's reservation in a Lane. A nil *Place is no reservation: Wait, Release and Pass do nothing.
A place is one allocation and makes no channel unless a caller has to block on it: the next place's Wait finds an already released place with an atomic load. Each place holds the place it waits for only until it has waited or been released, so a long-lived lane keeps no chain of places.
func After ¶
After returns a place that waits for previous, which may be nil. It is Reserve for a caller that keeps the tail itself, for example one lane per key in a map it already guards: the call must run in source order, under the caller's own lock.
func (*Place) Pass ¶
func (p *Place) Pass()
Pass waits for the earlier places and then hands this one on, so a call that ends without issuing its request cannot let a later call issue before an earlier one. It is idempotent.
type SettleGate ¶
type SettleGate struct {
// contains filtered or unexported fields
}
SettleGate orders actions that several goroutines run after waiting on an event loop's answers, in the order the answers arrived. Pi runs everything on one thread: when two awaits settle back to back, their continuations run in settle order, and nothing a continuation does overtakes an earlier one. Go wakes the goroutines that wait on those answers in no particular order: a sender that wakes two goroutines in a row runs the second first, so the answers' order is lost between the arrival and the continuation unless the order is recorded where the answers arrive and kept where the continuations act (SettleSlot). A continuation acts in two steps: it starts, and runs to its first await (Begin), and it finishes (Run). Pi starts the continuations of promises that settle back to back in settle order and lets each run on after its first await while the next starts, so a slot's start waits only for the earlier slots' starts, and its action waits for their actions.
The zero value is ready to use.
func (*SettleGate) NewSlot ¶
func (g *SettleGate) NewSlot() *SettleSlot
NewSlot returns a slot that holds no place until it settles.
func (*SettleGate) SetParkedHook ¶
func (g *SettleGate) SetParkedHook(fn func())
SetParkedHook has fn run each time a Run starts to wait for an earlier slot, so a test knows a caller is held without timing. Set it before the gate is used.
type SettleSlot ¶
type SettleSlot struct {
// contains filtered or unexported fields
}
SettleSlot is one waiter's place in a SettleGate.
func (*SettleSlot) Begin ¶
func (s *SettleSlot) Begin() (began func())
Begin returns when every slot that settled before this one began, and the function that reports this slot begun, which lets the slots behind it begin. The caller starts its continuation between the two, as Pi runs a continuation to its first await before the next one starts, and calls began when that point is reached. began is idempotent, and Close calls it, so a slot that never begins cannot hold the ones behind it. A slot that no reader settled settles when Begin starts.
func (*SettleSlot) Close ¶
func (s *SettleSlot) Close()
Close ends the slot: a slot that settled and never ran stops holding up the slots behind it. It does nothing for a slot that ran.
func (*SettleSlot) Gate ¶
func (s *SettleSlot) Gate() *SettleGate
Gate returns the gate the slot belongs to.
func (*SettleSlot) Run ¶
func (s *SettleSlot) Run(action func())
Run runs action once every slot that settled before this one finished. A slot that no reader settled settles when Run starts, so waiters whose answers carry no order keep the order they reach Run in. Each slot runs one action.
func (*SettleSlot) Settle ¶
func (s *SettleSlot) Settle()
Settle gives the slot its place after every slot that already settled. The goroutine that reads the answer calls it before it hands the answer to the waiter, so the order is the order the answers were read in. It does nothing for a slot that settled.
type Turns ¶
type Turns struct {
// contains filtered or unexported fields
}
Turns models when Pi's event loop gets to run the callbacks of timers and immediates (D189). Pi runs the agent on the thread that runs the extensions, so a callback an extension queued with setTimeout or setImmediate cannot run while the agent runs a chain of microtasks; it runs when the chain awaits real work (a model response, a tool's I/O, a dialog, a child process), or when the chain ends and the loop is idle.
A chain is the agent's run, from agent_start to the end of agent_settled. A wait is a stretch of the chain that awaits real work: while one is open the loop turns, so a callback runs at once. A turn is one completion of real work, such as a chunk of a model response. A callback that finds the chain running and no wait open is held, in arrival order, until a turn, a wait, or the end of the chain. Outside a chain a callback runs at once.
The extension host holds the host calls an extension runtime marks as made from a timer or an immediate (CallPayload.Timer), because a separate process cannot wait for the host's loop itself.
A nil *Turns holds nothing: callbacks run at once.
func (*Turns) Arm ¶
Arm opens the Turns command of a stdin command and returns once every extension runtime applied the hold, so the command's first event reaches no runtime that still runs its timer callbacks: Pi's loop runs nothing between reading the command and the end of its microtasks, and the runtimes are other processes. The caller must not hold the loop that runs the command, since a runtime may be waiting for it. A runtime that ended, or ctx's end, stops the wait. end is the function Command returns.
func (*Turns) Chain ¶
func (t *Turns) Chain() (end func())
Chain says the running work is a chain of microtasks, and returns the function that ends it. Callbacks wait while any chain runs and no wait is open.
func (*Turns) Command ¶
func (t *Turns) Command() (end func())
Command says the running work is the iteration of Pi's loop that handles one stdin command, and returns the function that ends it. While a command runs and no wait is open, a timer or immediate callback an extension runtime queued must not run, since Pi's loop runs nothing else between the command's microtasks and its response; ObserveDefer tells the runtimes. The calls of such a callback cannot be held, because the runtime may wait for their answers.
func (*Turns) Macrotask ¶
func (t *Turns) Macrotask(fn func())
Macrotask runs fn, the work of a timer or immediate callback, once the loop would run it: at once when no chain runs or a wait is open, and otherwise at the next turn, wait or end of the chain. Callbacks run in the order they arrived. fn must not block: a producer calls Macrotask from the goroutine that read the call.
func (*Turns) MacrotaskDone ¶
func (t *Turns) MacrotaskDone(fn func(done func()))
MacrotaskDone is Macrotask for work whose effect is written after fn returns: fn calls done once it is. The call that releases the callback waits for done before it returns, so the output of the callback precedes whatever Pi's chain does next.
func (*Turns) MacrotaskDoneFor ¶
MacrotaskDoneFor is MacrotaskDone for a callback held for owner: Release(owner) runs it before the loop turns. An owner is a runtime that cannot say whether one of its handlers waits for the callback's call (a Go, Rust or Python extension), so the handler's own wait is a turn the host cannot see.
func (*Turns) ObserveDefer ¶
ObserveDefer registers fn, which runs with true when the timer callbacks of an extension runtime must wait (a command runs and no wait is open) and with false when they may run. fn runs in the order of the changes. applied, when it is not nil, returns once every runtime applied the changes fn made (Arm waits for it).
func (*Turns) Release ¶
Release runs the callbacks held for owner now, in the order they arrived, and returns once their effect is written. The host calls it when a request starts on the owner's connection: the request's handler may await one of those callbacks' calls, which no turn of the loop would run while the handler is pending.
func (*Turns) Tick ¶
Tick runs fn, which must call done once its effect is written, as the work of a process.nextTick callback, or of a timer callback that runs while a sibling tool awaits, at the next Ticked of origin: Pi runs such a callback right after the tool_execution_end of the tool that queued it, before the chain goes on. origin is the tool call that queued the callback, "" when the callback was not queued by a tool call, which a Ticked of any tool call releases. It runs at once when no chain runs. A callback that waits for Ticked also runs at the next turn, wait or end of the chain, behind the ticks already held.
A callback whose tool call's boundary already passed runs at once: the runtime that made the call says the loop turns (a sibling tool awaits, or the tool's own tick queue runs), and the callback ran in Pi right after the tool_execution_end that came before the call. The runtime is another process, so the call can reach the host after that event, and the time it takes decides nothing about the call's place. It runs behind the callbacks held before it, which a turn of the loop runs with it, and it does not wait for the boundary of another tool call.
func (*Turns) Ticked ¶
Ticked says the tick boundary of the tool call toolCallID passed, which is the written tool_execution_end of the call: the tick callbacks it queued, and those no tool call queued, run. The held timer callbacks keep waiting for a turn, and so do the ticks of a tool call that has not ended.
func (*Turns) ToolStarted ¶
ToolStarted says the tool call toolCallID starts, so a call that reuses its identifier later in the chain has its own tick boundary ahead.