1Proc::Terminator(3)   User Contributed Perl Documentation  Proc::Terminator(3)
2
3
4

NAME

6       Proc::Terminator - Conveniently terminate processes
7

SYNOPSIS

9           use Proc::Terminator;
10
11           # Try and kill $pid using various methods, waiting
12           # up to 20 seconds
13
14           proc_terminate($pid, max_wait => 20);
15

DESCRIPTION

17       "Proc::Terminator" provides a convenient way to kill a process, often
18       useful in utility and startup functions which need to ensure the death
19       of an external process.
20
21       This module provides a simple, blocking, and procedural interface to
22       kill a process or multiple processes (not tested), and not return until
23       they are all dead.
24
25       "Proc::Terminator" can know if you do not have permissions to kill a
26       process, if the process is dead, and other interesting tidbits.
27
28       It also provides for flexible options in the type of death a process
29       will experience. Whether it be slow or immediate.
30
31       This module exports a single function, "proc_terminate"
32
33   "proc_terminate($pids, %options)"
34       Will try to terminate $pid, waiting until the process is no longer
35       alive, or until a fatal error happens (such as a permissions issue).
36
37       $pid can either be a single PID (a scalar), or a reference to an array
38       of multiple PIDs, in which case they are all attempted to be killed,
39       and the function only returning once all of them are dead (or when no
40       possible kill alternatives remain).
41
42       The %options is a hash of options which control the behavior for trying
43       to terminate the pid(s).
44
45       "max_wait"
46           Specify the time (in seconds) that the function should try to spend
47           killing the provided PIDs. The function is guaranteed to not wait
48           longer than "max_wait".
49
50           This parameter can also be a fractional value (and is passed to
51           Time::HiRes).
52
53           DEFAULT: 10 Seconds.
54
55       "siglist"
56           An array of signal constants (use POSIX's ":signal_h" to get them).
57
58           The signals are tried in order, until there are no more signals
59           remaining.
60
61           Sometimes applications do proper cleanup on exit with a 'proper'
62           signal such as "SIGINT".
63
64           The default value for this parameter
65
66           The default signal list can be found in
67           @Proc::Terminator::DefaultSignalOrder
68
69           DEFAULT: "[SIGINT, SIGQUIT, SIGTERM, SIGKILL]"
70
71       "grace_period"
72           This specifies a time, in seconds, between the shifting of each
73           signal in the "siglist" parameter above.
74
75           In other words, "proc_terminate" will wait $grace_period seconds
76           after sending each signal in "siglist". Thereafter the signal is
77           removed, and the next signal is attempted.
78
79           Currently, if you wish to have controlled signal wait times, you
80           can simply insert a signal more than once into "siglist"
81
82           DEFAULT: 0.75
83
84       "interval"
85           This is the loop interval. The loop will sleep for ever "interval"
86           seconds.  You probably shouldn't need to modify this
87
88           DEFAULT: 0.25
89
90       When called in a scalar context, returns true on sucess, and false
91       otherwise.
92
93       When called in list context, returns a list of the PIDS NOT killed.
94
95   OO Interface
96       This exists mainly to provide compatibility for event loops. While
97       "proc_terminate" loops internally, event loops will generally have
98       timer functions which will call within a given interval.
99
100       In the OO interface, one instantiates a "Proc::Terminator::Batch"
101       object which contains information about the PIDs the user wishes to
102       kill, as well as the signal list (in fact, "proc_terminate" is a
103       wrapper around this interface)
104
105       Proc::Terminator::Batch methods
106
107       Proc::Terminator::Batch->with_pids($pids,$options)
108
109       Creates a new "Proc::Terminator::Batch". The arguments are exactly the
110       same as that for "proc_terminate".
111
112       Since this module does not actually loop or sleep on anything, it is
113       important to ensure that the "grace_period" and "max_wait" options are
114       set appropriately.
115
116       In a traditional scenario, a timer would be associated with this object
117       which would fire every "grace_period" seconds.
118
119       $batch->loop_once()
120
121       Iterates once over all remaining processes which have not yet been
122       killed, and try to kill them.
123
124       Returns a true value if processes still remain which may be killed, and
125       a false value if there is nothing else to do for this batch.
126
127       More specifically, if all processes have been killed successfully, this
128       function returns 0. If there are still processes which are alive (but
129       cannot be killed due to the signal stack being empty, or another
130       error), then "undef" is returned.
131
132       $batch->badprocs
133
134       Returns a reference to an array of "Proc::Terminator::Ctx" objects
135       which were not successfully terminated. The Ctx object is a simple
136       container. Its API fields are as follows:
137
138       pid The numeric PID of the process
139
140       siglist
141           A reference to an array of remaining signals which would have been
142           sent to this process
143
144       error
145           This is the captured value of $! at the time the error occured (if
146           any). If this is empty, then most likely the process did not
147           respond to any signals in the signal list.
148

SEE ALSO

150       signal(7)
151
152       kill(2)
153
154       Perl's kill
155
157       Copyright (C) 2012 M. Nunberg
158
159       You may use and distribute this software under the same terms and
160       conditions as Perl itself.
161

POD ERRORS

163       Hey! The above document had some coding errors, which are explained
164       below:
165
166       Around line 381:
167           You forgot a '=back' before '=head1'
168
169
170
171perl v5.34.0                      2022-01-21               Proc::Terminator(3)
Impressum