NAME
    Gearman::Driver - Manage Gearman workers

SYNOPSIS
        package My::Workers::One;

        use base qw(Gearman::Driver::Worker);
        use Moose;

        # this method will be registered with gearmand as 'My::Workers::One::scale_image'
        sub scale_image : Job {
            my ( $self, $job ) = @_;
            # do something
        }

        # this method will be registered with gearmand as 'My::Workers::One::do_something_else'
        sub do_something_else : Job : MinChilds(2) : MaxChilds(15) {
            my ( $self, $job ) = @_;
            # do something
        }

        # this method wont be registered with gearmand at all
        sub do_something_internal {
            my ( $self, $job ) = @_;
            # do something
        }

        1;

        package My::Workers::Two;

        use base qw(Gearman::Driver::Worker);
        use Moose;

        # this method will be registered with gearmand as 'My::Workers::Two::scale_image'
        sub scale_image : Job {
            my ( $self, $job ) = @_;
            # do something
        }

        1;

        package main;

        use Gearman::Driver;

        my $driver = Gearman::Driver->new(
            namespaces => [qw(My::Workers)],
            server     => 'localhost:4730,otherhost:4731',
            interval   => 60,
        );

        $driver->run;

DESCRIPTION
    Having hundreds of Gearman workers running in separate processes can
    consume a lot of RAM. Often many of these workers share the same
    code/objects, like the database layer using DBIx::Class for example.
    This is where Gearman::Driver comes in handy:

    You write some base class which inherits from Gearman::Driver::Worker.
    Your base class loads your database layer for example. Each of your
    worker classes inherit from that base class. In the worker classes you
    can register single methods as jobs with gearmand. It's even possible to
    control how many workers doing that job/method in parallel. And this is
    the point where you'll save some RAM: Instead of starting each worker in
    a separate process Gearman::Driver will fork each worker from the main
    process. This will take advantage of copy-on-write on Linux and save
    some RAM.

    There's only one mandatory parameter which has to be set when calling
    the constructor: namespaces

        use Gearman::Driver;
        my $driver = Gearman::Driver->new( namespaces => [qw(My::Workers)] );

    See also: "namespaces" in Gearman::Driver. If you do not set "server"
    (gearmand) attribute the default will be used: "localhost:4730"

    Each module found in your namespace will be loaded and introspected,
    looking for methods having the 'Job' attribute set:

        package My::Workers::ONE;

        sub scale_image : Job {
            my ( $self, $job ) = @_;
            # do something
        }

    This method will be registered as job function with gearmand, verify it
    by doing:

        plu@mbp ~$ telnet localhost 4730
        Trying ::1...
        Connected to localhost.
        Escape character is '^]'.
        status
        My::Workers::ONE::scale_image   0       0       1
        .
        ^]
        telnet> Connection closed.

    If you dont like to use the full package name you can also specify a
    custom prefix:

        package My::Workers::ONE;

        sub prefix { 'foo_bar_' }

        sub scale_image : Job {
            my ( $self, $job ) = @_;
            # do something
        }

    This would register 'foo_bar_scale_image' with gearmand.

    See also: "prefix" in Gearman::Driver::Worker

ATTRIBUTES
  namespaces
    Will be passed to Module::Find "useall" method to load worker modules.
    Each one of those modules has to be inherited from
    Gearman::Driver::Worker or a subclass of it. It's also possible to use
    the full package name to load a single module/file. There is also a
    method "get_namespaces" in Gearman::Driver which returns a sorted list
    of all namespaces.

    * isa: ArrayRef
    * required: True

  modules
    Every worker module loaded by Module::Find will be added to this list.
    There are also two methods: "get_modules" in Gearman::Driver and
    "has_modules" in Gearman::Driver.

    * isa: ArrayRef
    * readonly: True

  wheels
    Stores all Gearman::Driver::Wheel instances. The key is the name the job
    gets registered with gearmand. There are also two methods: "get_wheel"
    in Gearman::Driver and "has_wheel" in Gearman::Driver.

    Example:

        {
            'My::Workers::ONE::scale_image'       => bless( {...}, 'Gearman::Driver::Wheel' ),
            'My::Workers::ONE::do_something_else' => bless( {...}, 'Gearman::Driver::Wheel' ),
            'My::Workers::TWO::scale_image'       => bless( {...}, 'Gearman::Driver::Wheel' ),
        }

    * isa: HashRef
    * readonly: True

  server
    A list of Gearman servers the workers should connect to. The format for
    the server list is: "host[:port][,host[:port]]"

    See also: Gearman::XS

    * default: localhost:4730
    * isa: Str

  interval
    Each n seconds Net::Telnet::Gearman is used in Gearman::Driver::Observer
    to check status of free/running/busy workers on gearmand. This is used
    to fork more workers depending on the queue size and the
    MinChilds/MaxChilds attribute of the job method. See also:
    Gearman::Driver::Worker

    * default: 5
    * isa: Int

  observer
    Instance of Gearman::Driver::Observer.

    * isa: Gearman::Driver::Observer
    * readonly: True

  logfile
    Path to logfile.

    * isa: Str
    * default: gearman_driver.log

  loglayout
    See also Log::Log4perl.

    * isa: Str
    * default: "[%d] %m%n"

  loglevel
    See also Log::Log4perl.

    * isa: Str
    * default: INFO

  unknown_job_callback
    Whenever Gearman::Driver::Observer sees a job that isnt handled it will
    call this CodeRef, passing following arguments:

    * $driver
    * $status

        my $driver = Gearman::Driver->new(
            namespaces           => [qw(My::Workers)],
            unknown_job_callback => sub {
                my ( $driver, $status ) = @_;
                # notify nagios here for example
            }
        );

    $status might look like:

        $VAR1 = {
            'busy'    => 0,
            'free'    => 0,
            'name'    => 'GDExamples::Sleeper::unknown_job',
            'queue'   => 6,
            'running' => 0
        };

METHODS
  get_namespaces
    Returns a sorted list of "namespaces" in Gearman::Driver.

  get_modules
    Returns a sorted list of "modules" in Gearman::Driver.

  has_modules
    Returns the count of "modules" in Gearman::Driver.

  has_wheel
    Params: $name

    Returns true/false if the wheel exists.

  get_wheel
    Params: $name

    Returns the wheel instance.

  run
    This must be called after the Gearman::Driver object is instantiated.

AUTHOR
    Johannes Plunien <plu@cpan.org>

COPYRIGHT AND LICENSE
    Copyright 2009 by Johannes Plunien

    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself.

SEE ALSO
    * Gearman::Driver::Observer
    * Gearman::Driver::Wheel
    * Gearman::Driver::Worker
    * Gearman::XS
    * Log::Log4perl
    * Module::Find
    * Moose
    * MooseX::Getopt
    * MooseX::Log::Log4perl
    * MooseX::MethodAttributes
    * Net::Telnet::Gearman
    * POE
    * <http://www.gearman.org/>

REPOSITORY
    <http://github.com/plu/gearman-driver/>

