Questions and Answers
*********************

How-Tos
=======

Coloring Output
---------------

Para leaves coloring output to other tools (e.g., Colout_,
the `Generic Colouriser <grc_>`_, or Supercat_).

However, output that is prefixed with a program name can be
colored with :manpage:`tput(1)` and :manpage:`sed(1)`.

Generate ANSI escape codes:

.. code:: bash

    blue="$(tput setaf 4)"
    cyan="$(tput setaf 6)"
    reset="$(tput sgr0)"

.. tip::
    See :manpage:`terminfo(5)` for how numbers map to colors.

Then pipe Para's output through a *sed*-script
that applies them:

.. code:: bash

    para 'echo foo: qux' 'echo bar: quux' |
    sed "
        s/\(^foo:\)\(.*\)/$blue\1$reset\2/;
        s/\(^bar:\)\(.*\)/$cyan\1$reset\2/;
    "


.. _integrate:

Integration into C-based projects
---------------------------------

Para can be used to parallelize tests.

Add rules to build and run Para to your :file:`Makefile`:

.. code:: Makefile

    PARA = para
    PARAFLAGS = -iqv -n77 -t600 -k120

    .PHONY: check

    $(PARA): para.c
        $(CC) -O1 -DNDEBUG -o$@ para.c

    check: $(PARA) $(tests)
        $(PARA) $(PARAFLAGS) $(tests)

Tests can then be run with::

    make check

.. note::

    * :option:`-i` ignores errors.
    * :option:`-q` suppresses test output.
    * :option:`-v` shows which tests are being run.
    * :option:`-n 77` prevents tests exiting with 77 being reported as error
      (e.g., because it signifies skipped tests).
    * :option:`-t 600` aborts testing if it takes longer than ten minutes.
    * :option:`-k 120` kills jobs that do not terminate within two
      minutes after termination has been requested; termination is
      requested when an error occurs (e.g., the timeout set with
      :option:`-t` has been reached).



Troubleshooting
===============

``-l: getloadavg(3) not available``
-----------------------------------

The load average is queried with :manpage:`getloadavg(3)`. However,
:c:func:`getloadavg` is not supported by the system or not declared in
:file:`stdlib.h`, or Para has been compiled to only use interfaces
standardized by POSIX.1-2008_ (which :c:func:`getloadavg` is not).

You can try to recompile Para with::

    ./configure -DEXTENSIONS
    make clean all


``Environment full`` or ``Too many variables``
----------------------------------------------

By default, Para permits only 255 variables in a job's environment.
You can raise that limit by re-compiling Para with :c:macro:`MAX_NVARS`
set to a higher value. For example,

.. code:: bash

    ./configure -DMAX_NVARS=2048
    make clean all

configures Para to permit up to 2047 environment variables
(one slot is needed for a terminator).


:command:`para` hangs after :kbd:`Ctrl-C`
-----------------------------------------

When :kbd:`Ctrl-C` is pressed, running jobs are requested to terminate.
However, :command:`para` itself only exits when all jobs have exited.
And it cannot be interrupted with :kbd:`Ctrl-C` or terminated with
:manpage:`kill(1)` while jobs are being waited for. So it may seem to
hang when a job takes a long time to terminate.

That said, if a *job* hangs, :command:`para` will wait forever.
So the job must be killed.

Press :kbd:`Ctrl-Z` to stop :command:`para` (and the jobs it started):

.. code:: none

    ^Z[1] + Stopped(SIGTSTP)     para foo bar baz

Display information about the jobs currently running by

.. code:: none

    $ ps -l | awk -vppid=$(jobs -p %1) 'NR == 1 || $3 == ppid'
    UID   PID   PPID     F  CPU  PRI  NI    SZ  RSS  WCHAN  S  ADDR  TTY        TIME  CMD
    1000  2001  2000  4006    0   31   0  1234   12  -      U     0  tty001  2:10.00  foo

and identify the job that is hanging.

Terminate that job's child processes::

    $ ps -oppid=,pid= | awk -vppid=2001 '$1 == ppid {print $2}' | xargs kill

Check which of the files that have been opened by that job are still open by

.. code:: none

    $ lsof -p 2001
    COMMAND  PID   USER   FD   TYPE  DEVICE  SIZE/OFF     NODE  NAME
    foo      2001  jdoe  cwd    DIR    1,13      1536  1908453  /home/jdoe
    foo      2001  jdoe  txt    REG    1,13    418208   741673  /home/jdoe/qux
    foo      2001  jdoe  101u   REG    1,13     12421   511412  /tmp/quux

and note them down for later.

.. warning::
    Some files that need attention may have already been closed
    and will therefore not be listed by :manpage:`lsof(8)`.

Check if all child processes have exited::

    $ pstree 2001
    --= 2001 jdoe foo

.. note::
    Child processes may have to be killed, too.

Once all child processes have exited, the job can be killed::

    $ kill -s KILL 2001

Check whether other process are using the files noted down earlier::

    $ lsof -f -- /home/jdoe/qux /tmp/quux

Delete temporary files that are not used by other processes
and that have not been deleted::

    $ rm /tmp/quux

Check the remaining files for consistency.

Finally, continue :command:`para` (and the remaining jobs)::

    $ fg 1
    [1] para foo bar baz

.. tip::
    Use :option:`-k` to kill jobs automatically if
    they fail to terminate within a grace period.


:samp:`para.c:{line}: {error}`
------------------------------

Error messages that mention :file:`para.c` indicate bugs.
Please be so kind and :doc:`report them <feedback>`.


:samp:`wordsplit: Invalid argument` or :samp:`-c: Invalid argument`
-------------------------------------------------------------------

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