++ed by:

5 PAUSE users
3 non-PAUSE users.

Алексей Пастухов
and 1 contributors


Gearman::Client - Client for gearman distributed job system


    use Gearman::Client;
    my $client = Gearman::Client->new;
        host      => '',
        port      => 4730,
        socket_cb => sub {...},
        use_ssl   => 1,
        ca_file   => ...,
        cert_file => ...,
        key_file  => ...,

    # running a single task
    my $result_ref = $client->do_task("add", "1+2");
    print "1 + 2 = $$result_ref\n";

    # waiting on a set of tasks in parallel
    my $taskset = $client->new_task_set;
    $taskset->add_task( "add" => "1+2", {
       on_complete => sub { ... }
    $taskset->add_task( "divide" => "5/0", {
       on_fail => sub { print "divide by zero error!\n"; },


Gearman::Client is a client class for the Gearman distributed job system, providing a framework for sending jobs to one or more Gearman servers. These jobs are then distributed out to a farm of workers.

Callers instantiate a Gearman::Client object and from it dispatch single tasks, sets of tasks, or check on the status of tasks.

Gearman::Client is derived from Gearman::Objects



Creates a new Gearman::Client object, and returns the object.

If %options is provided, initializes the new client object with the settings in %options, which can contain:

  • job_servers

    List of job servers. Value should be an array reference, hash reference or scalar.

    Calls Gearman::Objects to set job_servers

  • prefix

    Calls prefix (see below) to set the prefix / namespace.


Initializes the client $client with the list of job servers in @servers. @servers should contain a list of IP addresses, with optional port numbers. For example:

    $client->job_servers('', '');

If the port number is not provided, 4730 is used as the default.


$client->do_task($funcname, $arg, \%options)

Dispatches a task and waits on the results. May either provide a Gearman::Task object, or the 3 arguments that the Gearman::Task constructor takes.

Returns a scalar reference to the result, or undef on failure.

If you provide on_complete and on_fail handlers, they're ignored, as this function currently overrides them.

$taskset = $client->new_task_set

Creates and returns a new Gearman::Taskset object.


$taskset->add_task($funcname, $arg, $uniq)

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

Adds a task to a taskset. Three different calling conventions are available.


Waits for a response from the job server for any of the tasks listed in the taskset. Will call the on_* handlers for each of the tasks that have been completed, updated, etc. Doesn't return until everything has finished running or failing.


Sets the namespace / prefix for the function names.

See Gearman::Worker for more details.



This is an example client that sends off a request to sum up a list of integers.

    use Gearman::Client;
    use Storable qw( freeze );
    my $client = Gearman::Client->new;
    my $tasks = $client->new_task_set;
    my $handle = $tasks->add_task(sum => freeze([ 3, 5 ]), {
        on_complete => sub { print ${ $_[0] }, "\n" }

See the Gearman::Worker documentation for the worker for the sum function.



return Gearman::Taskset


return {job => {capable, queued, running}}


supported only by Gearman::Server

return {job => {address, listeners, key}}


supported only by Gearman::Server


do_task($funcname, $arg, \%options)

given a (func, arg_p, opts?)

return scalarref of WORK_COMPLETE result

dispatch_background($func, $arg_p, $options_hr)


Dispatches a task and doesn't wait for the result. Return value is an opaque scalar that can be used to refer to the task with get_status.

It is strongly recommended to set Gearman::Task uniq option to insure gearmand does not squash jobs if it store background jobs in a persistence backend. See the issue #87

return the handle from the jobserver, or undef on failure


run a hook callback if defined

add_hook($name, $cb)

add a hook


The Gearman Server will assign a scalar job handle when you request a background job with dispatch_background. Save this scalar, and use it later in order to request the status of this job.

return Gearman::JobStatus on success


Copyright 2006-2007 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.


 Brad Fitzpatrick (<brad at danga dot com>)
 Jonathan Steinert (<hachi at cpan dot org>)
 Alexei Pastuchov (<palik at cpan dot org>) co-maintainer