Struct Process 

pub struct Process { /* private fields */ }

Runs external programs and reports them through the event system

Process holds the two things that a run needs: the Output that carries its events, and the Cancellation that stops it. Context::process builds one from the context of a command, which is how a command reaches this interface.

A run reports every line that the program writes as it arrives, so a presenter can render the progress of a program that takes minutes. The same lines also reach the caller in the Execution, which means that a command can show the output and read it afterwards without running the program twice.

Cancellation ends the program. A command that observes its cancellation token therefore does not leave a build running after the user pressed Ctrl+C, and it needs no code of its own to achieve that. The program is asked to end first and killed only if it does not, so a build tool gets the moment it needs to remove its lock file. The builder names how long that moment is.

Process is cheaply clonable. Cloning produces another handle to the same event channel and the same cancellation token.

Examples

use clawless_core::process::{Invocation, Process};

let execution = process.run(Invocation::new("cargo").arg("build")).await?;

let succeeded = execution.status().success();

Implementations

impl Process

pub fn builder() -> ProcessBuilder

Create an instance of Process using the builder syntax

impl Process

pub async fn run( &self, invocation: Invocation, ) -> Result<Execution, RunProcessError>

Runs a program and reports its output while it runs

The method starts the program, sends every line that it writes into the event channel as the line arrives, waits for the program to end, and returns what the program produced. The Execution holds the exit status, both output streams as the program wrote them, and the time that the run took.

A program that ends without success is not a failure of this method. The status travels in the Execution, and require_success turns a status that the caller cannot accept into an error.

Cancellation ends the program: it is asked to end, and killed only if it does not answer within the grace period. The run then returns CancelledRun, and the events of the run end with an Outcome::Cancelled.

The program starts with a standard input that is null, so a program that asks for a password ends instead of waiting for an answer. It inherits the environment of the application, and the operating system resolves its name.

The future of this method owns the program. A caller that drops it, in a timeout of its own for example, kills the program with it and no event reports the end of the run. Stop a run through the cancellation token instead, which asks the program to end and closes its events.

Errors

Returns UnrunnableCommand when the program does not start or the run produces no result, CancelledRun when cancellation stopped the program, and UnreportableOutput when the presenter stopped listening while the program ran.

Panics

Panics when no Tokio runtime drives the future. Commands always run under one.

Examples

use clawless_core::process::{Invocation, Process};

let execution = process
    .run(Invocation::new("git").arg("rev-parse").arg("HEAD"))
    .await?
    .require_success()?;

let commit = execution.stdout().to_string_lossy().trim().to_owned();

Trait Implementations

impl Clone for Process

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Process

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

Formats the value using the given formatter.