The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.


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


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

    # Instantiate a new client session.
        alias => 'my_gearman_client',
        job_servers => [ '', '' ],

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

    # 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;


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



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.


(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".


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


This method returns an ARRAY or ARRAYREF (depending on the calling context) containing IP:port specification of the configured 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', ['']);

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.


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

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



Copyright Alessandro Ranellucci Some code copyright Six Apart, Ltd.

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


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


 Alessandro Ranellucci (
 based on code by Brad Fitzpatrick (