1TheSchwartz::Job(3pm) User Contributed Perl DocumentationTheSchwartz::Job(3pm)
2
6 TheSchwartz::Job - jobs for the reliable job queue
7
9 my $client = TheSchwartz->new( databases => $DATABASE_INFO );
10 my $job = TheSchwartz::Job->new_from_array('MyWorker', [ foo => 'bar' ]);
12 $client->insert($job);
13 $job = TheSchwartz::Job->new(
15 funcname => 'MyWorker',
16 uniqkey => 7,
17 arg => [ foo => 'bar' ],
18 );
19 $client->insert($job);
20
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 "TheSchwartz::Job" is a "Data::ObjectDriver" model class. See
26 Data::ObjectDriver::BaseObject.
27
29 "TheSchwartz::Job" objects have these possible fields:
30 "jobid"
32 The unique numeric identifier for this job. Set automatically when
33 saved.
34 "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 "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 "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 "insert_time"
51 The "insert_time" field is not used.
52 "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 "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 "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 "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
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 "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 "$job->funcname([ $funcname ])"
86 Returns the function name for the given job, after setting it to
87 $funcname, if specified.
88 "$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 "$job->driver()"
97 Returns the "Data::ObjectDriver" object driver for accessing the
98 database in which $job is stored. See Data::ObjectDriver.
99 "$job->add_failure( $msg )"
101 Records and returns a new "TheSchwartz::Error" object representing a
102 failure to perform $job, for reason $msg.
103 "$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 "$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 "$job->failures()"
116 Returns the number of times a worker has grabbed this job, only to fail
117 to complete it.
118 "$job->set_exit_status( $status )"
120 Records the exit status of the given job as $status.
121 "$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 "$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 "$job->debug( $msg )"
132 Sends the given message to the job's "TheSchwartz" client as debug
133 output.
134 "$job->set_as_current()"
136 Set $job as the current job being performed by its associated
137 "TheSchwartz" client.
138
140 "TheSchwartz::Worker" classes should use these methods to update the
141 status of their jobs:
142 "$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 "$job->failed( $msg, $exit_status )"
148 Records that the worker performing this job failed to complete it, for
149 reason $msg.
150 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 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 "$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 "$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 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 "$job->replace_with( @jobs )"
179 Atomically replaces the single job $job with the given set of jobs.
180 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
186 Data::ObjectDriver, Data::ObjectDriver::BaseObject, Storable
187perl v5.38.0 2023-07-21 TheSchwartz::Job(3pm)