std.process

Child processes for tasks: start a program, write to its stdin, readSomeOut/ readSomeErr its streams, wait for its exit code — every waiting form yielding to the scheduler instead of blocking the thread.

The silent forms answer whether (null/false); the OrThrow twins say why with an IoError — NotFound when the program does not exist, PermissionDenied when it may not be run. The streams speak readSome's three truths: bytes are bytes, an EMPTY array is the stream being done (EOF), and null is a failure.

Carries processAccess, its own capability bit: starting programs is a new power, not an osAccess refinement.

Child alias

pub type Child = int

A started child process. Opaque: it is issued here, never assembled.

stdlib/std/process.lyr:36

start function

pub fn start(program: string, args: string[]): ?Child

Starts program with args, streams piped. null when it cannot start — startOrThrow says why, NotFound being the usual answer.

stdlib/std/process.lyr:66

startOrThrow function

pub fn startOrThrow(program: string, args: string[]): Child throws IoError

start, with the reason when the program cannot start.

stdlib/std/process.lyr:75

readSomeOut function

pub fn readSomeOut(child: Child, max: int): ?uint8[]

Waits for bytes on the child's standard output and reads up to max of them. Three truths in one answer: bytes are bytes, an EMPTY array is the stream being done (EOF), and null is a failure — readSomeOutOrThrow says which.

A max of zero or less PANICS: an empty answer already means EOF, so there is no honest value to hand back for it.

stdlib/std/process.lyr:89

readSomeOutOrThrow function

pub fn readSomeOutOrThrow(child: Child, max: int): uint8[] throws IoError

readSomeOut, with the reason when the stream broke. EOF stays the empty array.

stdlib/std/process.lyr:94

readSomeErr function

pub fn readSomeErr(child: Child, max: int): ?uint8[]

readSomeOut, for the child's standard error.

stdlib/std/process.lyr:103

readSomeErrOrThrow function

pub fn readSomeErrOrThrow(child: Child, max: int): uint8[] throws IoError

readSomeErr, with the reason when the stream broke.

stdlib/std/process.lyr:108

write function

pub fn write(child: Child, bytes: uint8[]): bool

Hands bytes to the child's standard input. The write is queued and drained in the background; false once the child's stdin broke — a child that exited without reading everything is the usual way.

stdlib/std/process.lyr:135

writeOrThrow function

pub fn writeOrThrow(child: Child, bytes: uint8[]): void throws IoError

write, with the reason when the child's stdin broke.

stdlib/std/process.lyr:140

closeStdin function

pub fn closeStdin(child: Child): void

Closes the child's standard input once everything queued is written — EOF is how a filter learns it has everything.

stdlib/std/process.lyr:148

wait function

pub fn wait(child: Child): int

Waits until the child has exited and answers its exit code.

stdlib/std/process.lyr:153

kill function

pub fn kill(child: Child): void

Ends the child now, without appeal. The exit code wait then reports is the kill's, not the program's.

stdlib/std/process.lyr:162

close function

pub fn close(child: Child): void

Releases the child's resources — buffers, pipes, the notify descriptor. Closing twice closes once; a running child is NOT stopped, only disowned.

stdlib/std/process.lyr:168