Skip to main content

RunOptions

Struct RunOptions 

Source
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

Source

pub fn new() -> Self

Returns the default settings.

Source

pub fn stdin(self, input: Input) -> Self

Sets what the child reads on its standard input.

Source

pub fn stdout(self, capture: Capture) -> Self

Sets what the run keeps of the child’s standard output.

Source

pub fn stderr(self, capture: Capture) -> Self

Sets what the run keeps of the child’s standard error.

Source

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.

Source

pub fn cancel(self, cancel: &Cancel) -> Self

Makes the run watch cancel, so Cancel::cancel stops it.

Source

pub fn escalation(self, escalation: Escalation) -> Self

Sets the steps that stop the child.

Source

pub const fn scope(self, scope: Scope) -> Self

Sets which processes the run holds and signals.

Source

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
});
Source

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.

Source

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.

Source

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.

Trait Implementations§

Source§

impl Clone for RunOptions

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for RunOptions

Source§

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter. Read more
Source§

impl Default for RunOptions

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.