pan - A light-weight driver to run tests and clean up their pgrps

pan -n tagname [-SyAehp] [-t #s|m|h|d time] [-s starts] [-x nactive] [-l logfile] [-a active-file] [-f command-file] [-d debug-level] [-o output-file] [-O buffer_directory] [-r report_type] [cmd]

Pan will run a command, as specified on the commandline, or collection of commands from a command-file. By default pan runs one command, choosing it at random from the whole set of commands available to it. The pan's name in the active file is specified by the tagname. When a command terminates pan will kill any orphans that may have been left behind in its pgrp. If pan is signaled it will kill any active commands and, again, clean up any orphans.

Pan uses the signal ratchet found in other zoo tools. The first time pan is signaled it sends a SIGTERM to the active pgrps; the second time it sends SIGHUP; the third time a SIGINT; after that it always sends SIGKILL.

Pan will not terminate until all the active commands and everything in their pgrps is dead. It will loop around at 5 second intervals, triggering its own signal ratchet, until it succeeds in killing the pgrps.

When the pan starts up it places its own tagname and commandline in the active file and begins scheduling commands. After a command is started pan puts an entry for it into the active file with its indicated tagname. If the command was specified on the command line, rather than in the command-file, then its tagname will be "cmdln". When a process terminates pan frees the active file entry. If a command terminates and leaves an orphaned pgrp then pan will put an entry into the active file called "panorphan" which will be removed only when the orphaned pgrp is cleaned up. Before pan exits it will ensure that all orphaned pgrps are dead (see above) and then it will remove its own tagname from the active file.

The command-file is a file containing tag/command pairs. Each line in the file begins with a tag identifying the command, followed by white space, and then the command and its arguments. A line beginning with the # character is a comment. Pan recognizes the token "%f" in a command's arguments and replaces it with a unique identifier--add this to filename arguments to prevent two instances of the command from interfering with each other.

When pan receives a SIGUSR2 it stops scheduling new tests and waits for the active tests to terminate. If the -y option was used then it will begin scheduling again, otherwise it will exit. It does not propagate the SIGUSR2.

-A

The all-stop flag. If any command exits non-zero pan will shutdown its scheduler and signal any active pgrps. The pan will exit non-zero after everything is shut down. By default pan ignores command exit statuses. The -e option is implied when this option is used.

-a active_file A file containing the tagnames, pids, and commands being run. If this is not specified then the ZOO environment variable will be read for the name of a directory where the active file will be placed, and in this case the active file's name will be "active". A single active file may be shared by any number of Zoo tools.

-d debug-level See the source for settings.

-e

Pan will exit non-zero if any of its commands exited non-zero. By default pan ignores command exit statuses.

-h

Print some simple help.

-l logfile Name of a log file to be used to store exit information for each of the commands (tags) that are run. This log file may not be shared with other Zoo tools or other pan processes.

-n tagname The tagname by which this pan process will be known by the zoo tools. This is a required argument.

-o output_file The file to which all test output will be saved. Normally all test output is sent to standard output. This includes each test's standard output and standard error.

-O buffer_directory A directory where pan can place temporary files to capture test output. This will prevent output from several tests mixing together in the output file.

-p

Enables printing results in human readable format.

-r report_type This controls the type of output that pan will produce. Supported formats are rts and none. The default is rts.

-S

Causes pan to run commands (tags) sequentially, as they are listed in the command-file. By default it chooses tags randomly. If a command is specified on the commandline and a command-file is also specified, then the commandline tag will be the last command. If this is specified and -s is not specified then the default setting for -s is equal to the total number of commands.

-s starts Indicates the number of commands (tags) that should be run before terminating. Set this to zero to run forever. By default this is set to 1 (but see -S for an exception). If this is specified and is less than the value specified for -x then it is bumped up to be equal to the value of -x (in other words, -x is always satisfied).

-t #s|m|h|d time Indicates the length that pan should run tests. By default this is not set. If specified, the -s flag is automatically set to 0 (infinite). Presumably, you want as many tests ran during this timeframe. Duration is measured in seconds, minutes, hPours,OR dPays.

-x nactive Indicates the number of commands (tags) that should be kept active at any one time. If this is greater than 1 then it is possible to have multiple instances of the same tag active at once. By default this is 1.

-y

Causes the pan scheduler to go idle if a signal is received or if a command exits non-zero. All active commands and their pgrps will be killed. After everything is dead the scheduler will restart again where it left off. If the signal is SIGUSR1 then pan will behave as if -y had not been specified.

In practice, the ZOO environment variable is generally prefered over the -a option. All examples assume this is being set.

The following creates a pan named "ex1" with an active file in /tmp/active. It runs the command "echo hello", keeping 3 copies running at all times, running 10 copies before terminating.

$ export ZOO=/tmp

$ pan -n ex1 -s 10 -x 3 echo hello

The next example will use this command file. Call this /tmp/cmds1.

----------cut------

fido ls /bin

rover echo hello wally

gidget sleep 2

lassie ls /etc

----------cut------

Using the above command file, /tmp/cmds1, run one command at a time, sequentially, running each command only once. If one command should fail then terminate immediately. An exit log is kept for all the commands.

$ pan -n ex3 -S -A -f /tmp/cmds1 -l ex3.log

Pan is often used in layers. This section extends the above examples to show how this is done.

The next example will use this command file. Call this /tmp/cmds2. Note that the embedded pans inside this file have exit logs, and that %f is used to give each pan a unique log file name.

----------cut------

larry pan -n ex4b -s10 -A -l ex4_%f.log echo hello

curly pan -n ex4c -S -A -f /tmp/cmds1 -l ex4_%f.log

moe echo done here

----------cut------

The following will run commands from the command file, keeping two at a time running, choosing them sequentially, and terminating if any of them exits non-zero.

$ pan -n ex4 -x2 -A -S -f /tmp/cmds2

Now run the commands in /tmp/cmds2, but this time we want to recover if one of the commands should exit non-zero. In this example it is possible for the "larry" or "curly" tags to exit non-zero. When this happens the pan will kill all active tags, making sure both larry and curly are dead, and then will continue scheduling--ensuring that our "done here" message comes out no matter what.

$ pan -n ex5 -x2 -A -S -y -f /tmp/cmds2

ZOO

If set, should name the directory where the active file should be placed. This is ignored if -a is specified.

active

Default name of active file if -a is not specified. This is prefixed by the directory name found in the ZOO environment variable.

PAN_STOP_FILE

The creation of this file in the defined TMP directory will cause pan to execute one more loop and stop. This is useful when testing needs to be stopped before its scheduled stop time (-t). By doing a 'touch' on this file, testing is ended, i.e. touch /tmp/runalltests-2345/PAN_STOP_FILE

Zoo tools - bump(1)

By default it exits zero unless signaled, regardless of the exit status of any of the commands it is running. If -A or -e are specified it exits non-zero if it is signaled or if any of the commands it is running should exit non-zero.