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 outlives the connection safely.
If the underlying EV::Gearman connection has been destroyed by the time you call a job method, the call croaks with "client destroyed". If the client is alive but currently disconnected (even with reconnect armed), the call croaks with "not connected": gearmand forgets the job when the connection drops, so a packet queued for the next session would only earn a JOB_NOT_FOUND error there. The job holds an internal tombstone reference that keeps the connection's control block allocated (but torn down) until every job referencing it is released, so this check is sound — it never reads freed memory. The back-pointer is stored as perl magic, not a hash key: user code, hash walkers, and serializers cannot see or clobber it, and a job hash that did not come from a JOB_ASSIGN croaks with "stale job" instead of dereferencing a forged pointer. Note that job objects are not serializable; a Storable round-trip produces a job that croaks "stale job".
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.