Skip to main content

run

Function run 

Source
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.