POE::Component::Supervisor::Handle::Proc(3p)

NAME
POE::Component::Supervisor::Handle::Proc - A supervisor child handle for a POSIXish process.

VERSION
version 0.09

SYNOPSIS
    # created by POE::Component::Supervisor::Supervised::Proc

DESCRIPTION
These objects manage a real UNIX process (signalling, monitoring) within a POE::Component::Supervisor.

SIGNALLING
In order to kill a child process, first the child's standard input is closed, then the "TERM" signal is sent, and after a wait period the "KILL" signal is sent.

If the child has not died by the time the "KILL" loop times out then an error is thrown (this happens under weird OS scenarios and shouldn't happen normally).

The attributes "until_term", "until_kill" and "wait_for" determine the durations of these loops.

Initially inputs will be closed. Then, after "until_term" seconds have passed the "TERM" sending loop will start, sending the "TERM" signal with an exponential backoff.

When "until_kill" seconds have passed, from the time of the "stop" method being called, the "TERM" loop will be stopped, and instead the "KILL" signal will be sent, also with an exponential backoff.

From the time of the "stop" method being called the handle will wait for a maximum of "wait_for" seconds before giving up on the child process.

Any of these attributes may be set to "undef" to disable their corresponding behaviors (suppress sending of a certain signal, or wait indefinitely).

ATTRIBUTES
NOTE: All the attributes are generally passed in by POE::Component::Supervisor::Supervised::Proc, the factory for this class.

They are documented here because that is where their behavior is defined.

POE::Component::Supervisor::Supervised::Proc will borrow all the attributes from this class that have an "init_arg", and as such they should be passed to "new" in POE::Component::Supervisor::Supervised::Proc, while this class is never instantiated directly..

until_term
    The time to wait after closing inputs, and before sending the "TERM" signal. Defaults to one tenth of a second.

    Set to "undef" to disable sending the "TERM" signal.

until_kill
    The time to wait after closing inputs, and before sending the "KILL" signal. Defaults to 10 seconds.

    Set to "undef" to disable sending the "KILL" signal.

wait_for
    How long to keep sending exit signals for.

    Defaults to

        5 + ( $self->until_kill || $self->until_term || 0 )

enable_nested_poe
    Whether or not to call "stop" in POE::Kernel in the child program, before the callback. Only applies to code references.

    This allows a nested POE kernel to be started in the forked environment without needing to "exec" a new program.

    Defaults to true.

start_nested_poe
    Whether or not to call "run" in POE::Kernel in the child program, after the callback. Only applies to code references.

    Defaults to true.

program
    A coderef or an array ref. Passed as the "Program" parameter to the wheel, but may be wrapped depending on the values of "enable_nested_poe" and "start_nested_poe" if it's a code ref.

    Required.

wheel_parameters
    Additional parameters to pass to "new" in POE::Wheel::Run.

stdin_callback
stdout_callback
stderr_callback
    Callbacks to be fired when the corresponding POE::Wheel::Run events are handled.

    This only affects the default event handlers, if you override those by passing your own "wheel_parameters" these callbacks will never take effect.

    The arguments are passed through as is, see POE::Wheel::Run for the details.

    Not required.

pid Read only attribute containing the process ID.

exited
exit_code
exit_signal
    After the process has exited these read only attributes are filled in with the exit information.

    "exited" is the raw value of $?, and "exit_code" and "exit_signal" are the values of applying "WEXITSTATUS" and "WTERMSIG" to that value.

    See POSIX for details.

use_logger_singleton
    Changes the default value of the original MooseX::LogDispatch attribute to true.

METHODS

new Never called directly, but called by POE::Component::Supervisor::Supervised::Proc.

stop
    Stop the running process

is_running
    Check whether or not the process is still running.

EVENTS
All POE events supported by this object are currently internal, and as such the session corresponding to this object provides no useful POE interface.