Proc::Terminator(3pm)

💖 Proc::Terminator 💖

okay bestie, welcome to Proc::Terminator, straight out of the User Contributed Perl Documentation collection. this one's a lil perl module that kills processes for you, and honestly? it's giving responsible menace. let's get into it 🎀

---

✨ NAME ✨

Proc::Terminator — conveniently terminate processes. yes, that's the whole vibe. it ends things. gracefully, if you want. or not. your call 💅

---

🌸 SYNOPSIS 🌸

use Proc::Terminator;

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

proc_terminate($pid, max_wait => 20);

like. that's it. that's the whole thing. one function call and the process is gone girl ✨

---

🦋 DESCRIPTION 🦋

Proc::Terminator gives you a convenient way to kill a process, and it's genuinely so useful in utility and startup functions where you need to make sure some external process is actually dead. no cap.

this module hands you a simple, blocking, and procedural interface to kill a process — or multiple processes (not tested, bestie, so like… be aware 👀) — and it will not return until they are all dead. periodt.

and here's the iconic part: Proc::Terminator can know if you don't have permissions to kill a process, if the process is already dead, and other interesting tidbits. it's observant. it pays attention. main character energy fr fr.

it also gives you flexible options in the type of death a process will experience. slow and gentle? immediate and brutal? you decide. it's giving choose your own adventure but for process signals 💀

this module exports a single function, proc_terminate. that's the one. the only one. slay.

💜 proc_terminate($pids, %options)

will try to terminate $pid, waiting until the process is no longer alive, or until a fatal error happens (like a permissions issue, bestie, we've all been there 😭).

$pid can be either a single PID (a scalar), or a reference to an array of multiple PIDs — in which case they all get attempted, and the function only returns once all of them are dead (or when no possible kill alternatives remain). no half-finished business around here 💅

the %options is a hash of options which control the behavior for trying to terminate the pid(s). let's go through them one by one, babes:

• 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). fancy 💅

DEFAULT: 10 Seconds.

• siglist — an array of signal constants (use POSIX's :signal_h to get them, iykyk).

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. so like, respect the process's little farewell ritual, you know? 🥺

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. yes, that's the trick. iconic behavior honestly 👑

DEFAULT: 0.75

• interval — this is the loop interval. the loop will sleep for every interval seconds. you probably shouldn't need to modify this. it's fine. it's fine. leave it alone bestie 🙈

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. (yes, it's telling on them 📢)

👑 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. so like, the OO interface is for the ✨fancy scheduling girlies✨.

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). it's the same energy, different outfit 💅

🌈 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. this is not a drill, bestie 🚨

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. rude of it, honestly 😤

---

🎀 SEE ALSO 🎀

• signal(7)
• kill(2)
• Perl's kill

go read those if you wanna go deeper. the lore is real 📚✨

---

🫶 AUTHOR & COPYRIGHT 🫶

Copyright (C) 2012 M. Nunberg

you may use and distribute this software under the same terms and conditions as Perl itself. sharing is caring, bestie 💜

---

and that's the whole page, babes ✨ this was perl v5.36.0, dated 2022-12-11, and it's Proc::Terminator(3pm) — now go forth and terminate things responsibly 💅🎀🦋