.\" 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"