NAME

POE::Component::Gearman::Client - Asynchronous client module for Gearman for POE applications

SYNOPSIS

    use POE qw(Component::Gearman::Client);

    # Instantiate a new client session.
    POE::Component::Gearman::Client->spawn(
        alias => 'my_gearman_client',
        job_servers => [ '127.0.0.1', '192.168.0.1:123' ],
    );

    # Overwrite job server list with a new one.
    POE::Kernel->post('my_gearman_client' => 'set_job_servers', ['10.0.0.1']);

    # Start a task
    $task = Gearman::Task->new(...); # with callbacks, etc
    POE::Kernel->post('my_gearman_client' => 'add_task', $task);

    # if you keep a reference to the client object you can also 
    # get a list of job servers during runtime:
    my $client = POE::Component::Gearman::Client->spawn(...);
    $arrayref = $client->job_servers;
    @array = $client->job_servers;

ABSTRACT

This module lets provides an asynchronous interface to submit jobs to Gearman servers in a POE application.

PUBLIC METHODS

spawn

A program must spawn at least one POE::Component::Gearman::Client instance before it can submit jobs to Gearman servers. A reference to the object is returned if you need to call methods such as job_servers, otherwise you won't need to store it.

The following parameters can be passed to the spawn constructor.

alias

(Optional) This parameter will be used to set POE's internal session alias. This is useful to post events and is also very important if you instantiate multiple clients. If left empty, the alias will be set to "Gearman".

job_servers

(Optional) This parameter can contain an arrayref of IP:port host specifications.

job_servers

This method returns an ARRAY or ARRAYREF (depending on the calling context) containing IP:port specification of the configured job servers.

POE EVENTS

set_job_servers

Posting this event to your POE::Component::Gearman::Client client lets you set the current job server list (by overriding the existing one if any).

        $kernel->post('Gearman', 'set_job_servers', ['10.0.0.1']);

Gearman is the alias name (see above about alias parameter), and the passed argument is an ARRAYREF containing the server definitions in IP:port syntax.

add_task

Posting this event to your POE::Component::Gearman::Client client lets you submit a task.

        $kernel->post('Gearman', 'add_task', $task);

Gearman is the alias name (see above about alias parameter), and $task is a Gearman::Task object.

Warning: you can't call POE::Kernel's methods like yield(), delay() etc. from within a task callback, because callbacks will be executed within POE::Component::Gearman::Client's session instead of yours. Thus, the only methods you can call are post() and call() because they let you specify the destination session. See example:

    # WRONG
    sub submit_task {
        my $kernel = $_[KERNEL];
        my $cb = sub {
            $kernel->delay('submit_task', 60);  # this won't be called within your session!
        };
        my $task = Gearman::Task->new('do_task', \'', { on_complete => $cb });
        POE::Kernel->post('Gearman' => 'add_task', $task);
    }
    
    # CORRECT
    sub submit_task {
        my ($kernel, $session) = @_[KERNEL, SESSION];
        my $cb = sub {
            $kernel->post($session => 'task_done');
        };
        my $task = Gearman::Task->new('do_task', \'', { on_complete => $cb });
        POE::Kernel->post('Gearman' => 'add_task', $task);
    }
    sub task_done {
        $_[KERNEL]->delay('submit_task', 60);
    }

disconnect_all

Posting this event to your POE::Component::Gearman::Client client will disconnect the client from all job servers, allowing your POE application to shutdown if you want so.

        $kernel->post('Gearman', 'disconnect_all');

Gearman is the alias name (see above about alias parameter).

SEE ALSO

• Gearman::Task

• Gearman::Client::Async

COPYRIGHT

Copyright Alessandro Ranellucci Some code copyright Six Apart, Ltd.

License granted to use/distribute under the same terms as Perl itself.

WARRANTY

This is free software. This comes with no warranty whatsoever.

AUTHORS

 Alessandro Ranellucci (aar@cpan.org)
 based on code by Brad Fitzpatrick (brad@danga.com)