Gearman::Client(3pm)

💖 Gearman::Client 💖

okay bestie, so this is a page from the User Contributed Perl Documentation, and it's all about Gearman::Client — the 3pm one. it's giving "i want to boss around a whole farm of workers" energy and honestly? iconic. let's get into it 🫶

---

✨ NAME ✨

Gearman::Client — the client for the gearman distributed job system. no cap. 🌸

---

🌈 SYNOPSIS 🌈

like, here's the vibe:

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;

so you make a client, you tell it where the job servers live, and then you either yeet one single task off or you line up a whole lil squad of them and wait. periodt. ✨

---

🦋 DESCRIPTION 🦋

Gearman::Client is a client class for the Gearman distributed job system — it's the framework you use to send jobs off to one or more Gearman servers. and then? those jobs get distributed out to a whole farm of workers. it's giving delegation, it's giving management, it's giving main character energy 👑

so here's how it goes: you instantiate a Gearman::Client object, and from that object you dispatch single tasks, sets of tasks, or you check on the status of tasks. that's the whole loop bestie.

and lowkey important: Gearman::Client is derived from Gearman::Objects 🧬

---

💅 USAGE 💅

Gearman::Client->new(%options)

makes you a brand new Gearman::Client object and hands it back to you. slay.

if you pass in %options, it initializes the fresh new client object with whatever settings are in %options. and those can contain:

• exceptions — if this is true, the client sends an OPTION_REQ exceptions <http://gearman.org/protocol/> request for each connection to the job server. what does that do? it makes the job server forward WORK_EXCEPTION packets to the client. so you actually hear about it when things go wrong. 🙈
• job_servers — a list of job servers. the value should be an array reference, a hash reference, or a scalar.

it calls Gearman::Objects to set job_servers.

• prefix — calls prefix (see Gearman::Objects) to set the prefix / namespace.
• command_timeout — the maximum time a gearman command should take to get a result. and no, bestie, this is not a job timeout, don't get it twisted. 🚨

default: 30 seconds

• backoff_max — the max number of failed connection attempts before a job server gets temporarily disabled.

default: 90

---

🎀 EXAMPLES 🎀

Summation

this is an example client that sends off a request to sum up a list of integers. math but make it distributed fr fr.

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;

and if you wanna see the worker side of the sum function, go check the Gearman::Worker documentation. team effort 💖

---

⚠️ NOTE ⚠️

okay this one matters, listen up. if you intend to use UTF-8 data with an SSL based connection, beware: there is no UTF-8 support in the underlying Net::SSLeay.

the workaround tea is in "Forcing-Unicode-in-Perl-(Or-Unforcing-Unicode-in-Perl)" in perlunicode — that describes the proper workarounds. go read it, i'm not playing 😭

---

🔥 METHODS 🔥

new_task_set()

creates and returns a new Gearman::Taskset object. shiny new taskset, just for you ✨

get_job_server_status()

returns "{job_server => {job => {capable, queued, running}}}"

get_job_server_jobs()

supported only by Gearman::Server.

returns "{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. you can either hand it a Gearman::Task object, or the 3 arguments that the Gearman::Task constructor takes. your choice, bestie.

returns a scalarref of the 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. it's giving set it and forget it. the return value is an opaque scalar that you can use to refer to the task later with get_status.

it is strongly recommended to set the 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>

returns the handle from the jobserver, or undef on failure.

run_hook($name)

run a hook callback, if one is 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. so save that scalar!! and then use it later to request the status of this job. that's the whole trick, iykyk 🫶

returns 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. none. zero. nada. 💀

---

👑 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>

---

and that's the whole page bestie!! 🎀 this one came from perl v5.26.2, dated 2018-08-30, and it's the Gearman::Client(3pm) page — go forth and distribute some jobs, you absolute legend 💅✨🦋