rust-parallel

Command-line utility to execute commands in parallel and aggregate their output.

Similar interface to GNU Parallel or xargs but implemented in rust and tokio.

• Supports running commands read from stdin or input files similar to xargs.
• Supports ::: syntax to run all combinations of argument groups similar to GNU Parallel.
• Optional transformation of inputs using regular expression capture groups.

See examples for example commands and manual for more details.

Prevents output interleaving and is very fast.

Listed in Awesome Rust - utilities

Contents:

• Installation
• Documents
• Features
• Tech Stack

Installation:

Recommended:

1. Download a pre-built release from Github Releases for Linux or MacOS.
2. Extract the executable and put somewhere in your $PATH.

For manual installation/update:

1. Install Rust
2. Install the latest version of this app from crates.io:

$ cargo install rust-parallel   

3. The same cargo install rust-parallel command will also update to the latest version after initial installation.

Documents:

1. Examples - complete runnable commands to give an idea of overall features.
2. Manual - more detailed manual on how to use individual features.
3. Benchmarks
4. Output Interleaving - output interleaving in rust-parallel compared with other commands.

Features:

• Use only safe rust.
  • main.rs contains #![forbid(unsafe_code)])
• Supports optional processing of inputs using regular expression capture groups. This is implemented using the expand function to replace specified capture groups with input data.
• Prevent output interleaving.
• Use only asynchronous operations supported by tokio, do not use any blocking operations. This includes writing to stdout and stderr.
  • There is one exception to this: the which library used to build the path cache only has a blocking interface, so tokio::task::spawn_blocking is used to invoke this.
• Support arbitrarily large number of input lines, avoid O(number of input lines) memory usage. In support of this:
  • tokio::sync::Semaphore is used carefully to limit the number of commands that run concurrently. Do not spawn tasks for all input lines immediately to limit memory usage.
• Cache resolved command paths so expensive lookup in $PATH is not done for every command executed. This can be disabled with --disable-path-cache option.
• Support running commands on local machine only, not on remote machines.

Tech Stack:

• anyhow used for application error handling to propogate and format fatal errors.
• clap command line argument parser.
• itertools using multi_cartesian_product to process ::: command line inputs.
• indicatif optional graphical progress bar.
• regex optional regular expression capture groups processing for -r/--regex option.
• tokio asynchronous runtime for rust. From tokio this app uses:
  • async / await functions (aka coroutines)
  • Singleton CommandLineArgs instance using tokio::sync::OnceCell.
  • Asynchronous command execution using tokio::process::Command
  • tokio::sync::Semaphore used to limit number of commands that run concurrently.
  • tokio::sync::mpsc::channel used to receive inputs from input task, and to send command outputs to an output writer task. To await command completions, use the elegant property that when all Senders are dropped the channel is closed.
• tracing structured debug and warning logs.
  • tracing::Instrument is used to provide structured debug logs.
• which used to resolve command paths for path cache.