jsloop

package
v0.5.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 23, 2026 License: MIT Imports: 4 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func WithTurns

func WithTurns(ctx context.Context, turns *Turns) context.Context

WithTurns returns ctx carrying turns, which the work of the run observes: a completion of real work calls Turn, and a tool's execution is a wait.

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

func (l *Lane) Reserve() *Place

Reserve takes the next place in the lane. It must run in source order, before any of the calls runs.

func (*Lane) ReserveInto

func (l *Lane) ReserveInto(p *Place) *Place

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) Hops

func (l *Loop) Hops(n int, fn func())

Hops runs fn after n microtasks; with n zero it runs it at once.

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

func (l *Loop) Queued() (microtasks, macrotasks int)

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

func (l *Loop) SetBatchObserver(fn func(open bool))

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

func After(previous *Place) *Place

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.

func (*Place) Release

func (p *Place) Release()

Release hands the place on, so the next place's Wait can return. It does not wait for the earlier places, and it is idempotent. It must run however the call ends. A released place waits for nothing: its own Wait returns at once.

func (*Place) Wait

func (p *Place) Wait()

Wait returns when every earlier place was released, provided each earlier call waited before it released (Wait then Release, or Pass). A place released without waiting hands on at once, and the place behind it waits for it, not for the places before it.

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 TurnsFrom

func TurnsFrom(ctx context.Context) *Turns

TurnsFrom returns the Turns ctx carries, or nil.

func (*Turns) Arm

func (t *Turns) Arm(ctx context.Context) (end func())

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) Held

func (t *Turns) Held() int

Held reports how many callbacks wait for a turn or a tick.

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

func (t *Turns) MacrotaskDoneFor(owner any, fn func(done func()))

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

func (t *Turns) ObserveDefer(fn func(deferring bool), applied func(ctx context.Context))

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

func (t *Turns) Release(owner any)

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

func (t *Turns) Tick(origin string, fn func(done func()))

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

func (t *Turns) Ticked(toolCallID string)

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

func (t *Turns) ToolStarted(toolCallID string)

ToolStarted says the tool call toolCallID starts, so a call that reuses its identifier later in the chain has its own tick boundary ahead.

func (*Turns) Turn

func (t *Turns) Turn()

Turn says one completion of real work ran, which is a turn of the loop: the held callbacks run.

func (*Turns) Wait

func (t *Turns) Wait() (done func())

Wait says the chain awaits real work, so the loop turns, and returns the function that ends the wait. Opening a wait releases the held callbacks.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL