1Proc::Terminator(3) User Contributed Perl Documentation Proc::Terminator(3)
2
6 Proc::Terminator - Conveniently terminate processes
7
9 use Proc::Terminator;
10 # Try and kill $pid using various methods, waiting
12 # up to 20 seconds
13 proc_terminate($pid, max_wait => 20);
15
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 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 "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 It also provides for flexible options in the type of death a process
29 will experience. Whether it be slow or immediate.
30 This module exports a single function, "proc_terminate"
32 "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 $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 The %options is a hash of options which control the behavior for trying
43 to terminate the pid(s).
44 "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 This parameter can also be a fractional value (and is passed to
51 Time::HiRes).
52 DEFAULT: 10 Seconds.
54 "siglist"
56 An array of signal constants (use POSIX's ":signal_h" to get them).
57 The signals are tried in order, until there are no more signals
59 remaining.
60 Sometimes applications do proper cleanup on exit with a 'proper'
62 signal such as "SIGINT".
63 The default value for this parameter
65 The default signal list can be found in
67 @Proc::Terminator::DefaultSignalOrder
68 DEFAULT: "[SIGINT, SIGQUIT, SIGTERM, SIGKILL]"
70 "grace_period"
72 This specifies a time, in seconds, between the shifting of each
73 signal in the "siglist" parameter above.
74 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 Currently, if you wish to have controlled signal wait times, you
80 can simply insert a signal more than once into "siglist"
81 DEFAULT: 0.75
83 "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 DEFAULT: 0.25
89 When called in a scalar context, returns true on sucess, and false
91 otherwise.
92 When called in list context, returns a list of the PIDS NOT killed.
94 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 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 Proc::Terminator::Batch methods
106 Proc::Terminator::Batch->with_pids($pids,$options)
108 Creates a new "Proc::Terminator::Batch". The arguments are exactly the
110 same as that for "proc_terminate".
111 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 In a traditional scenario, a timer would be associated with this object
117 which would fire every "grace_period" seconds.
118 $batch->loop_once()
120 Iterates once over all remaining processes which have not yet been
122 killed, and try to kill them.
123 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 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 $batch->badprocs
133 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 pid The numeric PID of the process
139 siglist
141 A reference to an array of remaining signals which would have been
142 sent to this process
143 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
150 signal(7)
151 kill(2)
153 Perl's kill
155
157 Copyright (C) 2012 M. Nunberg
158 You may use and distribute this software under the same terms and
160 conditions as Perl itself.
161
163 Hey! The above document had some coding errors, which are explained
164 below:
165 Around line 381:
167 You forgot a '=back' before '=head1'
168perl v5.36.0 2023-01-20 Proc::Terminator(3)