####
Para
####

.. image:: _static/coverage.svg
   :target: _static/coverage/para/para.c.gcov.html
   :alt: Coverage data

.. image:: https://www.bestpractices.dev/projects/9357/badge
   :target: https://www.bestpractices.dev/en/projects/9357
   :alt: OpenSSF best practices badge

Para is a command-line utility that runs jobs in parallel.

It is simpler, more lightweight, and more portable than Concurrently_,
`GNU Parallel`_, or rust-parallel_. It's :doc:`fast <perf>`, too.

Para comprises a single source file, is written in C99_, only uses the
Unix standard library, and compiles with :option:`-Wall -Wextra -Werror`.
It should work out-of-the-box on almost every Unix-like system and be
easy to integrate into C-based projects.


Examples
========

Run :command:`echo foo` and :command:`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 BAZ=qux 'sh -c "echo $FOO"' 'sh -c "echo $BAZ"'
    bar
    qux


Comparison
==========

The GNU parallel documentation features an in-depth `comparison of
tools that run commands in parallel <comparison_>`_. This is how Para
rates according to their comparison matrix:

=== ============================================================= ============
ID  Description                                                   Supported
=== ============================================================= ============
I1  Arguments can be read from standard input.                    With :manpage:`xargs(1)`
I2  Arguments can be read from a file.                            With :manpage:`xargs(1)`
I3  Arguments can be read from multiple files.                    -- " -- and :manpage:`cat(1)`
I4  Arguments can be read from command line.                      Yes
I5  Arguments can be read from a table.                           With :manpage:`awk(1)`
I6  Arguments can be read from the same file using ``#!``.        No
I7  Line oriented input as default.                               n/a
M1  Composed commands.                                            Yes
M2  Multiple arguments can fill up an execution line.             Yes
M3  Arguments can be put anywhere in execution line.              Yes
M4  Multiple arguments can be put anywhere in execution line.     Yes
M5  Arguments can be replaced with context.                       No
M6  Input can be treated as the complete command line.            With :manpage:`xargs(1)`
O1  Grouping output so output from different jobs does not mix.   No
O2  Send standard error to standard error.                        Yes
O3  Send standard output to standard output.                      Yes
O4  Order of output can be same as order of input.                No
O5  Standard output only contains standard output from command.   Yes
O6  Standard error only contains standard error from command.     Yes
O7  Buffering on disk.                                            n/a
O8  No temporary files left if killed.                            Yes
O9  Test if disk runs full during run.                            n/a
O10 Output of a line bigger than 4 GB.                            Probably [#untested]_
E1  Run jobs in parallel.                                         Yes
E2  List running jobs.                                            Partly [#verbose]_
E3  Finish running jobs, but do not start new ones.               Yes
E4  Number of running jobs can depend on number of CPUs.          Yes
E5  Finish running jobs, but do not start new ones after failure. Yes
E6  Number of running jobs can be adjusted while running.         No
E7  Only spawn new jobs if load is less than a limit.             Yes
E8  Has non-zero exit value if any job has non-zero exit value.   Yes
E9  Jobs can be started without reading all input first.          n/a
R1  Jobs can be run on remote computers.                          No
R2  Basefiles can be transferred.                                 n/a
R3  Argument files can be transferred.                            n/a
R4  Result files can be transferred.                              n/a
R5  Cleanup of transferred files.                                 n/a
R6  No config files needed.                                       n/a
R7  Do not run more commands than SSHD can handle.                n/a
R8  Configurable SSH command.                                     n/a
R9  Retry if connection breaks occasionally.                      n/a
S1  Possibility to work as a mutex.                               No
S2  Possibility to work as a counting semaphore.                  No
=== ============================================================= ============

.. [#untested] Untested. But Para does not interfere with job output, so
               huge output should not be an issue.
.. [#verbose]  Started jobs can be shown with :option:`-v`,
               running jobs with :command:`pstree $(pgrep para)`.


GNU Parallel is the only tool that supports all of the above features.
Para is designed to be simple and portable, not feature-rich. If you need
to keep track of the output of individual jobs or distribute jobs over
multiple machines, GNU Parallel is likely the best choice.


.. toctree::
   :hidden:
   :titlesonly:

   quick
   build
   install
   manual
   Q & A <qa>
   security
   feedback
   contrib
   Change log <changelog>
   License <license>
   genindex