pub fn run(
command: Command,
options: &RunOptions,
) -> Result<ChildFinished, RunError>Expand description
Runs command with the settings in options and returns how it ended and
what it printed.
The run sets the command’s standard streams, starts it in the scope of
RunOptions::scope, and waits until the child exits, the deadline passes,
the cancel is cancelled, or a stream whose policy stops the child passes
its limit. In the last three cases it stops the child with the
Escalation. Once the child has exited, the run kills what is left of
its group, reaps it, waits on Unix until the group is empty for at most
REAP_GRACE after the exit, and reads its pipes for at most
DRAIN_GRACE more. A run whose deadline passes after the child exited gives the
child’s own exit.
On Unix, for a child that the tool may signal, a run takes at most the
time to its deadline, plus the graces of its escalation, plus
REAP_GRACE, plus DRAIN_GRACE, plus the time that a hook of
RunOptions::around_spawn takes, plus the time that a function of
RunOptions::stdout_copy or RunOptions::stderr_copy blocks, plus
the time that the report of RunOptions::overdue takes. Every
thread that it starts is joined before it returns. On Windows a stop ends the job at once, and a reader waits for
its pipe to close, which ending the job causes for every process in the
job, so a process outside the job that holds a pipe holds the run.
A stream delivered as lines waits for the caller while its queue is
full, and the child then waits on its full pipe. Once the run begins to
stop the child, a full queue drops each line instead. After the child
exits by itself, a full queue waits for the caller until the drain
deadline, half of DRAIN_GRACE after the reap, and then drops each
line while the reader goes on reading the pipe until DRAIN_GRACE
after the reap. Lines::lost says which line a
caller can rely on. The run ends each line queue when it returns, on
every path.
§Errors
Returns RunError::Start when the program cannot be started, a hook
of RunOptions::around_spawn fails, or an Input::File cannot be
duplicated, and
RunError::Run when waiting for, reaping or reading the child fails
a copy function panics, or the report of RunOptions::overdue panics.
The child is stopped and reaped on every path.