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.