.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Proc::Terminator 3pm"
.TH Proc::Terminator 3pm "2018-03-30" "perl v5.26.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Proc::Terminator \- Conveniently terminate processes
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    use Proc::Terminator;
\&    
\&    # Try and kill $pid using various methods, waiting
\&    # up to 20 seconds
\&    
\&    proc_terminate($pid, max_wait => 20);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`Proc::Terminator\*(C'\fR 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.
.PP
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.
.PP
\&\f(CW\*(C`Proc::Terminator\*(C'\fR can know if you do not have permissions to kill a process,
if the process is dead, and other interesting tidbits.
.PP
It also provides for flexible options in the type of death a process will
experience. Whether it be slow or immediate.
.PP
This module exports a single function, \f(CW\*(C`proc_terminate\*(C'\fR
.ie n .SS """proc_terminate($pids, %options)"""
.el .SS "\f(CWproc_terminate($pids, %options)\fP"
.IX Subsection "proc_terminate($pids, %options)"
Will try to terminate \f(CW$pid\fR, waiting until the process is no longer alive, or
until a fatal error happens (such as a permissions issue).
.PP
\&\f(CW$pid\fR can either be a single \s-1PID\s0 (a scalar), or a reference to an array of
\&\fImultiple\fR 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).
.PP
The \f(CW%options\fR is a hash of options which control the behavior for trying to
terminate the pid(s).
.ie n .IP """max_wait""" 4
.el .IP "\f(CWmax_wait\fR" 4
.IX Item "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 \f(CW\*(C`max_wait\*(C'\fR.
.Sp
This parameter can also be a fractional value (and is passed to Time::HiRes).
.Sp
\&\fI\s-1DEFAULT\s0\fR: 10 Seconds.
.ie n .IP """siglist""" 4
.el .IP "\f(CWsiglist\fR" 4
.IX Item "siglist"
An array of signal constants (use \s-1POSIX\s0's \f(CW\*(C`:signal_h\*(C'\fR to get them).
.Sp
The signals are tried in order, until there are no more signals remaining.
.Sp
Sometimes applications do proper cleanup on exit with a 'proper' signal such as
\&\f(CW\*(C`SIGINT\*(C'\fR.
.Sp
The default value for this parameter
.Sp
The default signal list can be found in \f(CW@Proc::Terminator::DefaultSignalOrder\fR
.Sp
\&\fI\s-1DEFAULT\s0\fR: \f(CW\*(C`[SIGINT, SIGQUIT, SIGTERM, SIGKILL]\*(C'\fR
.ie n .IP """grace_period""" 4
.el .IP "\f(CWgrace_period\fR" 4
.IX Item "grace_period"
This specifies a time, in seconds, between the shifting of each signal in the
\&\f(CW\*(C`siglist\*(C'\fR parameter above.
.Sp
In other words, \f(CW\*(C`proc_terminate\*(C'\fR will wait \f(CW$grace_period\fR seconds after sending
each signal in \f(CW\*(C`siglist\*(C'\fR. Thereafter the signal is removed, and the next signal
is attempted.
.Sp
Currently, if you wish to have controlled signal wait times, you can simply
insert a signal more than once into \f(CW\*(C`siglist\*(C'\fR
.Sp
\&\fI\s-1DEFAULT\s0\fR: 0.75
.ie n .IP """interval""" 4
.el .IP "\f(CWinterval\fR" 4
.IX Item "interval"
This is the loop interval. The loop will sleep for ever \f(CW\*(C`interval\*(C'\fR seconds.
You probably shouldn't need to modify this
.Sp
\&\fI\s-1DEFAULT\s0\fR: 0.25
.PP
When called in a scalar context, returns true on sucess, and false otherwise.
.PP
When called in list context, returns a list of the \s-1PIDS\s0 \fB\s-1NOT\s0\fR killed.
.SS "\s-1OO\s0 Interface"
.IX Subsection "OO Interface"
This exists mainly to provide compatibility for event loops. While \f(CW\*(C`proc_terminate\*(C'\fR
loops internally, event loops will generally have timer functions which will
call within a given interval.
.PP
In the \s-1OO\s0 interface, one instantiates a \f(CW\*(C`Proc::Terminator::Batch\*(C'\fR object which
contains information about the PIDs the user wishes to kill, as well as the signal
list (in fact, \f(CW\*(C`proc_terminate\*(C'\fR is a wrapper around this interface)
.PP
\fIProc::Terminator::Batch methods\fR
.IX Subsection "Proc::Terminator::Batch methods"
.PP
Proc::Terminator::Batch\->with_pids($pids,$options)
.IX Subsection "Proc::Terminator::Batch->with_pids($pids,$options)"
.PP
Creates a new \f(CW\*(C`Proc::Terminator::Batch\*(C'\fR. The arguments are exactly the same as
that for proc_terminate.
.PP
Since this module does not actually loop or sleep on anything, it is important
to ensure that the \f(CW\*(C`grace_period\*(C'\fR and \f(CW\*(C`max_wait\*(C'\fR options are set appropriately.
.PP
In a traditional scenario, a timer would be associated with this object which would
fire every \f(CW\*(C`grace_period\*(C'\fR seconds.
.PP
\f(CW$batch\fR\->\fIloop_once()\fR
.IX Subsection "$batch->loop_once()"
.PP
Iterates once over all remaining processes which have not yet been killed, and try
to kill them.
.PP
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.
.PP
More specifically, if all processes have been killed successfully, this function
returns \f(CW0\fR. If there are still processes which are alive (but cannot be killed
due to the signal stack being empty, or another error), then \f(CW\*(C`undef\*(C'\fR is returned.
.PP
\f(CW$batch\fR\->badprocs
.IX Subsection "$batch->badprocs"
.PP
Returns a reference to an array of \f(CW\*(C`Proc::Terminator::Ctx\*(C'\fR objects which were
not successfully terminated. The Ctx object is a simple container. Its \s-1API\s0 fields
are as follows:
.IP "pid" 4
.IX Item "pid"
The numeric \s-1PID\s0 of the process
.IP "siglist" 4
.IX Item "siglist"
A reference to an array of remaining signals which would have been sent to this
process
.IP "error" 4
.IX Item "error"
This is the captured value of \f(CW$!\fR 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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fIsignal\fR\|(7)
.PP
\&\fIkill\fR\|(2)
.PP
Perl's kill
.SH "AUTHOR & COPYRIGHT"
.IX Header "AUTHOR & COPYRIGHT"
Copyright (C) 2012 M. Nunberg
.PP
You may use and distribute this software under the same terms and conditions
as Perl itself.