.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Gearman::Worker 3pm"
.TH Gearman::Worker 3pm "2016-08-10" "perl v5.22.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Gearman::Worker \- Worker for gearman distributed job system
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    use Gearman::Worker;
\&    my $worker = Gearman::Worker\->new;
\&    $worker\->job_servers(\*(Aq127.0.0.1\*(Aq);
\&    $worker\->register_function($funcname => $subref);
\&    $worker\->work while 1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIGearman::Worker\fR is a worker class for the Gearman distributed job system,
providing a framework for receiving and serving jobs from a Gearman server.
.PP
Callers instantiate a \fIGearman::Worker\fR object, register a list of functions
and capabilities that they can handle, then enter an event loop, waiting
for the server to send jobs.
.PP
The worker can send a return value back to the server, which then gets
sent back to the client that requested the job; or it can simply execute
silently.
.SH "USAGE"
.IX Header "USAGE"
.SS "Gearman::Worker\->new(%options)"
.IX Subsection "Gearman::Worker->new(%options)"
Creates a new \fIGearman::Worker\fR object, and returns the object.
.PP
If \fI\f(CI%options\fI\fR is provided, initializes the new worker object with the
settings in \fI\f(CI%options\fI\fR, which can contain:
.IP "\(bu" 4
job_servers
.Sp
Calls \fIjob_servers\fR (see below) to initialize the list of job
servers. It will be ignored if this worker is running as a child
process of a gearman server.
.IP "\(bu" 4
prefix
.Sp
Calls \fIprefix\fR (see below) to set the prefix / namespace.
.ie n .SS "$client\->prefix($prefix)"
.el .SS "\f(CW$client\fP\->prefix($prefix)"
.IX Subsection "$client->prefix($prefix)"
Sets the namespace / prefix for the function names.  This is useful
for sharing job servers between different applications or different
instances of the same application (different development sandboxes for
example).
.PP
The namespace is currently implemented as a simple tab separated
concatenation of the prefix and the function name.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Summation"
.IX Subsection "Summation"
This is an example worker that receives a request to sum up a list of
integers.
.PP
.Vb 7
\&    use Gearman::Worker;
\&    use Storable qw( thaw );
\&    use List::Util qw( sum );
\&    my $worker = Gearman::Worker\->new;
\&    $worker\->job_servers(\*(Aq127.0.0.1\*(Aq);
\&    $worker\->register_function(sum => sub { sum @{ thaw($_[0]\->arg) } });
\&    $worker\->work while 1;
.Ve
.PP
See the \fIGearman::Client\fR documentation for a sample client sending the
\&\fIsum\fR job.
.SH "METHODS"
.IX Header "METHODS"
.SS "reset_abilities"
.IX Subsection "reset_abilities"
tell all the jobservers that this worker can't do anything
.ie n .SS "uncache_sock($ipport, $reason)"
.el .SS "uncache_sock($ipport, \f(CW$reason\fP)"
.IX Subsection "uncache_sock($ipport, $reason)"
close \s-1TCP\s0 connection
.SS "work(%opts)"
.IX Subsection "work(%opts)"
Endless loop takes a job and wait for the next one.
You can pass \*(L"stop_if\*(R", \*(L"on_start\*(R", \*(L"on_complete\*(R" and \*(L"on_fail\*(R" callbacks in \fI\f(CI%opts\fI\fR.
.ie n .SS "$worker\->register_function($funcname, $subref)"
.el .SS "\f(CW$worker\fP\->register_function($funcname, \f(CW$subref\fP)"
.IX Subsection "$worker->register_function($funcname, $subref)"
.ie n .SS "$worker\->register_function($funcname, $timeout, $subref)"
.el .SS "\f(CW$worker\fP\->register_function($funcname, \f(CW$timeout\fP, \f(CW$subref\fP)"
.IX Subsection "$worker->register_function($funcname, $timeout, $subref)"
Registers the function \fI\f(CI$funcname\fI\fR as being provided by the worker
\&\fI\f(CI$worker\fI\fR, and advertises these capabilities to all of the job servers
defined in this worker.
.PP
\&\fI\f(CI$subref\fI\fR must be a subroutine reference that will be invoked when the
worker receives a request for this function. It will be passed a
\&\fIGearman::Job\fR object representing the job that has been received by the
worker.
.PP
\&\fI\f(CI$timeout\fI\fR 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.
.PP
The subroutine reference can return a return value, which will be sent back
to the job server.
.SS "unregister_function($funcname)"
.IX Subsection "unregister_function($funcname)"
.SS "job_servers(@servers)"
.IX Subsection "job_servers(@servers)"
override Gearman::Objects method to skip job server initialization
if defined \f(CW$ENV{GEARMAN_WORKER_USE_STDIO}\fR
.PP
Calling this method will do nothing in a worker that is running as a child
process of a gearman server.
.SH "WORKERS AS CHILD PROCESSES"
.IX Header "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
\&\s-1GEARMAN_WORKER_USE_STDIO\s0 to true before launching the worker. If this
variable is set to true, then the jobservers function and option for
\&\fInew()\fR are ignored and the unix socket bound to \s-1STDIN/OUT\s0 are used
instead as the \s-1IO\s0 path to the gearman server.