NAME

       TheSchwartz::Job - jobs for the reliable job queue

SYNOPSIS

           my $client = TheSchwartz->new( databases => $DATABASE_INFO );

           my $job = TheSchwartz::Job->new_from_array('MyWorker', [ foo => 'bar' ]);
           $client->insert($job);

           $job = TheSchwartz::Job->new(
               funcname => 'MyWorker',
               uniqkey  => 7,
               arg      => [ foo => 'bar' ],
           );
           $client->insert($job);

DESCRIPTION

       "TheSchwartz::Job" models the jobs that are posted to the job queue by your application,
       then grabbed and performed by your worker processes.

       "TheSchwartz::Job" is a "Data::ObjectDriver" model class. See
       Data::ObjectDriver::BaseObject.

FIELDS

       "TheSchwartz::Job" objects have these possible fields:

   "jobid"
       The unique numeric identifier for this job. Set automatically when saved.

   "funcid"
       The numeric identifier for the type of job to perform. "TheSchwartz" clients map function
       names (also known as abilities and worker class names) to these numbers using
       "TheSchwartz::FuncMap" records.

   "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 "Storable" module.

   "uniqkey"
       An arbitrary string identifier used to prevent applications from posting duplicate jobs.
       At most one with the same "uniqkey" value can be posted to a single "TheSchwartz"
       database.

   "insert_time"
       The "insert_time" field is not used.

   "run_after"
       The UNIX system time after which the job can next be attempted by a worker process. This
       time stamp is set when a job is first created or is released after a failure.

   "grabbed_until"
       The UNIX system time after which the job can next be available by a worker process. This
       time stamp is set when a job is grabbed by a worker process, and reset to 0 when is
       released due to failure to complete the job.

   "priority"
       An integer value to specify the priority of the job to be executed; larger numbers mean
       higher priority. See "prioritize" property of TheSchwartz for details.

   "coalesce"
       A string used to discover jobs that can be efficiently pipe-lined 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 "coalesce" value. A worker process could then deliver all the mail
       queued for a given mail host after connecting to it once.

USAGE

   "TheSchwartz::Job->new( %args )"
       Returns a new job object with the given data. Members of %args can be keyed on any of the
       fields described above, or "funcname".

   "TheSchwartz::Job->new_from_array( $funcname, $arg )"
       Returns a new job with the given function name (also called ability or worker class), and
       the scalar or reference $arg for an argument.

   "$job->funcname([ $funcname ])"
       Returns the function name for the given job, after setting it to $funcname, if specified.

   "$job->handle([ $handle ])"
       Returns the "TheSchwartz::JobHandle" object describing this job, after setting it to
       $handle, if specified. A job handle is a convenience class for accessing other records
       related to jobs; as its convenience methods are also available directly from
       "TheSchwartz::Job" instances, you will usually not need to work directly with job handles.

   "$job->driver()"
       Returns the "Data::ObjectDriver" object driver for accessing the database in which $job is
       stored. See Data::ObjectDriver.

   "$job->add_failure( $msg )"
       Records and returns a new "TheSchwartz::Error" object representing a failure to perform
       $job, for reason $msg.

   "$job->exit_status()"
       Returns the exit status 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
       "keep_exit_status_for()" method.

   "$job->failure_log()"
       Returns a list of the error messages specified to "add_failure()" when a worker failed to
       perform the given job.

   "$job->failures()"
       Returns the number of times a worker has grabbed this job, only to fail to complete it.

   "$job->set_exit_status( $status )"
       Records the exit status of the given job as $status.

   "$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 $value first, if specified.

   "$job->was_declined()"
       Sets (if given an argument) and returns the value of the was_declined flag for a job
       object. See also "$job->declined()"

   "$job->debug( $msg )"
       Sends the given message to the job's "TheSchwartz" client as debug output.

   "$job->set_as_current()"
       Set $job as the current job being performed by its associated "TheSchwartz" client.

WORKING

       "TheSchwartz::Worker" classes should use these methods to update the status of their jobs:

   "$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 0.

   "$job->failed( $msg, $exit_status )"
       Records that the worker performing this job failed to complete it, for reason $msg.

       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 "max_retries()" and "retry_delay()" respectively.

       If workers have exceeded the maximum number of reattempts for this job, the job's exit
       status is recorded as $exit_status, and the job is removed from the queue. If $exit_status
       is not defined or 0, the job will be recorded with an exit status of 1, to indicate a
       failure.

   "$job->permanent_failure( $msg, $exit_status )"
       Records that the worker performing this job failed to complete it, as in "failed()", but
       that the job should not be reattempted, no matter how many times the job has been
       attempted before. The job's exit status is thus recorded as $exit_status (or 1), and the
       job is removed from the queue.

   "$job->declined([ $run_after ])"
       Report that the job has been declined for handling at this time, which means that the job
       will be retried after the next grabbed_until interval, and does not count against the
       max_retries count.

       If $run_after is set then the job will be grabbed_until will be reset and the job will be
       reconsidered at $run_after, and does not count against the max_retries count.

   "$job->replace_with( @jobs )"
       Atomically replaces the single job $job with the given set of jobs.

       This can be used to decompose one "meta job" 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.

SEE ALSO

       Data::ObjectDriver, Data::ObjectDriver::BaseObject, Storable