NAME

       Proc::Terminator - Conveniently terminate processes

SYNOPSIS

           use Proc::Terminator;

           # Try and kill $pid using various methods, waiting
           # up to 20 seconds

           proc_terminate($pid, max_wait => 20);

DESCRIPTION

       "Proc::Terminator" provides a convenient way to kill a process, often useful in utility
       and startup functions which need to ensure the death of an external process.

       This module provides a simple, blocking, and procedural interface to kill a process or
       multiple processes (not tested), and not return until they are all dead.

       "Proc::Terminator" can know if you do not have permissions to kill a process, if the
       process is dead, and other interesting tidbits.

       It also provides for flexible options in the type of death a process will experience.
       Whether it be slow or immediate.

       This module exports a single function, "proc_terminate"

   "proc_terminate($pids, %options)"
       Will try to terminate $pid, waiting until the process is no longer alive, or until a fatal
       error happens (such as a permissions issue).

       $pid can either be a single PID (a scalar), or a reference to an array of multiple PIDs,
       in which case they are all attempted to be killed, and the function only returning once
       all of them are dead (or when no possible kill alternatives remain).

       The %options is a hash of options which control the behavior for trying to terminate the
       pid(s).

       "max_wait"
           Specify the time (in seconds) that the function should try to spend killing the
           provided PIDs. The function is guaranteed to not wait longer than "max_wait".

           This parameter can also be a fractional value (and is passed to Time::HiRes).

           DEFAULT: 10 Seconds.

       "siglist"
           An array of signal constants (use POSIX's ":signal_h" to get them).

           The signals are tried in order, until there are no more signals remaining.

           Sometimes applications do proper cleanup on exit with a 'proper' signal such as
           "SIGINT".

           The default value for this parameter

           The default signal list can be found in @Proc::Terminator::DefaultSignalOrder

           DEFAULT: "[SIGINT, SIGQUIT, SIGTERM, SIGKILL]"

       "grace_period"
           This specifies a time, in seconds, between the shifting of each signal in the
           "siglist" parameter above.

           In other words, "proc_terminate" will wait $grace_period seconds after sending each
           signal in "siglist". Thereafter the signal is removed, and the next signal is
           attempted.

           Currently, if you wish to have controlled signal wait times, you can simply insert a
           signal more than once into "siglist"

           DEFAULT: 0.75

       "interval"
           This is the loop interval. The loop will sleep for ever "interval" seconds.  You
           probably shouldn't need to modify this

           DEFAULT: 0.25

       When called in a scalar context, returns true on sucess, and false otherwise.

       When called in list context, returns a list of the PIDS NOT killed.

   OO Interface
       This exists mainly to provide compatibility for event loops. While "proc_terminate" loops
       internally, event loops will generally have timer functions which will call within a given
       interval.

       In the OO interface, one instantiates a "Proc::Terminator::Batch" object which contains
       information about the PIDs the user wishes to kill, as well as the signal list (in fact,
       "proc_terminate" is a wrapper around this interface)

       Proc::Terminator::Batch methods

       Proc::Terminator::Batch->with_pids($pids,$options)

       Creates a new "Proc::Terminator::Batch". The arguments are exactly the same as that for
       proc_terminate.

       Since this module does not actually loop or sleep on anything, it is important to ensure
       that the "grace_period" and "max_wait" options are set appropriately.

       In a traditional scenario, a timer would be associated with this object which would fire
       every "grace_period" seconds.

       $batch->loop_once()

       Iterates once over all remaining processes which have not yet been killed, and try to kill
       them.

       Returns a true value if processes still remain which may be killed, and a false value if
       there is nothing else to do for this batch.

       More specifically, if all processes have been killed successfully, this function returns
       0. If there are still processes which are alive (but cannot be killed due to the signal
       stack being empty, or another error), then "undef" is returned.

       $batch->badprocs

       Returns a reference to an array of "Proc::Terminator::Ctx" objects which were not
       successfully terminated. The Ctx object is a simple container. Its API fields are as
       follows:

       pid The numeric PID of the process

       siglist
           A reference to an array of remaining signals which would have been sent to this
           process

       error
           This is the captured value of $! at the time the error occured (if any). If this is
           empty, then most likely the process did not respond to any signals in the signal list.

SEE ALSO

       signal(7)

       kill(2)

       Perl's kill

AUTHOR & COPYRIGHT

       Copyright (C) 2012 M. Nunberg

       You may use and distribute this software under the same terms and conditions as Perl
       itself.