NAME

POE::Component::ProcTerminator - Safely and easily kill runaway processes

DESCRIPTION

This is a POE component wrapping the functionality of Proc::Terminator, but using POE's timers and event loop instead of the built-in (and obviously blocking) sleep-based loop.

SYNOPSIS

Set up the component..

    POE::Component::ProcTerminator->spawn(Alias => "proc_terminator");
    

Later, in your code..

    $_[KERNEL]->call(proc_terminator =>
                    terminate =>
                    $a_pid,
                    {
                        siglist => [ SIGINT, SIGTERM, SIGKILL ]
                    });
                    

And that's all!

DESCRIPTION

Semantics here are identical to that specified in Proc::Terminator. This manpage describes feature specific to the POE component

spawn(Alias => "a name", %options..)

If the Alias parameter is missing, then it will spawn the default session, called proc_terminator

Further options are taken as defaults to be used for subsequent calls to "terminate"

$kernel->post($alias, terminate => $pid, { other => options })

Instruct the component to begin trying to kill $pid, where $pid can either be a single PID, or an array reference of PIDs.

The second argument may be an optional hashref of options, accepting the same kinds of things that Proc::Terminator's proc_terminate does.

The more relevant options are

siglist

A list of signals which will be used to kill off the process. Signals are tried in succession, until the process is either dead or there are no more signals left in the list. The defaults exist in @Proc::Terminator::DefaultSignalOrder

grace_period

An interval (in seconds) to wait between shifting the signal list (specified in siglist). In the world of POE, this effectively means how often the timer event will be called.

Some additional options:

failure_callback

If for whatever reason Proc::Terminator is unable to kill your process, this callback will be invoked with a Proc::Terminator::Batch as its sole argument. See Proc::Terminator for documentation on that object.

cleanup_flags

Control the behavior of POE::Component::ProcTerminator when the session terminates prematurely (e.g. the kernel is being shut down, or some other exceptional terminal condition has occured).

The default behavior is to not do anything.

This value is one or more of the following flags, OR'd together (these are sub constants, exported to your namespace).

PROCTERMf_CLEANUP_BLOCK

This instructs the cleanup handler to block and loop for this batch, as Proc::Terminator does in the synchronous API. The maximum time each batch can block is 5 seconds (though this might be configurable).

PROCTERMf_SIGKILL_LAST

If SIGKILL was not in the original list of signals to send to the process, then push it to the end of the signal-to-send stack. This only makes sense with the PROCTERMf_CLEANUP_BLOCK

PROCTERMf_SIGKILL_ONLY

Blindly sends a SIGKILL to the remaining processes. It does not make sense to use this flag with the other flags.

NOTES

When POE shuts down and the component is about to stop, it will call an iteration of the loop (hopefully killing it). In the future I might want to do something like either invoke a 'real' Proc::Terminate session (with a reasonable time limit) or nuke them all with SIGKILL. Dunno?

SEE ALSO

Proc::Terminator

AUTHOR & COPYRIGHT

Copyright (C) 2012 M. Nunberg

You may use and distribute this software under the same terms and conditions as Perl itself.