Questions and Answers

How-Tos

Coloring Output

Para leaves coloring output to other tools (e.g., Colout, the Generic Colouriser, or Supercat).

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

Generate ANSI escape codes:

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

Tip

See terminfo(5) for how numbers map to colors.

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

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

Integration into C-based projects

Para can be used to parallelize tests.

Add rules to build and run Para to your 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

• -i ignores errors.

• -q suppresses test output.

• -v shows which tests are being run.

• -n 77 prevents tests exiting with 77 being reported as error (e.g., because it signifies skipped tests).

• -t 600 aborts testing if it takes longer than ten minutes.

• -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 -t has been reached).

Troubleshooting

-l: getloadavg(3) not available

The load average is queried with getloadavg(3). However, getloadavg() is not supported by the system or not declared in stdlib.h, or Para has been compiled to only use interfaces standardized by POSIX.1-2008 (which 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 MAX_NVARS set to a higher value. For example,

./configure -DMAX_NVARS=2048
make clean all

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

para hangs after Ctrl-C

When Ctrl-C is pressed, running jobs are requested to terminate. However, para itself only exits when all jobs have exited. And it cannot be interrupted with Ctrl-C or terminated with 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, para will wait forever. So the job must be killed.

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

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

Display information about the jobs currently running by

$ 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

$ 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 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 para (and the remaining jobs):

$ fg 1
[1] para foo bar baz

Tip

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

para.c:line: error

Error messages that mention para.c indicate bugs. Please be so kind and report them.

wordsplit: Invalid argument or -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 (\).