
[![Build Status](https://api.travis-ci.org/guillon/ptimeout.png?branch=master)](https://travis-ci.org/guillon/ptimeout/branches)

# Synopsys

The ptimeout utility is a python script implementing an interface similar to
GNU timeout with the additional ability to terminate all processes launched
from the timeout session.

In order to terminate all processes launched as part of the timeout
session, an environment variable is propagated along with processes creation.

This heuristic enables terminations of detached processes even when
they are not anymore in the process parent-child tree.

This also avoids the usage of process groups or process session leadership
which have some undesirable effect observed with timeout tools provided
with standard distributions. This approach is thus more transparent w.r.t.
to overall process management.

The limitation to this approach is when some process reset its environment,
in which case it will not be tracked anymore (nor any of its child) by
the termination heuristic. In this case the sub-process tree may not
terminate as part of the timeout session.

# Download

Download the last stable version of the script from there:
https://raw.githubusercontent.com/guillon/ptimeout/master/ptimeout

# Examples

A typical usage of such a tool if for limiting the time of a batch job
which may fall into non terminating condition such as in validation
scripts or test processes.

Also one generally expect the whole set of executed processes as part of
the job lifetime to be teminated when the job terminates, hence the
termination heuristic.

Example of usage for limiting a batch script to 1 hour duration:

    $ ptimeout 3600 script.sh

By default script.sh and all process executed from its process tree will
be terminated with SIGTERM after 3600 seconds, or killed by SIGKILL 10
seconds after if still persistent.

If one wants only process garbage collection, use a timeout of 0 as in:

    $ ptimeout 0 script.sh

In this case, the tool will not bound the execution time, but will still
garbage collect all processes when receiving an interrupting signal.

The usage of ptimeout can be recursive and there is not side effect with
respect to interactive/sessions/tty modes.

Get the command line help with:

    $ ptimeout --help
    usage: ptimeout [-h] [-v] [-d] [-s SIGNAL] [-k KILL_AFTER] [-c CATCH_SIGNALS]
                [-l LIST] [-f FORMAT]
                [duration] [command] ...
    ....


# Build and Install

This script requires python 2.6, 2.7 or 3.3+.

The script can be used directly without installation.

A makefile is provided anyway for completion and testing purpose.

Build with:

    $ make all # a no-op actually

Run unittests with:

    $ make check

Install with, for instance:

    $ make install PREFIX=$HOME/local  # Default is PREFIX=/usr/local


# References

Refer to the project home page at:
http://guillon.github.com/ptimeout

Refer to the current build and validation status at:
https://travis-ci.org/guillon/ptimeout?branches

Fill issues and enhancement request at:
https://github.com/guillon/ptimeout/issues


# License

The tool is distributed under the GPLv2 license.

Refer to the COPYING file: https://github.com/guillon/ptimeout/blob/master/COPYING
Refer to the COPYRIGHT file: https://github.com/guillon/ptimeout/blob/master/COPYRIGHT
