NAME

Gearman::WorkerSpawner - Subprocess manager for Gearman workers in a Danga::Socket environment

SYNOPSIS

   # write your worker code here:

   package MyWorkers::BlahWorker;
   use base 'Gearman::Worker';

   sub new {
       my $class = shift;
       my $slot  = shift; # a numeric identifier for this worker
       my $params = shift; # given below
       my $self = Gearman::Worker->new;
       bless $self, $class;
       $self->register_function(blah => sub { return 42 });
       return $self;
   }

   # and your client code in some Danga::Socket environment, e.g. Perlbal:

   package Perlbal::Plugin::MyPlugin;
   sub register {
       # create one manager per process
       my $worker_manager = Gearman::WorkerSpawner->new(
           gearmand => 'external', # starts a gearmand
       );
       # add different workers
       $worker_manager->add_worker(
           class        => 'MyWorkers::BlahWorker',
           num_workers  => 4,
           worker_args  => {
               foo => 3,
               bar => 1.2,
           }, # passed as second arg to MyWorkers::BlahWorker->new()
       );
       $svc->register_hook(
           MyPlugin => proxy_read_request => sub {
               $worker_manager->add_task(Gearman::Task->new(blah => '3.14'));
           }
       );
   }

DESCRIPTION

Launches subclasses of Gearman::Worker in their own processes for communication with a gearmand. External Gearman servers may be used, or one can be created for the lifetime of the spawner.

CLASS METHODS

• Gearman::WorkerSpawner->new(%params)

  Constructor, can take the following parameters:

  • gearmand

    Specifies the location of the Gearman server to use. This may either be a comma separated list of host:port specs, or external, which specifies that the WorkerSpawner should spawn a separate process to contain a Gearman server. The advantage of using this over running gearmand externally is that the Gearman server process will halt itself in the event of the calling process' demise. Defaults to external.

  • check_period

    Time in seconds between live-worker checks. Any zombie children are reaped with waitpid during the check, and enough workers are spawned to make the total num_workers again.

  • perl

    Path to the perl(1) binary with which to execute workers. Defaults to $^X.

  • reaper

    WorkerSpawner periodically reaps any dead children of its running process. If there are non-WorkerSpawner child processes in your program, you won't know when they die. To be notified of such events, you can provide a subref as the reaper parameter which will be called with the PID of any reaped children which don't belong to WorkerSpawner.

    Along that line, only a single WorkerSpawner may be created in a process (otherwise multiple spawners would race to reap each others' children, making worker accounting impossible). As such, new() will croak if called more than once.

• Gearman::WorkerSpawner->gearmand_pid()

  Returns the PID of the gearmand which was started up if external was given as the gearmand parameter to new, or undef otherwise.

OBJECT METHODS

$spawner->add_worker(%options)

Add a new worker set to the manager. A new supervisor process will be created to manage it if one does not already exist for the worker class. Can take the following parameters:

• class

  (Required) The package name of the Gearman::Worker subclass which will register itself for work when instantiated. This need not be distinct across different calls.

• source

  (Optional) The path to the file containing the definition of 'class'; only necessary if the module can't be use'd.

• num_workers

  The number of worker children to spawn. If any child processes die they will be respawned. Defaults to 1.

• worker_args

  An opaque data structure to pass to the child process. Must be serializable via Storable.

$spawner->wait_until_all_ready()

Returns only once all worker are ready to accept jobs. This will only wait on workers which have been started since the last call to wait_until_all_ready.

$spawner->add_task($task)

$spawner->add_task($funcname, $arg, \%options)

Asynchronously submits a task to a configured Gearman server. May either take a Gearman::Task object, or the 3 arguments that the Gearman::Task constructor takes.

$spawner->stop_workers([$sig])

Tell all spawned processes to quit (by default, with SIGINT).

DESTROY

Upon destruction, stop_workers is called unless you've already called it.

$spawner->gearman_server()

Returns a list of server host:port specs. If an 'external' server was requested, its hostspec is returned.

INTERNAL METHODS

$spawner->_gearman_client()

Returns the Gearman::Client::Async object used by the spawner.

Gearman::WorkerSpawner->_supervise('My::WorkerClass', @ARGV)

Loads the given Gearman::Worker subclass, then parses additional arguments as specified by the return value of the worker class' options() class method via Getopt::Long. These options are passed to the worker object's constructor and the work method of the worker object is called repeatedly until either SIG_INT is received or the ppid changes (parent went away).

This class method is automatically executed if Gearman/WorkerSpawner.pm has no caller(), i.e. if it is run as a script rather than loaded as a module. This should only be done by other internal methods of this package (add_worker).

SEE ALSO

Gearman::Server

Gearman::Worker

Gearman::Task

Gearman::Client::Async

Getopt::Long

brian d foy's modulino article: http://www.ddj.com/dept/debug/184416165

AUTHOR

Adam Thomason, <athomason@sixapart.com>

COPYRIGHT AND LICENSE

Copyright (C) 2007-2009 by Six Apart, <cpan@sixapart.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.