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.

       •   prefix

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

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

   $client->prefix($prefix)
       Sets the namespace / prefix for the function names.

       See Gearman::Worker for more details.

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.

COPYRIGHT

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

        Brad Fitzpatrick (brad@danga.com)
        Jonathan Steinert (hachi@cpan.org)