Skip to main content

ProcessRunnerExt

processkit

Trait ProcessRunnerExt 

Source 
pub trait ProcessRunnerExt: ProcessRunner {
    // Provided methods
    fn run<'life0, 'life1, 'async_trait>(
        &'life0 self,
        command: &'life1 Command,
    ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>
       where Self: Sync + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn run_unit<'life0, 'life1, 'async_trait>(
        &'life0 self,
        command: &'life1 Command,
    ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
       where Self: Sync + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn exit_code<'life0, 'life1, 'async_trait>(
        &'life0 self,
        command: &'life1 Command,
    ) -> Pin<Box<dyn Future<Output = Result<i32>> + Send + 'async_trait>>
       where Self: Sync + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn probe<'life0, 'life1, 'async_trait>(
        &'life0 self,
        command: &'life1 Command,
    ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
       where Self: Sync + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn checked<'life0, 'life1, 'async_trait>(
        &'life0 self,
        command: &'life1 Command,
    ) -> Pin<Box<dyn Future<Output = Result<ProcessResult<String>>> + Send + 'async_trait>>
       where Self: Sync + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn parse<'life0, 'life1, 'async_trait, T, F>(
        &'life0 self,
        command: &'life1 Command,
        parse: F,
    ) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'async_trait>>
       where T: Send + 'async_trait,
             F: FnOnce(&str) -> T + Send + 'async_trait,
             Self: Sync + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn try_parse<'life0, 'life1, 'async_trait, T, F>(
        &'life0 self,
        command: &'life1 Command,
        parse: F,
    ) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'async_trait>>
       where T: Send + 'async_trait,
             F: FnOnce(&str) -> Result<T> + Send + 'async_trait,
             Self: Sync + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
    fn first_line<'life0, 'life1, 'async_trait, F>(
        &'life0 self,
        command: &'life1 Command,
        predicate: F,
    ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>
       where F: Fn(&str) -> bool + Send + 'async_trait,
             Self: Sync + 'async_trait,
             'life0: 'async_trait,
             'life1: 'async_trait { ... }
}
Expand description

Convenience methods available on every ProcessRunner (including &dyn ProcessRunner), layered over output_string.

Provided Methods§

Source

fn run<'life0, 'life1, 'async_trait>( &'life0 self, command: &'life1 Command, ) -> Pin<Box<dyn Future<Output = Result<String>> + Send + 'async_trait>>
where Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run, require an accepted exit, and return trimmed stdout. Accepted is 0 by default, widened by Command::ok_codes; any other code is Error::Exit.

Source

fn run_unit<'life0, 'life1, 'async_trait>( &'life0 self, command: &'life1 Command, ) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>
where Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run for the side effect: require an accepted exit (0, or any code in Command::ok_codes), discard the output.

Source

fn exit_code<'life0, 'life1, 'async_trait>( &'life0 self, command: &'life1 Command, ) -> Pin<Box<dyn Future<Output = Result<i32>> + Send + 'async_trait>>
where Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run and return just the exit code. A run that produced no code surfaces as an error — a timeout as Error::Timeout, a signal-kill as Error::Signalled — rather than a synthetic sentinel, mirroring ensure_success.

Source

fn probe<'life0, 'life1, 'async_trait>( &'life0 self, command: &'life1 Command, ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'async_trait>>
where Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run a predicate command and read its exit code as a boolean: exit 0 → Ok(true), exit 1 → Ok(false), anything else → Err (other code as Error::Exit, timeout as Error::Timeout, signal-kill as Error::Signalled). For commands whose exit code is the answer — git diff --quiet, grep -q, …

Source

fn checked<'life0, 'life1, 'async_trait>( &'life0 self, command: &'life1 Command, ) -> Pin<Box<dyn Future<Output = Result<ProcessResult<String>>> + Send + 'async_trait>>
where Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run, require an accepted exit (0 by default, widened by Command::ok_codes), and return the full captured result (untrimmed stdout). The building block for the parse/try_parse helpers — use it when you need the whole ProcessResult after success-checking, rather than just trimmed stdout (run) or the raw result (output_string).

Unlike run (and the CliClient::parse/try_parse verbs built over it), checked does not fail loud on a bounded-buffer truncation: it hands back the (possibly truncated) ProcessResult so the caller can decide — inspect truncated() before relying on the stdout. This is deliberate: checked is the lenient building block; the trimming / parsing verbs add the loud-on-truncation guard because they present stdout as if complete.

Source

fn parse<'life0, 'life1, 'async_trait, T, F>( &'life0 self, command: &'life1 Command, parse: F, ) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'async_trait>>
where T: Send + 'async_trait, F: FnOnce(&str) -> T + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run (requiring an accepted exit) and feed the captured stdout to an infallible parse closure — the shape of struct-returning CLI commands (git/jj --format output). Built on checked, but unlike it, fails loud on a bounded-buffer truncation so the parser never silently sees a clipped tail; returns the parsed value.

Because it is generic over the parser F, parse — like first_line — makes the ext trait not object-safe, so it cannot be dispatched through a dyn ProcessRunnerExt object; it is callable on a &dyn ProcessRunner (via the blanket ext impl). Reach for it on a concrete runner (JobRunner, &ProcessGroup, a ScriptedRunner), or via the Command::parse / CliClient::parse wrappers.

Source

fn try_parse<'life0, 'life1, 'async_trait, T, F>( &'life0 self, command: &'life1 Command, parse: F, ) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'async_trait>>
where T: Send + 'async_trait, F: FnOnce(&str) -> Result<T> + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Run (requiring an accepted exit) and feed the captured stdout to a fallible parse closure — the shape of JSON deserialization, where a parse failure becomes Error::Parse (or whatever error the closure returns). Like parse it is built on checked, fails loud on truncation, and — being generic over F — cannot be dispatched through a dyn ProcessRunnerExt object (the trait isn’t object-safe), though it is callable on a &dyn ProcessRunner. The Command::try_parse / CliClient::try_parse wrappers are the ergonomic path.

Source

fn first_line<'life0, 'life1, 'async_trait, F>( &'life0 self, command: &'life1 Command, predicate: F, ) -> Pin<Box<dyn Future<Output = Result<Option<String>>> + Send + 'async_trait>>
where F: Fn(&str) -> bool + Send + 'async_trait, Self: Sync + 'async_trait, 'life0: 'async_trait, 'life1: 'async_trait,

Stream command’s stdout and return the first line matching predicate (None if the stream ends first), bounded by the command’s timeout: a Some deadline surfaces as Error::Timeout and tears the process down. On an own-group runner (JobRunner, the default) that teardown covers the whole tree; on a shared ProcessGroup it reaches the run’s direct child by pid — a forking child’s grandchildren (and, on the Linux cgroup mechanism, a direct child that catches the graceful signal and closes stdout but keeps running) may outlive the probe until the group is dropped. Bound such a run with a whole-chain owner instead.

Routes through start — the streaming seam — so it is exercisable with any runner (a ScriptedRunner in tests), unlike the real-runner-only Command::first_line, which now delegates here.

Because it is generic over the predicate F, first_line makes the ext trait not object-safe, so it cannot be dispatched through a dyn ProcessRunnerExt object; it is callable on a &dyn ProcessRunner (via the blanket ext impl), like every other ProcessRunnerExt verb. The Command::first_line / CliClient::first_line wrappers are the ergonomic path.

Dyn Compatibility§

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors§