TheSchwartz::Job(3pm)

Okay so, bestie, this is TheSchwartz::Job(3pm) from the User Contributed Perl Documentation, and it’s literally about to make the reliable job queue make sense. 💅✨

🌸 NAME 🌸

TheSchwartz::Job — jobs for the reliable job queue. That’s the whole vibe. 🎀

✨ 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 your application posts to the job queue, and then your worker processes grab them and perform them. Main character job objects, no cap. 💖

It’s a Data::ObjectDriver model class. See Data::ObjectDriver::BaseObject for the supporting cast. 🫶

🎀 FIELDS 🎀

TheSchwartz::Job objects have these possible fields:

🔢 jobid

The unique numeric identifier for this job. It gets set automatically when saved. Slay. ⭐

🗺️ 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. Cute little lookup moment. ✨

🧊 arg

Arbitrary state data to supply to the worker process for this job. If you specify it as a reference, the data is frozen to a blob with the Storable module. Frozen and fabulous. ❄️

✋ 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. One-and-done, bestie. 💅

💀 insert_time

The insert_time field is not used. That’s it. It’s giving decorative. 🙈

⏰ 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. Clock it. 🕰️

⏳ 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. Lowkey a whole scheduling situation. 📅

👑 priority

An integer value to specify the priority of the job to be executed; larger numbers mean higher priority. See the prioritize property of TheSchwartz for details. Higher number = more main character energy. 🔥

📬 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. Efficiency ate. 💌

💜 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. New job, who dis? 🎀

🧚 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. Bestie, it’s array-powered. 🌈

🏷️ $job->funcname([ $funcname ])

Returns the function name for the given job, after setting it to $funcname, if specified. Name tag moment. 💖

🫶 $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. Convenience icon behavior. 👑

🚗 $job->driver()

Returns the Data::ObjectDriver object driver for accessing the database in which $job is stored. See Data::ObjectDriver. Vroom vroom, database. 🏎️

😭 $job->add_failure( $msg )

Records and returns a new TheSchwartz::Error object representing a failure to perform $job, for reason $msg. Not me crying over job errors. 💀

⏳ $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. Keep it for the timeline. 📜

📜 $job->failure_log()

Returns a list of the error messages specified to add_failure() when a worker failed to perform the given job. The receipts, fr fr. 🧾

😵‍💫 $job->failures()

Returns the number of times a worker has grabbed this job, only to fail to complete it. Oof, the struggle. 🫠

✅ $job->set_exit_status( $status )

Records the exit status of the given job as $status. Set it and forget it. 💅

👀 $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. Did it do the thing? This method knows. 🕵️‍♀️

🙅‍♀️ $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(). Declined, but make it iconic. 🚫

🐛 $job->debug( $msg )

Sends the given message to the job’s TheSchwartz client as debug output. Debug princess behavior. 🧚‍♀️

🌟 $job->set_as_current()

Set $job as the current job being performed by its associated TheSchwartz client. Current job, current slay. 👑

🔥 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 done, exit status zero, absolutely ate. 🍓

😬 $job->failed( $msg, $exit_status )

Records that the worker performing this job failed to complete it, for reason $msg. It’s giving not-the-vibe. 😭

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. Retry era. 🔁

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. Warning bestie, this one is serious. ⚠️

🚫 $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. Permanent means permanent, periodt. 💀

🙅‍♀️ $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. Not right now, but maybe later. 🕰️

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

🔄 $job->replace_with( @jobs )

Atomically replaces the single job $job with the given set of jobs. Glow-up via replacement. ✨

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. Big job, meet smaller jobs. 🧩

🌈 SEE ALSO 🌈

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

---

💖 okay that’s the whole page, bestie — go keep those jobs reliable. This one is from perl v5.42.0, dated 2024-12-31. 🎀