NAME

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

SYNOPSIS

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

    my $worker_manager = Gearman::WorkerSpawner->new;

    # add one or more workers
    $worker_manager->add_worker(
        class        => 'AdditionWorker',
        num_workers  => 4,
        config       => {
            left_hand => 3,
        },
    );
    $worker_manager->run_method(adder => { right_hand => 3 }, sub {
        my $return = shift;
        print $return->{sum};
    });
    Danga::Socket->EventLoop;

    # and in the worker:

    package MethodWorker;
    use base 'Gearman::WorkerSpawner::BaseWorker';

    sub new {
        my MethodWorker $self = fields::new(shift);
        $self->SUPER::new(@_);

        $self->register_method(adder => \&add);
        return $self;
    }

    sub add {
        my MethodWorker $self = shift;
        my $args = shift;
        return { sum => $self->{config}{left_hand} + $args->{right_hand} };
    }

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 an array reference of host:port specs ; or a comma separated list of host:port specs; or auto, 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; the disadvantage is that you give up gearmand redundancy. Defaults to auto.

  • 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 and exit code 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.

  • sigchld

    If true, a SIGCHLD handler is installed which immediately schedules a child check, rather than waiting upwards of check_period seconds. Defaults to true.

• Gearman::WorkerSpawner->old

  Returns the Gearman::WorkerSpawner object created by a previous call to ->new. Use this if you need a WorkerSpawner in multiple places in your code within the same process and passing the object is tricky.

• Gearman::WorkerSpawner->gearmand_pid()

  Returns the PID of the gearmand which was started up if auto 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 for some reason.

• caller_source

  (Optional) If true, assume that the source for 'class' is the calling module or script. This will generally fail if the working directory has changed since program startup. This overrides source if both are provided.

• num_workers

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

• config

  An opaque data structure to pass to the child process, generally used to keep configuration that is specific to the worker but not any one job. 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->run_method($funcname, $arg, \%options)

$spawner->run_method($funcname, $arg, $callback)

Submits a task but with less boilerplate than add_task. %options is the same as for add_task. Marshaling of $arg is done for you in a manner compatible with methods created with Gearman::WorkerSpawner::BaseWorker::register_method. The on_fail handler will be called if marshalling fails for some reason.

If the second form is used, an empty %options is created and $callback is used as the on_complete handler.

method_suffix([$suffix])

Accessor for the suffix which is appended to the method name. Defaults to '_m'.

$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_servers()

Returns an arrayref of server host:port specs. If an 'auto' server was requested, its hostspec is included.

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).

BUGS

• add_worker may sleep in attempt to recontact an unreachable supervisor process. This is detrimental if a worker is added after the Danga::Socket event loop is running.

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@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2007-2011 by Say Media Inc, <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.