Process.Child

handle Child

A running child process.

Killed and reaped when this value dies — on a normal return, at the end of a block, on an Err, and on a panic. Once the handle is gone nothing can poll the process, wait for it, signal it or read its output, so leaving it running would leak something the program can no longer name.

Its output is readable only after it has exited, and then any number of times.

let Child.pid (c: Child): Int

The operating system's identifier for the child, for a caller that has to report it or hand it to something else.

let Child.poll (c: Child): Result[Option[ProcessResult], String]

None means still running. This is the call an application loop makes: it never blocks, so a loop can poll a child, redraw, and poll again.

let Child.wait (c: Child): Result[ProcessResult, String]

Blocks until the child exits. Calling it on a child that has already exited returns the same result again rather than failing.

let Child.wait_timeout (c: Child) (d: Time.Duration): Result[Option[ProcessResult], String]

Waits, but not forever. None means the time ran out and the child is still going. It has NOT been signalled, so the caller can wait again, give up, or terminate it.

let Child.terminate (c: Child): Result[Unit, String]

Asks the child to stop, and returns at once; the child may still be running when this returns, so a caller that needs it gone should wait afterwards.

On Windows this is kill. There is no SIGTERM, so a child that would have cleaned up after a polite request does not get the chance. A program relying on that behaviour is relying on something only POSIX offers.

Signalling a child that has already exited succeeds: the caller asked for it to be gone, and it is.

let Child.kill (c: Child): Result[Unit, String]

Cannot be refused, and gives the child no chance to clean up.