Gearman::Worker(3pm)

💖 Gearman::Worker 💖

okay bestie, this is the manual page for Gearman::Worker — a User Contributed Perl Documentation page, and it's giving "worker class for the gearman distributed job system." ✨

---

🌸 NAME 🌸

Gearman::Worker — the Worker for the gearman distributed job system. that's it, that's the whole name, she's simple and she's iconic 👑

---

✨ SYNOPSIS ✨

okay so this is what it looks like in the wild, no cap:

use Gearman::Worker;
my $worker = Gearman::Worker->new;
$worker->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  => ...,
  }
);

$worker->register_function($funcname => sub {
    ...
  }
);

$worker->work(
  on_start => sub {
    my ($jobhandle) = @_;
    ...
  },
  on_complete => sub {
    my ($jobhandle, $result) = @_;
    ...
  },
  on_fail => sub {
    my ($jobhandle, $err) = @_;
    ..
  },
  stop_if => sub {
    my ($is_idle, $last_job_time) = @_;
    # stop idle worker
    return $is_idle;
  },
);

like literally all the vibes are right there 💅

---

🦋 DESCRIPTION 🦋

Gearman::Worker is a worker class for the Gearman distributed job system, and it's out here providing a whole framework for receiving and serving jobs from a Gearman server. 🫶

So the way that it works: you (the caller) instantiate a Gearman::Worker object, you register a list of functions and capabilities that you can handle, and then you enter an event loop and just… wait for the server to send you jobs. main character energy fr. ⭐

And the worker can send a return value back to the server — which then gets sent back to the client that requested the job — or, alternatively, it can simply execute silently. 🤫 your choice bestie.

---

🎀 USAGE 🎀

🌈 Gearman::Worker->new(%options)

Creates a brand new Gearman::Worker object, and returns the object. ✨

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

also important, bestie: Gearman::Worker is derived from Gearman::Objects — so that inheritance is real, iykyk. 💜

• job_servers — List of job servers. The value should be an array reference, hash reference or scalar. It will be ignored if this worker is running as a child process of a gearman server. 👀
• prefix — Calls prefix (see below) to set the prefix / namespace.
• client_id — Unique worker identifier for "job_servers".

💫 $worker->prefix($prefix)

Sets the namespace / prefix for the function names. This is useful for sharing job servers between different applications, or between different instances of the same application (different development sandboxes for example). 🧚

The namespace is currently implemented as a simple tab separated concatenation of the prefix and the function name. no fancy business, just vibes. 💅

---

🍓 EXAMPLES 🍓

⭐ Summation

This is an example worker that receives a request to sum up a list of integers. she's little but she's doing the math 💖

use Gearman::Worker;
use Storable qw( thaw );
use List::Util qw( sum );
my $worker = Gearman::Worker->new;
$worker->job_servers('127.0.0.1');
$worker->register_function(sum => sub { sum @{ thaw($_[0]->arg) } });
$worker->work while 1;

See the Gearman::Client documentation for a sample client sending the sum job. 🫶

---

🙈 NOTE 🙈

If you intend to send or receive UTF-8 data over SSL connections, beware — there is no UTF-8 support in the underlying Net::SSLeay. 😭

"Forcing-Unicode-in-Perl-(Or-Unforcing-Unicode-in-Perl)" in perlunicode describes proper workarounds. so like, go read that, bestie, it's got the fixes.

---

👑 METHODS 👑

🌸 reset_abilities

This tells all the job servers that this worker can no longer do any tasks. 💀

Returns true if the "reset_abilities" request was successfully transmitted to "job_servers".

🌸 work(%opts)

This endlessly loops. It takes an applicable job, if available, does the job, and then waits for the next one. 🔁

You can pass "stop_if", "on_start", "on_complete" and "on_fail" callbacks in %opts. See "SYNOPSIS". ✨

🌸 $worker->register_function($funcname, $subref)

🌸 $worker->register_function($funcname, $timeout, $subref)

Registers the function $funcname as being provided by the worker $worker, and advertises these capabilities to all of the job servers defined in this worker. 📢

$subref must be a subroutine reference that will be invoked when the worker receives a request for this function. It will be passed a Gearman::Job object representing the job that has been received by the worker. 🎁

$timeout is an optional parameter specifying how long the jobserver will wait for your subroutine to give an answer. Exceeding this time will result in the jobserver reassigning the task and ignoring your result. 😭 This prevents a gimpy worker from ruining the 'user experience' in many situations. (thank u for ur service, timeout param 🫡)

Returns true if the $funcname registration was successfully transmitted to "job_servers".

🌸 unregister_function($funcname)

Sends a cant_do $funcname request to job_servers. 📤

Returns true if the CANT_DO $funcname request was successfully transmitted to "job_servers".

🌸 job_servers(@servers)

Overrides the Gearman::Objects method to skip job server initialization if working with Gearman::Server. 💅

Calling this method will do <b>nothing</b> in a worker that is running as a child process of a gearman server. fr fr, nothing.

🌸 send_work_complete($job, $v)

Notifies the server (and listening clients) that the job completed successfully. 🎉 slay!

🌸 send_work_data($job, $data)

Use this method to update the client with data from a running job. 📡

🌸 send_work_warning($job, $message)

Use this method to send a warning $message to the server (and any listening clients) with regard to the running "job". ⚠️

🌸 send_work_exception($job, $exception)

Use this method to notify the server (and any listening clients) that the "job" failed with the given $exception. 💥

If you are using Gearman::Client, you have to set the parameter exceptions properly to get worker exception notifications. don't forget it bestie, that's the whole trick 🫶

🌸 send_work_fail($job)

Use this method to notify the server (and any listening clients) that the job failed. 💀

🌸 send_work_status($job, $numerator, $denominator)

Use this method to send periodically to the server a status update for long running jobs, to update the percentage complete. 📊 progress bar moment ✨

🌸 _uncache_sock($js, $reason)

Closes the TCP connection. 🔌

---

🌈 WORKERS AS CHILD PROCESSES 🌈

Gearman workers can be run as child processes of a parent process which embeds Gearman::Server. 👶

When such a parent process fork/execs a worker, it sets the environment variable GEARMAN_WORKER_USE_STDIO to true before launching the worker. If this variable is set to true, then the job_servers function and option for new() are ignored, and the unix socket bound to STDIN/OUT are used instead as the IO path to the gearman server. 🦋

---

and that's the whole page, bestie!! you ate that 💅✨

this lil document is <b>perl v5.26.2</b>, dated <b>2018-08-30</b>, and it lives in the <b>Gearman::Worker(3pm)</b> section of the manual. bye ily 🫶💖🎀