pub struct RunOptions { /* private fields */ }Expand description
The settings of one run: the child’s input, what it keeps of each
output stream, when and how it stops the child, and the child’s scope.
A RunOptions value that delivers a stream as lines serves one run,
because the run ends the line queue when it returns.
The default reads nothing, keeps nothing, has no deadline and no cancel, kills at once when it stops the child, and starts the child in a group of its own.
Implementations§
Source§impl RunOptions
impl RunOptions
Sourcepub fn stdout(self, capture: Capture) -> Self
pub fn stdout(self, capture: Capture) -> Self
Sets what the run keeps of the child’s standard output.
Sourcepub fn stderr(self, capture: Capture) -> Self
pub fn stderr(self, capture: Capture) -> Self
Sets what the run keeps of the child’s standard error.
Sourcepub const fn deadline(self, deadline: Instant) -> Self
pub const fn deadline(self, deadline: Instant) -> Self
Sets the time at which the run stops a child that has not exited,
which then ends as Outcome::TimedOut.
Sourcepub fn cancel(self, cancel: &Cancel) -> Self
pub fn cancel(self, cancel: &Cancel) -> Self
Makes the run watch cancel, so Cancel::cancel stops it.
Sourcepub fn escalation(self, escalation: Escalation) -> Self
pub fn escalation(self, escalation: Escalation) -> Self
Sets the steps that stop the child.
Sourcepub fn around_spawn(
self,
hook: impl Fn(Spawn) -> Result<Spawned> + Send + Sync + 'static,
) -> Self
pub fn around_spawn( self, hook: impl Fn(Spawn) -> Result<Spawned> + Send + Sync + 'static, ) -> Self
Makes hook start the child, so the caller can hold a lock or change
process-wide state for exactly the length of the start.
The run calls hook once, on the thread that called run, and
never when its cancel was already cancelled. The hook does its work
before the start, calls Spawn::start, does its work after the
start, and returns the Spawned that the start gave. The hook
surrounds the whole start, including the forward feature’s lock.
A hook that returns an error ends the run with RunError::Start.
When the child had started, dropping its Spawned kills the child
and every process in its scope and reaps the child. A panic in the
hook does the same as it unwinds.
The time the hook takes counts towards the deadline, and it is not
part of the time bound that run states. Time that the hook spends
after the start counts towards
first_stdout, because the run reads
the child’s output only once the hook returns. A hook that waits for a
lock can check the deadline itself and return an error. With the
forward feature, a start waits forever once the tool has received
a signal, so a clean-up must not wait for a lock that the hook holds.
use std::io;
use std::process::Command;
use std::sync::Mutex;
use crumbkit_process::{RunOptions, run};
static FORK_GATE: Mutex<()> = Mutex::new(());
fn inherit(descriptors: bool) -> io::Result<()> {
// Clears or sets CLOEXEC on the descriptors the child inherits.
Ok(())
}
let options = RunOptions::new().around_spawn(|spawn| {
let _gate = FORK_GATE.lock().map_err(|_| io::Error::other("poisoned"))?;
inherit(true)?;
let spawned = spawn.start();
inherit(false)?;
spawned
});Sourcepub fn stdout_copy(self, copy: impl Fn(&[u8]) + Send + Sync + 'static) -> Self
pub fn stdout_copy(self, copy: impl Fn(&[u8]) + Send + Sync + 'static) -> Self
Calls copy with each chunk of standard output as the run reads it,
whatever the capture keeps, so a tool can show the output while the
run keeps a bounded copy. See RunOptions::stderr_copy.
Sourcepub fn stderr_copy(self, copy: impl Fn(&[u8]) + Send + Sync + 'static) -> Self
pub fn stderr_copy(self, copy: impl Fn(&[u8]) + Send + Sync + 'static) -> Self
Calls copy with each chunk of standard error as the run reads it,
whatever the capture keeps.
A chunk can end in the middle of a line or of a UTF-8 character. The
run does not read a stream with Capture::Inherit, so its function
receives nothing.
Each stream’s function runs on that stream’s reader thread, so the
two streams can interleave. A function that blocks holds the reader:
the child then waits on its full pipe, and the run waits for the
function past the time bound that run states. A function that
panics gets no more chunks, the run reads the rest of the stream so
the child runs on, and the run ends with RunError::Run.
Sourcepub const fn report_survivors(self) -> Self
pub const fn report_survivors(self) -> Self
Makes the run check, when the child ends by itself and before the run
kills what is left of the group, whether any other process in the
group still runs. ChildFinished::survivors gives the answer. The
run kills those processes as it always does.
The check is off by default because on Linux it reads every process
in /proc. It reports on Scope::Group on Linux and macOS alone.