Manual¶

Synopsis¶

para [variable…] command […]

para -k format [variable…] argument […]

para -C | -V | -h

Description¶

para runs commands in parallel, adding variables to their environment.

Commands are split into words in the same way as they are split by the sh, save for that escaped newlines are interpreted as newlines and that trailing escapes raise a syntax error.

If -k is given, commands are composed by replacing each {}, or each occurrence of the placeholder set with -r, in the format with the next argument. Placeholders must occur as words of their own; placeholders that occur within words are treated as ordinary characters. The format is split into words in the same way as commands are. Word-splitting precedes placeholder substitution.

Started processes are made process group leaders.

If -c has not been given and a job exits with a non-zero status not ignored with -i, or if a job exits because it caught a signal, or if the timeout set with -t is reached, running jobs are sent a TERM, pending jobs are discarded, and para exits. If a process group leader does not terminate within 120 seconds, or the time set with -g, after TERM was sent, its process group is killed.

If -f is given and a job exits with a non-zero status, or if para is sent USR1, pending jobs are discarded and para exits as soon as all running jobs have finished.

Suspending para with Ctrl-Z also suspends running jobs; resuming para with bg(1) or fg(1) also resumes suspended jobs.

Options¶

-C¶: Print Para’s build configuration.

-c¶: Continue when a job returns an error.

-e fd¶: Send non-job output, including errors, to file descriptor fd.

-f¶: Let running jobs finish when a job returns an error.

-g n¶: Give jobs n secs to terminate when aborted (default: 120). Set to 0 to give jobs unlimited time.

-h¶: Show a help screen.

-i n¶: Do not treat exit status n as error.

-j n¶: Run up to n jobs in parallel. Defaults to the number of processors (or 2 if that number cannot be detected).

-k format¶: Compose commands by replacing {}’s in format with arguments.

-l n¶: Only start jobs if no jobs are running or the one minute load average is smaller than n. Defaults to one less than the number of processors (or 2.0 if that number cannot be detected). Set to 0 to run as many jobs in parallel as requested with -j. Only available on systems that support getloadavg(3).

-r str¶: Use str as replacement string for -k (default: {}).

-q¶: Suppress job output, including errors.

-t n¶: Abort after n seconds.

-V¶: Show version and legal information.

-v¶: Be more verbose.

-i can be given multiple times.

Diagnostics¶

Arguments are invalid if they cannot be split into words. This happens when they contain unbalanced quotes or end with an escape (\).

Exit Status¶

para exits with the same status as the last job that has exited with a non-zero status not ignored with -i. If no job has been been started yet, all jobs have exited with such a status, a signal was caught, or an unexpected error occurred, para exits with:

0: Success
1: Failure
2: Usage error
> 128: Signal caught

Caveats¶

If getloadavg(3) is not available, para will silently run as many jobs in parallel as processors are online or as requested with -j.

Bugs¶

Please report bugs at <https://github.com/odkr/para/issues>.

Examples¶

Run echo foo and echo bar in parallel:

$ para 'echo foo' 'echo bar'
bar
foo

Compose commands from arguments:

$ para -k 'echo {}' foo bar baz
foo
bar
baz

Add FOO=bar and BAZ=qux to the job environment:

$ para FOO=bar QUX=quux 'sh -c "echo $FOO"' 'sh -c "echo $QUX"'
bar
quux

Rename files from x.foo to x.bar:

$ for file in *.foo
> do printf '%s\0' "$file" "${file%.foo}.bar"
> done |
> # Without -n, xargs would read all input before calling para
> xargs -0 -n256 para -k 'mv {} {}'

Of course, if your xargs(1) supports -L and -P, just do:

$ for file in *.foo
> do printf '%s\0' "$file" "${file%.foo}.bar"
> done |
> xargs -0 -L2 -P4 mv

Show which jobs have been started and redirect job output:

$ exec 3>&2
$ para -ve3 'echo foo' 'sh -c "echo bar >&2"' >jobs.out 2>jobs.err
para: [31744] echo foo
para: [31747] sh -c echo\ bar\ >&2
para: Waiting for 1 job to finish...
para: 2 jobs succeeded, 0 failed
$ cat jobs.out
foo
$ cat jobs.err
bar