NAME

MooseX::Workers::Engine - Provide the workhorse to MooseX::Workers

SYNOPSIS

    package MooseX::Workers;

    has Engine => (
        isa      => 'MooseX::Workers::Engine',
        is       => 'ro',
        lazy     => 1,
        required => 1,
        default  => sub { MooseX::Workers::Engine->new( visitor => $_[0] ) },
        handles  => [
            qw(
              max_workers
              has_workers
              num_workers
              put_worker
              kill_worker
              )
        ],
    );

DESCRIPTION

MooseX::Workers::Engine provides the main functionality to MooseX::Workers. It wraps a POE::Session and as many POE::Wheel::Run objects as it needs.

ATTRIBUTES

visitor

Hold a reference to our main object so we can use the callbacks on it.

max_workers

An Integer specifying the maximum number of workers we have.

workers

An ArrayRef of POE::Wheel::Run objects that are our workers.

session

Contains the POE::Session that controls the workers.

METHODS

yield

Helper method to post events to our internal manager session.

call

Helper method to call events to our internal manager session. This is synchronous and will block incoming data from the children if it takes too long to return.

set_worker($key)

Set the worker at $key

get_worker($key)

Retrieve the worker at $key

delete_worker($key)

Remove the worker atx $key

has_workers

Check to see if we have *any* workers currently. This is delegated to the MooseX::Workers::Engine object.

num_workers

Return the current number of workers. This is delegated to the MooseX::Workers::Engine object.

has_manager

Check to see if we have a manager session.

remove_manager

Remove the manager session.

meta

The Metaclass for MooseX::Workers::Engine see Moose's documentation.

EVENTS

add_worker ($command)

Create a POE::Wheel::Run object to handle $command. If $command holds a scalar, it will be executed as exec($scalar). Shell metacharacters will be expanded in this form. If $command holds an array reference, it will executed as exec(@$array). This form of exec() doesn't expand shell metacharacters. If $command holds a code reference, it will be called in the forked child process, and then the child will exit.

See POE::Wheel::Run for more details.

INTERFACE

MooseX::Worker::Engine fires the following callbacks to its visitor object:

worker_manager_start

Called when the managing session is started.

worker_manager_stop

Called when the managing session stops.

max_workers_reached

Called when we reach the maximum number of workers.

worker_stdout

Called when a child prints to STDOUT.

worker_stderr

Called when a child prints to STDERR.

worker_error

Called when there is an error condition detected with the child.

worker_done

Called when a worker completes $command.

worker_started

Called when a worker starts $command.

sig_child($PID, $ret)

Called when the managing session receives a SIG CHLD event.

sig_*

Called when the underlying POE Kernel receives a signal; this is not limited to OS signals (ie. what you'd usually handle in Perl's %SIG) so will also accept arbitrary POE signals (sent via POE::Kernel->signal), but does exclude SIGCHLD/SIGCHILD, which is instead handled by sig_child above.

These interface methods are automatically inserted when MooseX::Worker::Engine detects that the visitor object contains any methods beginning with sig_. Signals are case-sensitive, so if you wish to handle a TERM signal, you must define a sig_TERM() method. Note also that this action is performed upon MooseX::Worker::Engine startup, so any run-time modification of the visitor object is not likely to be detected.