.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" 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" ''
'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.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" 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::Job 3pm"
.TH TheSchwartz::Job 3pm "2007-12-20" "perl v5.10.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::Job \- jobs for the reliable job queue
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&    my $client = TheSchwartz\->new( databases => $DATABASE_INFO );
\&
\&    my $job = TheSchwartz::Job\->new_from_array(\*(AqMyWorker\*(Aq, foo => \*(Aqbar\*(Aq);
\&    $client\->dispatch_async($job);
\&
\&    $job = TheSchwartz::Job\->new(
\&        funcname => \*(AqMyWorker\*(Aq,
\&        uniqkey  => 7,
\&        arg      => [ foo => \*(Aqbar\*(Aq ],
\&    );
\&    $client\->dispatch_async($job);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\f(CW\*(C`TheSchwartz::Job\*(C'\fR models the jobs that are posted to the job queue by your
application, then grabbed and performed by your worker processes.
.PP
\&\f(CW\*(C`TheSchwartz::Job\*(C'\fR is a \f(CW\*(C`Data::ObjectDriver\*(C'\fR model class. See
Data::ObjectDriver::BaseObject.
.SH "FIELDS"
.IX Header "FIELDS"
\&\f(CW\*(C`TheSchwartz::Job\*(C'\fR objects have these possible fields:
.ie n .SS """jobid"""
.el .SS "\f(CWjobid\fP"
.IX Subsection "jobid"
The unique numeric identifier for this job. Set automatically when saved.
.ie n .SS """funcid"""
.el .SS "\f(CWfuncid\fP"
.IX Subsection "funcid"
The numeric identifier for the type of job to perform. \f(CW\*(C`TheSchwartz\*(C'\fR clients
map function names (also known as abilities and worker class names) to these
numbers using \f(CW\*(C`TheSchwartz::FuncMap\*(C'\fR records.
.ie n .SS """arg"""
.el .SS "\f(CWarg\fP"
.IX Subsection "arg"
Arbitrary state data to supply to the worker process for this job. If specified
as a reference, the data is frozen to a blob with the \f(CW\*(C`Storable\*(C'\fR module.
.ie n .SS """uniqkey"""
.el .SS "\f(CWuniqkey\fP"
.IX Subsection "uniqkey"
An arbitrary string identifier used to prevent applications from posting
duplicate jobs. At most one with the same \f(CW\*(C`uniqkey\*(C'\fR value can be posted to a
single \f(CW\*(C`TheSchwartz\*(C'\fR database.
.ie n .SS """insert_time"""
.el .SS "\f(CWinsert_time\fP"
.IX Subsection "insert_time"
The \f(CW\*(C`insert_time\*(C'\fR field is not used.
.ie n .SS """run_after"""
.el .SS "\f(CWrun_after\fP"
.IX Subsection "run_after"
The \s-1UNIX\s0 system time after which the job can next be attempted by a worker
process. This timestamp is set when a job is first created or is released after
a failure.
.ie n .SS """grabbed_until"""
.el .SS "\f(CWgrabbed_until\fP"
.IX Subsection "grabbed_until"
The \s-1UNIX\s0 system time after which the job can next be available by a worker
process. This timestamp is set when a job is grabbed by a worker process, and
reset to \f(CW0\fR when is released due to failure to complete the job.
.ie n .SS """priority"""
.el .SS "\f(CWpriority\fP"
.IX Subsection "priority"
The \f(CW\*(C`priority\*(C'\fR field is not used.
.ie n .SS """coalesce"""
.el .SS "\f(CWcoalesce\fP"
.IX Subsection "coalesce"
A string used to discover jobs that can be efficiently pipelined with a given
job due to some shared resource. For example, for email delivery jobs, the
domain of an email address could be used as the \f(CW\*(C`coalesce\*(C'\fR value. A worker
process could then deliver all the mail queued for a given mail host after
connecting to it once.
.SH "USAGE"
.IX Header "USAGE"
.ie n .SS """TheSchwartz::Job\->new( %args )"""
.el .SS "\f(CWTheSchwartz::Job\->new( %args )\fP"
.IX Subsection "TheSchwartz::Job->new( %args )"
Returns a new job object with the given data. Members of \f(CW%args\fR can be keyed
on any of the fields described above, or \f(CW\*(C`funcname\*(C'\fR.
.ie n .SS """TheSchwartz::Job\->new_from_array( $funcname, $arg )"""
.el .SS "\f(CWTheSchwartz::Job\->new_from_array( $funcname, $arg )\fP"
.IX Subsection "TheSchwartz::Job->new_from_array( $funcname, $arg )"
Returns a new job with the given function name (also called \fIability\fR or
\&\fIworker class\fR), and the scalar or reference \f(CW$arg\fR for an argument.
.ie n .SS """$job\->funcname([ $funcname ])"""
.el .SS "\f(CW$job\->funcname([ $funcname ])\fP"
.IX Subsection "$job->funcname([ $funcname ])"
Returns the function name for the given job, after setting it to \f(CW$funcname\fR,
if specified.
.ie n .SS """$job\->handle([ $handle ])"""
.el .SS "\f(CW$job\->handle([ $handle ])\fP"
.IX Subsection "$job->handle([ $handle ])"
Returns the \f(CW\*(C`TheSchwartz::JobHandle\*(C'\fR object describing this job, after setting
it to \f(CW$handle\fR, if specified. A \fIjob handle\fR is a convenience class for
accessing other records related to jobs; as its convenience methods are also
available directly from \f(CW\*(C`TheSchwartz::Job\*(C'\fR instances, you will usually not
need to work directly with job handles.
.ie n .SS """$job\->driver()"""
.el .SS "\f(CW$job\->driver()\fP"
.IX Subsection "$job->driver()"
Returns the \f(CW\*(C`Data::ObjectDriver\*(C'\fR object driver for accessing the database in
which \f(CW$job\fR is stored. See Data::ObjectDriver.
.ie n .SS """$job\->add_failure( $msg )"""
.el .SS "\f(CW$job\->add_failure( $msg )\fP"
.IX Subsection "$job->add_failure( $msg )"
Records and returns a new \f(CW\*(C`TheSchwartz::Error\*(C'\fR object representing a failure
to perform \f(CW$job\fR, for reason \f(CW$msg\fR.
.ie n .SS """$job\->exit_status()"""
.el .SS "\f(CW$job\->exit_status()\fP"
.IX Subsection "$job->exit_status()"
Returns the \fIexit status\fR specified by the worker that either completed the
job or declared it failed permanently. The exit status for a job will be
available for a period of time after the job has exited the queue. That time is
defined in the job's worker class's \f(CW\*(C`keep_exit_status_for()\*(C'\fR method.
.ie n .SS """$job\->failure_log()"""
.el .SS "\f(CW$job\->failure_log()\fP"
.IX Subsection "$job->failure_log()"
Returns a list of the error messages specified to \f(CW\*(C`add_failure()\*(C'\fR when a
worker failed to perform the given job.
.ie n .SS """$job\->failures()"""
.el .SS "\f(CW$job\->failures()\fP"
.IX Subsection "$job->failures()"
Returns the number of times a worker has grabbed this job, only to fail to
complete it.
.ie n .SS """$job\->set_exit_status( $status )"""
.el .SS "\f(CW$job\->set_exit_status( $status )\fP"
.IX Subsection "$job->set_exit_status( $status )"
Records the exit status of the given job as \f(CW$status\fR.
.ie n .SS """$job\->did_something([ $value ])"""
.el .SS "\f(CW$job\->did_something([ $value ])\fP"
.IX Subsection "$job->did_something([ $value ])"
Returns whether the given job has been completed or failed since it was created
or loaded, setting whether it has to \f(CW$value\fR first, if specified.
.ie n .SS """$job\->debug( $msg )"""
.el .SS "\f(CW$job\->debug( $msg )\fP"
.IX Subsection "$job->debug( $msg )"
Sends the given message to the job's \f(CW\*(C`TheSchwartz\*(C'\fR client as debug output.
.ie n .SS """$job\->set_as_current()"""
.el .SS "\f(CW$job\->set_as_current()\fP"
.IX Subsection "$job->set_as_current()"
Set \f(CW$job\fR as the current job being performed by its associated \f(CW\*(C`TheSchwartz\*(C'\fR
client.
.SH "WORKING"
.IX Header "WORKING"
\&\f(CW\*(C`TheSchwartz::Worker\*(C'\fR classes should use these methods to update the status of
their jobs:
.ie n .SS """$job\->completed()"""
.el .SS "\f(CW$job\->completed()\fP"
.IX Subsection "$job->completed()"
Records that the given job has been fully performed and removes it from the job
queue. Completing a job records its exit status as \f(CW0\fR.
.ie n .SS """$job\->failed( $msg, $exit_status )"""
.el .SS "\f(CW$job\->failed( $msg, $exit_status )\fP"
.IX Subsection "$job->failed( $msg, $exit_status )"
Records that the worker performing this job failed to complete it, for reason
\&\f(CW$msg\fR.
.PP
If workers have not failed to complete the job more times than the maximum
number of retries for that type of job, the job will be reattempted after its
retry delay has elapsed. The maximum number of retries and the delay before a
retry are defined in the job's worker class definition as \f(CW\*(C`max_retries()\*(C'\fR and
\&\f(CW\*(C`retry_delay()\*(C'\fR respectively.
.PP
If workers \fIhave\fR exceeded the maximum number of reattempts for this job, the
job's exit status is recorded as \f(CW$exit_status\fR, and the job is removed from
the queue. If \f(CW$exit_status\fR is not defined or \f(CW0\fR, the job will be recorded
with an exit status of \f(CW1\fR, to indicate a failure.
.ie n .SS """$job\->permanent_failure( $msg, $exit_status )"""
.el .SS "\f(CW$job\->permanent_failure( $msg, $exit_status )\fP"
.IX Subsection "$job->permanent_failure( $msg, $exit_status )"
Records that the worker performing this job failed to complete it, as in
\&\f(CW\*(C`failed()\*(C'\fR, but that the job should \fInot\fR be reattempted, no matter how many
times the job has been attempted before. The job's exit status is thus recorded
as \f(CW$exit_status\fR (or \f(CW1\fR), and the job is removed from the queue.
.ie n .SS """$job\->replace_with( @jobs )"""
.el .SS "\f(CW$job\->replace_with( @jobs )\fP"
.IX Subsection "$job->replace_with( @jobs )"
Atomically replaces the single job \f(CW$job\fR with the given set of jobs.
.PP
This can be used to decompose one \*(L"metajob\*(R" posted by your application into a
set of jobs workers can perform, or to post a job or jobs required to complete
the process already partly performed.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Data::ObjectDriver, Data::ObjectDriver::BaseObject, Storable