.\" 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::Task 3pm"
.TH Gearman::Task 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::Task \- a task in Gearman, from the point of view of a client
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&    my $task = Gearman::Task\->new("add", "1+2", {
\&            ...
\&    });
\&
\&    $taskset\->add_task($task);
\&    $client\->do_task($task);
\&    $client\->dispatch_background($task);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fIGearman::Task\fR is a Gearman::Client's representation of a task to be
done.
.SH "USAGE"
.IX Header "USAGE"
.ie n .SS "Gearman::Task\->new($func, $arg, \e%options)"
.el .SS "Gearman::Task\->new($func, \f(CW$arg\fP, \e%options)"
.IX Subsection "Gearman::Task->new($func, $arg, %options)"
Creates a new \fIGearman::Task\fR object, and returns the object.
.PP
\&\fI\f(CI$func\fI\fR is the function name to be run.  (that you have a worker registered to process)
.PP
\&\fI\f(CI$arg\fI\fR is an opaque scalar or scalarref representing the argument(s)
to pass to the distributed function.  If you want to pass multiple
arguments, you must encode them somehow into this one.  That's up to
you and your worker.
.PP
\&\fI\f(CI%options\fI\fR can contain:
.IP "\(bu" 4
uniq
.Sp
A key which indicates to the server that other tasks with the same
function name and key will be merged into one.  That is, the task
will be run just once, but all the listeners waiting on that job
will get the response multiplexed back to them.
.Sp
Uniq may also contain the magic value \*(L"\-\*(R" (a single hyphen) which
means the uniq key is the contents of the args.
.IP "\(bu" 4
on_complete
.Sp
A subroutine reference to be invoked when the task is completed. The
subroutine will be passed a reference to the return value from the worker
process.
.IP "\(bu" 4
on_fail
.Sp
A subroutine reference to be invoked when the task fails (or fails for
the last time, if retries were specified). The reason could be passed
to this callback as an argument. This callback won't be called after a
failure if more retries are still possible.
.IP "\(bu" 4
on_retry
.Sp
A subroutine reference to be invoked when the task fails, but is about
to be retried.
.Sp
Is passed one argument, what retry attempt number this is.  (starts with 1)
.IP "\(bu" 4
on_status
.Sp
A subroutine reference to be invoked if the task emits status updates.
Arguments passed to the subref are ($numerator, \f(CW$denominator\fR), where those
are left up to the client and job to determine.
.IP "\(bu" 4
on_warning
.Sp
A subroutine reference to be invoked if the task emits status updates.
Arguments passed to the subref are ($numerator, \f(CW$denominator\fR), where those
are left up to the client and job to determine.
.IP "\(bu" 4
retry_count
.Sp
Number of times job will be retried if there are failures.  Defaults to 0.
.IP "\(bu" 4
high_priority
.Sp
\&\fBthe option high_priority is deprecated\fR. Use \f(CW\*(C`priority => high\*(C'\fR instead.
Boolean, whether this job should take priority over other jobs already
enqueued.
.IP "\(bu" 4
priority
.Sp
valid value:
.RS 4
.IP "\(bu" 4
high
.IP "\(bu" 4
normal (defaul)
.IP "\(bu" 4
low
.RE
.RS 4
.RE
.IP "\(bu" 4
timeout
.Sp
Automatically fail, calling your on_fail callback, after this many
seconds have elapsed without an on_fail or on_complete being
called. Defaults to 0, which means never.  Bypasses any retry_count
remaining.
.IP "\(bu" 4
try_timeout
.Sp
Automatically fail, calling your on_retry callback (or on_fail if out of
retries), after this many seconds have elapsed. Defaults to 0, which means
never.