Crate pipelight_exec

Warning - Unstable crate.

This crate is still in development and undergoing API changes.

It is internally used in the pipelight cicd engine: https://github.com/pipelight/pipelight

Breanking changes

• v0.4 : New API for easier process manipulation. p.run_detached() becomes p.detach().run();

About

A crate for easy process management (on Unix systems).

It makes a best effort to leverage the standard library process crate.

Features:

• Get process execution time.

• Spawn and Kill background processes.

• Display a running process standard inputs/outputs.

• Interoperability with rustix and sysinfo crates.

Usage

Spawn a process

Spawn a simple process in the background. or in other words, execute a process and detach it.

It keeps running after parent process exit and terminal exit.

// Runs a child process and wait until execution is over.
let mut p = Process::new()
    .stdin("echo test")
    .to_owned();
p.run()?;

Runs child process in the background. Do not wait until process is over and return as soon as child is spawned.

let mut p = Process::new()
    .stdin("echo test")
    .background()
    .to_owned();
p.run()?;

Runs a child process and wait for it to return, but do not print stdout and stderr to console.

In other words it is detached from standards inputs and outputs.

let mut p = Process::new()
    .stdin("echo test")
    .detach()
    .to_owned();
p.run()?;

Runs a disowned child process that won’t be killed if parent is killed.

let mut p = Process::new()
    .stdin("echo test")
    .orphan()
    .to_owned();
p.run()?;

Runs a disowned child process that won’t be killed if parent is killed. and stores process outputs in ./.pipelight/proc/:uuid/ Practical if you want to process child output from another program.

let mut p = Process::new()
    .stdin("echo test")
    .fs()
    .detach()
    .to_owned();
p.run()?;

Read a process i/o.

let mut p = Process::new()
    .stdin("echo test")
    .background()
    .fs()
    .to_owned();
p.run()?;

// Later in execution
p.io.read().into_diagnostic()?;
println!("{:?}", p.io.stdout); // Some("stuff\n")

Find a process.

Find a running process, with handy search options.

let process_finder = Finder::new().seed("my_proc").root("/my/dir").search()?;

let pid = 1792;
let process_finder = Finder::new().pid(&pid).search()?;

Beware - Unconventional process management

In linux, a process inputs and outputs are exposed at /proc/:process_id/fd/:fd_id and are deleted as soon as the process finishes its execution.

A very good straightforward rustacean overview at procfs crate

To keep track of running and dead processes, this crate can redirect some process i/o into its own managed files. Pipelight managed processes are stored in a the .pipelight/proc/ directory. It has the same structure as your /proc/.

However, to ease ones developer life, standard outputs are polled, read and finally stored as text files. /proc/:pid/2 (file descriptor / buffer)-> ./pipelight/proc/:uuid/2(text file)

For example, The following code runs a process whose outputs are redirected to pipelight temporary filesystem thanks to the fs() method.

let p = Process::new().stdin("pwd").fs().run()?;
p.io.read().into_diagnostic()?;
let stdout: Option<String> = p.io.stdout;

It allows us to read a process outputs during and long after execution.

Modules

dates

statuable

Structs

Finder

Io

A struct that stores the procees standards input and outputs into human readable strings.

Process

A struct that stores the process attributes for further access and manipulation.

Runner

A struct that stores the process attributes for further access and manipulation.

State

A convenience struct to store the process status and its duration.

Enums

Status

An enum for the different possible process state.

Traits

Statuable

In pipelight, many are the structs and enum substructs that have a status. This trait is to query the deepenth status in a more standardize way.