.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
.\"
.\" 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 >0, 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
.\}
.\" ========================================================================
.\"
.IX Title "Gearman::Client 3pm"
.TH Gearman::Client 3pm "2018-08-30" "perl v5.26.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::Client \- Client for gearman distributed job system
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 10
\& use Gearman::Client;
\& my $client = Gearman::Client\->new;
\& $client\->job_servers(
\& \*(Aq127.0.0.1\*(Aq,
\& {
\& host => \*(Aq10.0.0.1\*(Aq,
\& 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\en";
\&
\& # 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!\en"; },
\& });
\& $taskset\->wait;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIGearman::Client\fR is a client class for the Gearman distributed job
system, providing a framework for sending jobs to one or more Gearman
servers. These jobs are then distributed out to a farm of workers.
.PP
Callers instantiate a \fIGearman::Client\fR object and from it dispatch
single tasks, sets of tasks, or check on the status of tasks.
.PP
\&\fIGearman::Client\fR is derived from Gearman::Objects
.SH "USAGE"
.IX Header "USAGE"
.SS "Gearman::Client\->new(%options)"
.IX Subsection "Gearman::Client->new(%options)"
Creates a new \fIGearman::Client\fR object, and returns the object.
.PP
If \fI\f(CI%options\fI\fR is provided, initializes the new client object with the
settings in \fI\f(CI%options\fI\fR, which can contain:
.IP "\(bu" 4
exceptions
.Sp
If true, the client sends an \s-1OPTION_REQ\s0 exceptions request for each connection to the job server.
This causes job server to forward \s-1WORK_EXCEPTION\s0 packets to the client.
.IP "\(bu" 4
job_servers
.Sp
List of job servers. Value should be an array reference, hash reference
or scalar.
.Sp
Calls Gearman::Objects to set \fIjob_servers\fR
.IP "\(bu" 4
prefix
.Sp
Calls \fIprefix\fR (see Gearman::Objects) to set the prefix / namespace.
.IP "\(bu" 4
command_timeout
.Sp
Maximum time a gearman command should take to get a result (not a job timeout)
.Sp
default: 30 seconds
.IP "\(bu" 4
backoff_max
.Sp
Max number of failed connection attempts before an job server will be temporary disabled
.Sp
default: 90
.SH "EXAMPLES"
.IX Header "EXAMPLES"
.SS "Summation"
.IX Subsection "Summation"
This is an example client that sends off a request to sum up a list of
integers.
.PP
.Vb 9
\& use Gearman::Client;
\& use Storable qw( freeze );
\& my $client = Gearman::Client\->new;
\& $client\->job_servers(\*(Aq127.0.0.1\*(Aq);
\& my $tasks = $client\->new_task_set;
\& my $handle = $tasks\->add_task(sum => freeze([ 3, 5 ]), {
\& on_complete => sub { print ${ $_[0] }, "\en" }
\& });
\& $tasks\->wait;
.Ve
.PP
See the Gearman::Worker documentation for the worker for the \fIsum\fR
function.
.SH "NOTE"
.IX Header "NOTE"
If you intend using \s-1UTF\-8\s0 data with \s-1SSL\s0 based connection,
beware there is no \s-1UTF\-8\s0 support in underlying Net::SSLeay.
\&\*(L"Forcing\-Unicode\-in\-Perl\-(Or\-Unforcing\-Unicode\-in\-Perl)\*(R" in perlunicode describes proper workarounds.
.SH "METHODS"
.IX Header "METHODS"
.SS "\fInew_task_set()\fP"
.IX Subsection "new_task_set()"
Creates and returns a new Gearman::Taskset object.
.SS "\fIget_job_server_status()\fP"
.IX Subsection "get_job_server_status()"
\&\fBreturn\fR \f(CW\*(C`{job_server => {job => {capable, queued, running}}}\*(C'\fR
.SS "\fIget_job_server_jobs()\fP"
.IX Subsection "get_job_server_jobs()"
supported only by Gearman::Server
.PP
\&\fBreturn\fR \f(CW\*(C`{job\-server => {job => {address, listeners, key}}}\*(C'\fR
.SS "\fIget_job_server_clients()\fP"
.IX Subsection "get_job_server_clients()"
supported only by Gearman::Server
.SS "do_task($task)"
.IX Subsection "do_task($task)"
.ie n .SS "do_task($funcname, $arg, \e%options)"
.el .SS "do_task($funcname, \f(CW$arg\fP, \e%options)"
.IX Subsection "do_task($funcname, $arg, %options)"
Dispatches a task and waits on the results. May either provide a
Gearman::Task object, or the 3 arguments that the Gearman::Task
constructor takes.
.PP
\&\fBreturn\fR scalarref of \s-1WORK_COMPLETE\s0 result, or undef on failure.
.ie n .SS "dispatch_background($func, $arg_p, $options_hr)"
.el .SS "dispatch_background($func, \f(CW$arg_p\fP, \f(CW$options_hr\fP)"
.IX Subsection "dispatch_background($func, $arg_p, $options_hr)"
.SS "dispatch_background($task)"
.IX Subsection "dispatch_background($task)"
Dispatches a \f(CW\*(C`task\*(C'\fR and doesn't wait for the result. Return value
is an opaque scalar that can be used to refer to the task with get_status.
.PP
\&\fBIt is strongly recommended to set\fR Gearman::Task \f(CW\*(C`uniq\*(C'\fR \fBoption\fR
to insure gearmand does not squash jobs if it store background jobs in a persistence backend.
See the issue #87
.PP
\&\fBreturn\fR the handle from the jobserver, or undef on failure
.SS "run_hook($name)"
.IX Subsection "run_hook($name)"
run a hook callback if defined
.ie n .SS "add_hook($name, $cb)"
.el .SS "add_hook($name, \f(CW$cb\fP)"
.IX Subsection "add_hook($name, $cb)"
add a hook
.SS "get_status($handle)"
.IX Subsection "get_status($handle)"
The Gearman Server will assign a scalar job handle when you request a
background job with dispatch_background. Save this scalar, and use it later
in order to request the status of this job.
.PP
\&\fBreturn\fR Gearman::JobStatus on success
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2006\-2007 Six Apart, Ltd.
.PP
License granted to use/distribute under the same terms as Perl itself.
.SH "WARRANTY"
.IX Header "WARRANTY"
This is free software. This comes with no warranty whatsoever.
.SH "AUTHORS"
.IX Header "AUTHORS"
.Vb 3
\& Brad Fitzpatrick ()
\& Jonathan Steinert ()
\& Alexei Pastuchov () co\-maintainer
.Ve
.SH "REPOSITORY"
.IX Header "REPOSITORY"