NAME
EV::Gearman::Job - a job dispatched to a worker callback
SYNOPSIS
$g->register_function(slow_compute => { async => 1 }, sub {
my ($job) = @_;
# introspect
my $h = $job->handle; # 'H:host:42'
my $f = $job->function; # 'slow_compute'
my $u = $job->unique; # set if grab_unique => 1
my $w = $job->workload; # request bytes
# progress / partial-result events delivered to the client
$job->status(50, 100);
$job->send_data("partial chunk");
$job->warning("non-fatal warning");
$job->exception("rich error info"); # if exceptions option set
# terminal
$job->complete($result); # success (sends WORK_COMPLETE)
$job->fail; # failure (sends WORK_FAIL)
});DESCRIPTION
A job object is created by EV::Gearman when a JOB_ASSIGN / JOB_ASSIGN_UNIQ packet arrives, and passed as the sole argument to the function callback registered with register_function.
In sync mode (default), you typically just return a result from your callback — the worker translates that into WORK_COMPLETE. die becomes WORK_FAIL. The job methods below are still available for sending intermediate events.
In async mode, the callback returns immediately; you must explicitly call complete, fail, or exception later. The job object can be stashed in a closure or any other long-lived container — it carries the connection pointer plus a magic word that's checked on every send.
If the underlying EV::Gearman connection has been destroyed by the time you call a job method, the call croaks with "client destroyed"; this prevents use-after-free.
ACCESSORS
handle
Server-assigned job handle (e.g. H:host:42).
function
Function name as registered.
unique
Submitter-supplied unique key. Empty string if the worker did not opt into grab_unique => 1 (the server only sends the unique key with JOB_ASSIGN_UNIQ).
workload
The job payload bytes.
data
Alias for workload.
EVENT METHODS
These methods send packets back to the job server; the foreground client (if any) receives the corresponding WORK_* events demultiplexed by handle.
send_data($bytes)
Send a partial WORK_DATA chunk. The client's on_data fires.
warning($bytes)
Send WORK_WARNING. The client's on_warning fires.
status($numerator, $denominator)
Send progress as WORK_STATUS. Both values are sent as strings, so any printable form is accepted ("42", "3.14", ...). The client's on_status fires with the same two values.
TERMINAL METHODS
Exactly one of these should be called per job in async mode; in sync mode the worker calls one for you based on your callback's return value or thrown exception. Sending a second terminal packet produces a JOB_NOT_FOUND error from gearmand (which arrives as a connection-level error), so don't follow exception with fail.
complete([$result])
Send WORK_COMPLETE. $result defaults to the empty string.
fail
Send WORK_FAIL.
exception($bytes)
Send WORK_EXCEPTION. Terminal at the server: gearmand forwards the data to the foreground client and then marks the job as failed, so do not also call fail. Only delivered to clients that requested the exceptions option (either via the constructor's exceptions => 1 or via $cli->option('exceptions')); other clients see a plain WORK_FAIL.