---
name: "Gearman::Client"
section: "3pm"
platform: "linux"
package: "libgearman-client-perl"
version: "2.004.015-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Gearman::Client"
---

# Gearman::Client(3pm)

Client for gearman distributed job system

## 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',
      {
        host      => '10.0.0.1',
        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", {
      on_fail => sub {...},
      on_complete => sub {...}
    });
    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.

*Gearman::Client* is derived from Gearman::Objects

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

- •

  exceptions

  If true, the client sends an OPTION\_REQ exceptions \<http://gearman.org/protocol/\> request for each connection to the job server. This causes job server to forward WORK\_EXCEPTION packets to the client.

- •

  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 Gearman::Objects) to set the prefix / namespace.

- •

  command\_timeout

  Maximum time a gearman command should take to get a result (not a job timeout)

  default: 30 seconds

- •

  backoff\_max

  Max number of failed connection attempts before an job server will be temporary disabled

  default: 90

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

## NOTE

If you intend using UTF-8 data with SSL based connection, beware there is no UTF-8 support in underlying Net::SSLeay. "Forcing-Unicode-in-Perl-(Or-Unforcing-Unicode-in-Perl)" in perlunicode describes proper workarounds.

## METHODS

### *new\_task\_set()*

Creates and returns a new Gearman::Taskset object.

### *get\_job\_server\_status()*

**return** `"{job_server => {job => {capable, queued, running}}}"`

### *get\_job\_server\_jobs()*

supported only by Gearman::Server

**return** `"{job-server => {job => {address, listeners, key}}}"`

### *get\_job\_server\_clients()*

supported only by Gearman::Server

### do\_task($task)

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

**return** scalarref of WORK\_COMPLETE result, or undef on failure.

### dispatch\_background($func, $arg\_p, $options\_hr)

### dispatch\_background($task)

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 \<https://github.com/gearman/gearmand/issues/87#issuecomment-291119785\>

**return** the handle from the jobserver, or undef on failure

### run\_hook($name)

run a hook callback if defined

### add\_hook($name, $cb)

add a hook

### get\_status($handle)

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

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 at danga dot com>)
 Jonathan Steinert (<hachi at cpan dot org>)
 Alexei Pastuchov (<palik at cpan dot org>) co-maintainer
```

## REPOSITORY

\<https://github.com/p-alik/perl-Gearman.git\>