/ 
Gearman-1.01
River stage two • 15 direct dependents • 22 total dependents
/ Gearman::Client

NAME

Gearman::Client - Client for gearman distributed job system

SYNOPSIS

use Gearman::Client;
my $client = Gearman::Client->new;
$client->job_servers('127.0.0.1', '10.0.0.1');

# 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"; },
});
$taskset->wait;

DESCRIPTION

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.

USAGE

Gearman::Client->new(%options)

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

    Calls job_servers (see below) to initialize the list of job servers. Value in this case should be an arrayref.

$client->job_servers(@servers)

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('127.0.0.1', '192.168.1.100:7003');

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

$client->do_task($task)

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

$client->dispatch_background($task)

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

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.

$taskset = $client->new_task_set

Creates and returns a new Gearman::Taskset object.

$taskset->add_task($task)

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

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

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

$taskset->wait

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.

EXAMPLES

Summation

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;
$client->job_servers('127.0.0.1');
my $tasks = $client->new_task_set;
my $handle = $tasks->add_task(sum => freeze([ 3, 5 ]), {
    on_complete => sub { print ${ $_[0] }, "\n" }
});
$tasks->wait;

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