1TheSchwartz::Job(3pm) User Contributed Perl DocumentationTheSchwartz::Job(3pm)
2
3
4

NAME

6       TheSchwartz::Job - jobs for the reliable job queue
7

SYNOPSIS

9           my $client = TheSchwartz->new( databases => $DATABASE_INFO );
10
11           my $job = TheSchwartz::Job->new_from_array('MyWorker', [ foo => 'bar' ]);
12           $client->insert($job);
13
14           $job = TheSchwartz::Job->new(
15               funcname => 'MyWorker',
16               uniqkey  => 7,
17               arg      => [ foo => 'bar' ],
18           );
19           $client->insert($job);
20

DESCRIPTION

22       "TheSchwartz::Job" models the jobs that are posted to the job queue by
23       your application, then grabbed and performed by your worker processes.
24
25       "TheSchwartz::Job" is a "Data::ObjectDriver" model class. See
26       Data::ObjectDriver::BaseObject.
27

FIELDS

29       "TheSchwartz::Job" objects have these possible fields:
30
31   "jobid"
32       The unique numeric identifier for this job. Set automatically when
33       saved.
34
35   "funcid"
36       The numeric identifier for the type of job to perform. "TheSchwartz"
37       clients map function names (also known as abilities and worker class
38       names) to these numbers using "TheSchwartz::FuncMap" records.
39
40   "arg"
41       Arbitrary state data to supply to the worker process for this job. If
42       specified as a reference, the data is frozen to a blob with the
43       "Storable" module.
44
45   "uniqkey"
46       An arbitrary string identifier used to prevent applications from
47       posting duplicate jobs. At most one with the same "uniqkey" value can
48       be posted to a single "TheSchwartz" database.
49
50   "insert_time"
51       The "insert_time" field is not used.
52
53   "run_after"
54       The UNIX system time after which the job can next be attempted by a
55       worker process. This time stamp is set when a job is first created or
56       is released after a failure.
57
58   "grabbed_until"
59       The UNIX system time after which the job can next be available by a
60       worker process. This time stamp is set when a job is grabbed by a
61       worker process, and reset to 0 when is released due to failure to
62       complete the job.
63
64   "priority"
65       An integer value to specify the priority of the job to be executed;
66       larger numbers mean higher priority. See "prioritize" property of
67       TheSchwartz for details.
68
69   "coalesce"
70       A string used to discover jobs that can be efficiently pipe-lined with
71       a given job due to some shared resource. For example, for email
72       delivery jobs, the domain of an email address could be used as the
73       "coalesce" value. A worker process could then deliver all the mail
74       queued for a given mail host after connecting to it once.
75

USAGE

77   "TheSchwartz::Job->new( %args )"
78       Returns a new job object with the given data. Members of %args can be
79       keyed on any of the fields described above, or "funcname".
80
81   "TheSchwartz::Job->new_from_array( $funcname, $arg )"
82       Returns a new job with the given function name (also called ability or
83       worker class), and the scalar or reference $arg for an argument.
84
85   "$job->funcname([ $funcname ])"
86       Returns the function name for the given job, after setting it to
87       $funcname, if specified.
88
89   "$job->handle([ $handle ])"
90       Returns the "TheSchwartz::JobHandle" object describing this job, after
91       setting it to $handle, if specified. A job handle is a convenience
92       class for accessing other records related to jobs; as its convenience
93       methods are also available directly from "TheSchwartz::Job" instances,
94       you will usually not need to work directly with job handles.
95
96   "$job->driver()"
97       Returns the "Data::ObjectDriver" object driver for accessing the
98       database in which $job is stored. See Data::ObjectDriver.
99
100   "$job->add_failure( $msg )"
101       Records and returns a new "TheSchwartz::Error" object representing a
102       failure to perform $job, for reason $msg.
103
104   "$job->exit_status()"
105       Returns the exit status specified by the worker that either completed
106       the job or declared it failed permanently. The exit status for a job
107       will be available for a period of time after the job has exited the
108       queue. That time is defined in the job's worker class's
109       keep_exit_status_for() method.
110
111   "$job->failure_log()"
112       Returns a list of the error messages specified to add_failure() when a
113       worker failed to perform the given job.
114
115   "$job->failures()"
116       Returns the number of times a worker has grabbed this job, only to fail
117       to complete it.
118
119   "$job->set_exit_status( $status )"
120       Records the exit status of the given job as $status.
121
122   "$job->did_something([ $value ])"
123       Returns whether the given job has been completed or failed since it was
124       created or loaded, setting whether it has to $value first, if
125       specified.
126
127   "$job->was_declined()"
128       Sets (if given an argument) and returns the value of the was_declined
129       flag for a job object. See also "$job->declined()"
130
131   "$job->debug( $msg )"
132       Sends the given message to the job's "TheSchwartz" client as debug
133       output.
134
135   "$job->set_as_current()"
136       Set $job as the current job being performed by its associated
137       "TheSchwartz" client.
138

WORKING

140       "TheSchwartz::Worker" classes should use these methods to update the
141       status of their jobs:
142
143   "$job->completed()"
144       Records that the given job has been fully performed and removes it from
145       the job queue. Completing a job records its exit status as 0.
146
147   "$job->failed( $msg, $exit_status )"
148       Records that the worker performing this job failed to complete it, for
149       reason $msg.
150
151       If workers have not failed to complete the job more times than the
152       maximum number of retries for that type of job, the job will be
153       reattempted after its retry delay has elapsed. The maximum number of
154       retries and the delay before a retry are defined in the job's worker
155       class definition as max_retries() and retry_delay() respectively.
156
157       If workers have exceeded the maximum number of reattempts for this job,
158       the job's exit status is recorded as $exit_status, and the job is
159       removed from the queue. If $exit_status is not defined or 0, the job
160       will be recorded with an exit status of 1, to indicate a failure.
161
162   "$job->permanent_failure( $msg, $exit_status )"
163       Records that the worker performing this job failed to complete it, as
164       in failed(), but that the job should not be reattempted, no matter how
165       many times the job has been attempted before. The job's exit status is
166       thus recorded as $exit_status (or 1), and the job is removed from the
167       queue.
168
169   "$job->declined([ $run_after ])"
170       Report that the job has been declined for handling at this time, which
171       means that the job will be retried after the next grabbed_until
172       interval, and does not count against the max_retries count.
173
174       If $run_after is set then the job will be grabbed_until will be reset
175       and the job will be reconsidered at $run_after, and does not count
176       against the max_retries count.
177
178   "$job->replace_with( @jobs )"
179       Atomically replaces the single job $job with the given set of jobs.
180
181       This can be used to decompose one "meta job" posted by your application
182       into a set of jobs workers can perform, or to post a job or jobs
183       required to complete the process already partly performed.
184

SEE ALSO

186       Data::ObjectDriver, Data::ObjectDriver::BaseObject, Storable
187
188
189
190perl v5.38.0                      2023-07-21             TheSchwartz::Job(3pm)
Impressum