.\" 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::Server::Client 3pm"
.TH Gearman::Server::Client 3pm "2016-07-22" "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::Server::Client \- client for gearmand
.SH "NAME"
Used by Gearman::Server to instantiate connections from clients.
Clients speak either a binary protocol, for normal operation (calling
functions, grabbing function call requests, returning function values,
etc), or a text\-based line protocol, for relatively rare
administrative / monitoring commands.
.PP
The binary protocol commands aren't currently documented. (FIXME) But
they're well\-implemented in Gearman::Client, Gearman::Worker,
and Gearman::Client::Async, if that's any consolation.
.PP
The line\-based administrative commands are documented below.
.SH "Binary Protocol Structure"
.IX Header "Binary Protocol Structure"
All binary protocol exchanges between clients (which can be callers,
workers, or both) and the Gearman server have common packet header:
.PP
.Vb 5
\&  4 byte magic  \-\- either "\e0REQ" for requests to the server, or
\&                   "\e0RES" for responses from the server
\&  4 byte type   \-\- network order integer, representing the packet type
\&  4 byte length \-\- network order length, for data segment.
\&  data          \-\- optional, if length is non\-zero
.Ve
.SH "Binary Protocol Commands"
.IX Header "Binary Protocol Commands"
.SS "echo_req (type=16)"
.IX Subsection "echo_req (type=16)"
A debug command.  The server will reply with the same data, in a echo_res (type=17) packet.
.SS "(and many more...)"
.IX Subsection "(and many more...)"
\&\s-1FIXME:\s0 auto-generate protocol docs from internal Gearman::Util table,
once annotated with some English?
.SH "Line based commands"
.IX Header "Line based commands"
These commands are used for administrative or statistic tasks to be done on the gearman server. They can be entered using a line based client (telnet, etc.) by connecting to the listening port (7003) and are also intended to be machine parsable.
.ie n .SS """workers"""
.el .SS "``workers''"
.IX Subsection "workers"
Emits list of registered workers, their fds, IPs, client ids, and list of registered abilities (function names they can do).  Of format:
.PP
.Vb 4
\&  fd ip.x.y.z client_id : func_a func_b func_c
\&  fd ip.x.y.z client_id : func_a func_b func_c
\&  fd ip.x.y.z client_id : func_a func_b func_c
\&  .
.Ve
.PP
It ends with a line with just a period.
.ie n .SS """status"""
.el .SS "``status''"
.IX Subsection "status"
The output format of this function is tab separated columns as follows, followed by a line consisting of a fullstop and a newline (\*(L".\en\*(R") to indicate the end of output.
.IP "Function name" 4
.IX Item "Function name"
A string denoting the name of the function of the job
.IP "Number in queue" 4
.IX Item "Number in queue"
A positive integer indicating the total number of jobs for this function in the queue. This includes currently running ones as well (next column)
.IP "Number of jobs running" 4
.IX Item "Number of jobs running"
A positive integer showing how many jobs of this function are currently running
.IP "Number of capable workers" 4
.IX Item "Number of capable workers"
A positive integer denoting the maximum possible count of workers that could be doing this job. Though they may not all be working on it due to other tasks holding them busy.
.ie n .SS """jobs"""
.el .SS "``jobs''"
.IX Subsection "jobs"
Output format is zero or more lines of:
.PP
.Vb 1
\&    [Job function name]\et[Uniq (coalescing) key]\et[Worker address]\et[Number of listeners]\en
.Ve
.PP
Follows by a single line of:
.PP
.Vb 1
\&    .\en
.Ve
.PP
\&\et is a literal tab character
\&\en is perl's definition of newline (literal \en on linux, something else on win32)
.ie n .SS """clients"""
.el .SS "``clients''"
.IX Subsection "clients"
Output format is zero or more sections of:
.Sp
.RS 4
One line of:
.Sp
.Vb 1
\&    [Client Address]\en
.Ve
.Sp
Followed by zero or more lines of:
.Sp
.Vb 1
\&    \et[Job Function]\et[Uniq (coalescing) key]\et[Worker Address]\en
.Ve
.RE
.PP
Follows by a single line of:
.PP
.Vb 1
\&    .\en
.Ve
.PP
\&\et is a literal tab character
\&\en is perl's definition of newline (literal \en on linux, something else on win32)
.ie n .SS """maxqueue"" function [max_queue_size]"
.el .SS "``maxqueue'' function [max_queue_size]"
.IX Subsection "maxqueue function [max_queue_size]"
For a given function of job, the maximum queue size is adjusted to be max_queue_size jobs long. A negative value indicates unlimited queue size.
.PP
If the max_queue_size value is not supplied then it is unset (and the default maximum queue size will apply to this function).
.PP
This function will return \s-1OK\s0 upon success, and will return \s-1ERR\s0 incomplete_args upon an invalid number of arguments.
.ie n .SS """shutdown"" [""graceful""]"
.el .SS "``shutdown'' [``graceful'']"
.IX Subsection "shutdown [graceful]"
Close the server.  Or \*(L"shutdown graceful\*(R" to close the listening socket, then close the server when traffic has died away.
.ie n .SS """version"""
.el .SS "``version''"
.IX Subsection "version"
Returns server version.