NAME

Cantella::Worker::Manager::Prefork - Preforking POE worker-pool manager

SYNOPSIS

    my $manager = Cantella::Worker::Manager::Prefork->new(
      logger => $logger,
      workers => 5,
      worker_class => 'TestWorkerClass',
      max_worker_age => 3600,
      worker_args => {
        interval => 5,
        logger => $logger,
      }
    );

    $manager->start;

MANAGER-WORKER COMMUNICATION

Signals

Great care has been taken to provide with basic means of communication between a manager and its workers. The manager process will pass-on INT, TERM, USR1 and USR2 signals to it's workers, which means that you only need to worry about interacting with one process.

IO Handles

To communicate with the manager, workers can write to STDOUT and STDERR, which the manager will log at the levels of worker_stderr_log_level and worker_stdout_log_level. Currently the worker process' STDIN is reserved for internal communications, but this may change in the future.

Process Management

At start and resume time, as well as when a CHLD signal is received, the manager process will check the number of workers and spawn new ones, if appropriate. This way, even if a worker unexpectedly dies, it will be promptly replaced. If workers have detached themselves from the manager session, they will outlive their manager, so if they detect the manager has unexpectedly exited, they will signal themselves with a TERM signal and shut down gracefully to avoid unsupervised processes.

ATTRIBUTES

logger

logger - reader

Read-only Log::Dispatch instance. Defaults to a device that logs to Null. This attribute can coerce from a hash or array reference, see MooseX::Types::Log::Dispatch for details.

program_name

program_name - reader

has_program_name - predicate

Read-only non-blank string. If program_name set, the manager process will be renamed to "${program_name}-pm" and the children to "${program_name}". Please see $0 in perlvar for more information.

worker_class

worker_class - reader

Required read-only class name of the worker class, which must consume the role Cantella::Worker::Manager::Prefork.

worker_args

worker_args - reader

A read-only hash ref of arguments to be passed to instantiate the worker class. Defaults to an empty hash ref.

workers

workers - accessor

Read-write integer. The maximum number of subprocesses to have alive at any one time. Defaults to 5.

max_worker_age

max_worker_age - accessor

has_max_worker_age - predicate

clear_max_worker_age - clearer

Optional read-write integer. if this value is set, the manager will retire workers when they reach a certain age and spawn a new worker. You may have seen this behavior in mailscanner. It is useful for times when children may, in rare cases, require large amounts of memory and you want to periodically replace them to free it again.

alias

alias - accessor

Read-only string. This is the alias of the session managing the workers and will default to a UUID string by default.

close_on_call

close_on_call - accessor

Read-write boolean value option for declaring whether file descriptors should be closed in the forked process. Defaults to true.

worker_detaches

worker_detches - accessor

Read-write boolean value option for declaring whether worker processes should setsid() to detach themselves from the manager's session. Defaults to true.

worker_sets_process_group

worker_sets_process_group - accessor

Read-write boolean value option for declaring whether worker processes should setpgrp() to match the process group of the parent process. Defaults to true.

worker_priority

worker_priority - accessor

Read-write integer. The priority or niceness that should be given to children processes expressed as a delta of the parent's. For example, to give a worker process a lesser priority, use 1. To escalate the priority use a negative number. UNIX operating systems require elevated privileges to do this. Defaults to 0.

pid_to_wheel_map

pid_to_wheel_map - accessor

A read-only HashRef used to map process IDs to POE::Wheel::Run objects

wid_to_wheel_map

wid_to_wheel_map - accessor

A read-only HashRef used to map Wheel IDs to POE::Wheel::Run objects

worker_stderr_log_level

worker_stderr_log_level - reader

Log level to use when logging stderr output that comes from the child processes.

worker_stdout_log_level

worker_stdout_log_level - reader

Log level to use when logging stdout output that comes from the child processes.

METHODS

BUILD

arguments: \%args

return value: none

Sets up the manager session and its event handlers.

current_worker_count

arguments: none

return value: $number_of_live_children

Returns the number of children workers that are still alive.

worker_wheels

arguments: none

<return value:> @worker_poe_wheel_run_objects

Returns all of the wheel objects for currently living children workers

signal_workers

arguments: $signal

<return value:> none

Sends a signal to all worker processes.

start

arguments: none

return value: none

Start the manager and begin spawning workers.

pause

arguments: $until

return value: none

Pause the manager and stop it from spawning any new workers.

resume

arguments: $when

return value: none

Resume the manager and resume spawning workers.

shutdown

arguments: none

return value: none

Stop the manager from spawning any new workers and end the session after all workers have finished working.

EVENT HANDLERS

The following methods are POE event handlers. They are not menat to be called directly and will not work if you do. When applicable, arguments will be passed into the methods in ARG0, ARG1, etc.

_spawn_workers

handles event: spawn_workers

arguments: none

return value: none

Spawn workers if current_worker_count is less than workers. This is also the place where an alarm to retire a worker will be set if workers have a maximum age.

The following events are set up to communicate with children processes:

worker_process_stdout - StdoutEvent

worker_process_stderr - StderrEvent

worker_process_close - CloseEvent

worker_process_sig_chld - SIGCHLD

_retire_worker

handles event: retire_worker

arguments: $wheel_id

return value: none

If the worker process working under $wheel_id is still alive, send a sig TERM

_worker_process_close

handles event: worker_process_close

arguments: none

return value: none

See POE::Wheel::Run

_worker_process_sig_chld

handles event: worker_process_sig_chld

arguments: $pid, $exit_status_code

return value: none

Once a sig CHLD comes back from a worker, this event will schedule a spawn_workers event to make sure there's enough workers alive.

_worker_process_stdout

handles event: worker_process_stdout

arguments: $line

return value: none

This event will be triggered for every line that the child process outputs to STDOUT. By default, these will be logged to the log-level selcted with worker_stdout_log_level. See POE::Wheel::Run for more.

_worker_process_stderr

handles event: worker_process_stderr

arguments: $line

return value: none

This event will be triggered for every line that the child process outputs to STDOUT. By default, these will be logged to the log-level selcted with worker_stdout_log_level. See POE::Wheel::Run for more.

_start

handles event: _start

arguments: none

return value: none

Start the manager session.

_pause

handles event: _pause

arguments: none

return value: none

Signal workers to stop polling until notified and suspend the spawning of new workers. The pause event can be triggered by sending signal USR1

_resume

handles event: _resume

arguments: none

return value: none

Signal workers to resume polling and resume the spawning of new workers. The resume event can be triggered sending signal USR2

_shutdown

handles event: shutdown

arguments: none

return value: none

Remove all alarms, signal the workers to shutdown and wait for the session to die The shutdown event can be triggered sending signal INT or TERM

OTHER EVENTS

_keep_alive - Used to keep the session alive while paused. Does nothing other than schedule the next keep alive_1000 seconds away.

sig_int - mark sig INT as handled and yield to shutdown

sig_term - mark sig TERM as handled and yield to shutdown

sig_usr1 - mark sig USR1 as handled and yield to _pause

sig_usr2 - mark sig USR2 as handled and yield to _resume

SEE ALSO

Cantella::Worker::Role::Worker, Cantella::Worker::Role::Beanstalk

AUTHOR

Guillermo Roditi (groditi) <groditi@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2009-2010 by Guillermo Roditi. This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself.

cpanm Cantella::Worker

perl -MCPAN -e shell
install Cantella::Worker