.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" 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
..
.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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "TheSchwartz::Worker 3pm"
.TH TheSchwartz::Worker 3pm "2022-06-28" "perl v5.34.0" "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"
TheSchwartz::Worker \- superclass for defining task behavior
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    package MyWorker;
\&    use base qw( TheSchwartz::Worker );
\&
\&    sub work {
\&        my $class = shift;
\&        my TheSchwartz::Job $job = shift;
\&
\&        print "Workin\*(Aq hard or hardly workin\*(Aq? Hyuk!!\en";
\&
\&        $job\->completed();
\&    }
\&
\&
\&    package main;
\&    
\&    my $client = TheSchwartz\->new( databases => $DATABASE_INFO );
\&    $client\->can_do(\*(AqMyWorker\*(Aq);
\&    $client\->work();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fITheSchwartz::Worker\fR objects are the salt of the reliable job queuing earth.
The behavior required to perform posted jobs are defined in sub-classes of
\&\fITheSchwartz::Worker\fR. These sub-classes are named for the ability required of
a \f(CW\*(C`TheSchwartz\*(C'\fR client to do the job, so that the clients can dispatch
automatically to the appropriate worker routine.
.PP
Because jobs can be performed by any machine running code for capable worker
classes, \f(CW\*(C`TheSchwartz::Worker\*(C'\fRs are generally stateless. All mutable state is
stored in the \f(CW\*(C`TheSchwartz::Job\*(C'\fR objects. This means all
\&\f(CW\*(C`TheSchwartz::Worker\*(C'\fR methods are \fIclass\fR methods, and \f(CW\*(C`TheSchwartz::Worker\*(C'\fR
classes are generally never instantiated.
.SH "SUBCLASSING"
.IX Header "SUBCLASSING"
Define and customize how a job is performed by overriding these methods in your
subclass:
.ie n .SS """$class\->work( $job )"""
.el .SS "\f(CW$class\->work( $job )\fP"
.IX Subsection "$class->work( $job )"
Performs the job that required ability \f(CW$class\fR. Override this method to
define how to do the job you're defining.
.PP
Note that will need to call \f(CW\*(C`$job\->completed()\*(C'\fR or \f(CW\*(C`$job\->failed()\*(C'\fR
as appropriate to indicate success or failure. See TheSchwartz::Job.
.ie n .SS """$class\->max_retries( $job )"""
.el .SS "\f(CW$class\->max_retries( $job )\fP"
.IX Subsection "$class->max_retries( $job )"
Returns the number of times workers should attempt the given job. After this
many tries, the job is marked as completed with errors (that is, a
\&\f(CW\*(C`TheSchwartz::ExitStatus\*(C'\fR is recorded for it) and removed from the queue. By
default, returns 0.
.ie n .SS """$class\->retry_delay( $num_failures )"""
.el .SS "\f(CW$class\->retry_delay( $num_failures )\fP"
.IX Subsection "$class->retry_delay( $num_failures )"
Returns the number of seconds after a failure workers should wait until
reattempting a job that has already failed \f(CW$num_failures\fR times. By default,
returns 0.
.ie n .SS """$class\->keep_exit_status_for()"""
.el .SS "\f(CW$class\->keep_exit_status_for()\fP"
.IX Subsection "$class->keep_exit_status_for()"
Returns the number of seconds to allow a \f(CW\*(C`TheSchwartz::ExitStatus\*(C'\fR record for
a job performed by this worker class to exist. By default, returns 0.
.ie n .SS """$class\->grab_for()"""
.el .SS "\f(CW$class\->grab_for()\fP"
.IX Subsection "$class->grab_for()"
Returns the number of seconds workers of this class will claim a grabbed a job.
That is, returns the length of the \fItimeout\fR after which other workers will
decide a worker that claimed a job has crashed or faulted without marking the
job failed. Jobs that are marked as failed by a worker are also marked for
immediate retry after a delay indicated by \f(CW\*(C`retry_delay()\*(C'\fR.
.SH "USAGE"
.IX Header "USAGE"
.ie n .SS """$class\->grab_job( $client )"""
.el .SS "\f(CW$class\->grab_job( $client )\fP"
.IX Subsection "$class->grab_job( $client )"
Finds and claims a job for workers with ability \f(CW$class\fR, using \f(CW\*(C`TheSchwartz\*(C'\fR
client \f(CW$client\fR. This job can then be passed to \f(CW\*(C`work()\*(C'\fR or \f(CW\*(C`work_safely()\*(C'\fR
to perform it.
.ie n .SS """$class\->work_safely( $job )"""
.el .SS "\f(CW$class\->work_safely( $job )\fP"
.IX Subsection "$class->work_safely( $job )"
Performs the job associated with the worker's class name. If an error is thrown
while doing the job, the job is appropriately marked as failed, unlike when
calling \f(CW\*(C`work()\*(C'\fR directly.