Manual

Synopsis

para [variable…] command […]

para -c 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 -c 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 an error occurs, running jobs are terminated and pending jobs are discarded. If -k is given and a process group leader does not terminate within the given grace period, its process group is killed.

Ctrl-Z also stops runnings jobs. Continuing with bg(1) or fg(1) continues them again. Sending SIGUSR1 discards pending jobs but will leave running jobs alone.

para exits when all jobs have exited.

Options

-C

Show the build configuration.

-c format

Compose commands by replacing {}’s in format with arguments.

-e fd

Write non-job output, including errors, to file descriptor fd.

-h

Show a help screen.

-i

Neither terminate runnings jobs nor discard pending ones when a job returns an error.

-j n

Run n jobs in parallel. Defaults to the number of processors available or 2, whichever is higher.

-k n

Kill jobs that do not exit within n seconds after they have been requested to terminate.

-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 available or 2.0, whichever is higher. Set to 0 to run as many jobs in parallel as requested with -j. Only available on systems that support getloadavg(3).

-n status

Do not treat a job exiting with status as error. Give multiple times to exempt multiple statuses.

-r str

Use str as placeholder in format (default: {}).

-q

Suppress job output, including errors.

-t n

Time out after n seconds.

-V

Show version and legal information.

-v

Be more verbose.

-w

Wait for running jobs to finish when a job returns an error. Pending jobs are still discarded.

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 exempted with -n. 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

Caveats

How long applications take to terminate varies. Use -k with caution.

If getloadavg(3) is not available, para will silently run as many jobs in parallel as processors are available 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 -c 'echo {}' foo bar baz
foo
bar
baz

Add FOO=bar to the job environment:

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

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 -c '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 run, 0 failed
$ cat jobs.out
foo
$ cat jobs.err
bar

See Also

xargs(1)