---
name: "Proc::Terminator"
section: "3pm"
platform: "linux"
package: "libproc-terminator-perl"
version: "0.5-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Proc::Terminator"
---

# Proc::Terminator(3pm)

Conveniently terminate processes

## 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)](/signal/7.md)

[**kill**(2)](/kill/2.md)

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.