Documentation
¶
Overview ¶
Waiting for a child's output pipes after it exits.
Ports packages/coding-agent/src/utils/child-process.ts waitForChildProcess.
Index ¶
Constants ¶
const Grace = 100 * time.Millisecond
Grace mirrors upstream EXIT_STDIO_GRACE_MS.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Hooks ¶
type Hooks struct {
// BeforeRead runs in each reader before its first read.
BeforeRead func()
// AfterData runs in a reader once onData has taken a chunk, with the chunk
// onData was lent. A test learns from it that the reader has consumed what
// a writer wrote.
AfterData func(index int, chunk []byte)
// GraceTimer replaces the wall-clock timer that measures the grace, so a
// test decides when the grace elapses instead of racing a writer against
// host load.
GraceTimer func() IdleTimer
// GraceExpired runs each time the idle grace elapses, before Wait asks
// whether the pipes can still produce output.
GraceExpired func()
// BeforeDeliver runs in a reader once it has taken bytes from a pipe,
// before it hands them to onData: the bytes are out of the pipe and in
// no one's hands yet.
BeforeDeliver func()
// AfterPeek runs in a reader that waits for its turn, once it has asked
// whether the pipe of the earlier reader at index earlier holds bytes and
// before it asks whether that reader has taken bytes it has not
// delivered. That reader can take the pipe's bytes between the two
// questions; a test plays that reader here.
AfterPeek func(earlier int)
// Released runs in Wait once the grace released the pipes and Wait closed
// them, before it waits for the readers to stop.
Released func()
}
Hooks order the reader, the child's exit and the grace in tests without sleeps. Start takes them by pointer, nil outside tests, so they add nothing to a production Pipes.
type IdleTimer ¶
type IdleTimer struct {
// Expired delivers once Grace has elapsed with no chunk.
Expired <-chan time.Time
// Rearm restarts the grace in full. Wait calls it for each chunk that
// arrives after the child exited, and when the grace elapsed while a pipe
// held output that no reader had taken.
Rearm func()
// Stop releases the timer when Wait no longer uses it.
Stop func()
}
IdleTimer is the clock of the grace that Wait measures. Every field is required.
type Pipes ¶
type Pipes struct {
// contains filtered or unexported fields
}
Pipes reads a child's output pipes. Create it with Start before the child runs and call Wait once the child has exited.
func Start ¶
Start reads each file until it fails or ends, calling onData with the index of the file and the bytes read. Calls to onData never overlap. Every chunk a reader has taken from a pipe is delivered, also when Wait released the pipes meanwhile: Wait returns after the readers stopped, so no call outlives it. The chunk is lent for the call: each pipe reads into one buffer of its own, so onData copies what it keeps.
func (*Pipes) Wait ¶
Wait mirrors the post-exit half of upstream waitForChildProcess: once the child has exited, keep reading until every pipe ends, or until no data has arrived on any pipe for Grace (re-armed on every chunk). A descendant that inherited a pipe therefore neither blocks the call nor truncates output it is still writing. Wait then closes the pipes, discards what a held pipe still holds unread when the grace released the wait (a reader that has taken a chunk delivers it), and returns after every reader has stopped. It reports whether every pipe ended.
The grace exists only for a descendant that still holds a pipe, and it measures that holder's silence, not a reader's latency. A reader that a busy machine has not scheduled for a grace has taken nothing yet from a command that exited long before, and the grace must not release the pipe on it: what the exited command wrote is output, as it is for upstream, which keeps reading while a pipe delivers (Pi's regression test for earendil-works/pi#5303 drives the grace with virtual time because host load reorders a real subprocess's writes and the grace timer). So when the grace expires:
- mayHoldOutput reports whether a process can still hold a pipe that the kernel cannot tell Wait about (a Windows job that is empty holds none). If none can, every write end is closed, EOF follows once the readers have drained what the child's tree already wrote, and Wait reads to EOF.
- On Unix the kernel answers for each pipe (pollPipe). A pipe with no write end left ends the same way. A pipe that holds bytes no reader has taken is a reader that fell behind: the grace is armed again, and the readers deliver what the exited command had already written.
- Only a pipe that a process still holds and that holds no unread byte is the quiet holder the grace is for: Wait releases it.