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.