jobs

A parsed cron expression. Each list holds the allowed values of one field in ascending order: seconds 0-59 (only 0 for a 5-field expression), minutes 0-59, hours 0-23, days of the month 1-31, months 1-12 and days of the week 0-6 (0 is Sunday; 7 is read as 0). any_day and any_weekday record whether those fields started with *, which decides how the two day fields combine (see cron_matches).

Parses a cron expression: five fields (minute, hour, day of month, month, day of week), six with a seconds field first, or a macro (@yearly, @annually, @monthly, @weekly, @daily, @midnight, @hourly). Fields take *, numbers, a-b ranges, /step on any of them (*/15, 1-30/5, and 5/15 for 5-59/15), comma lists, month names JAN-DEC and day names SUN-SAT (any case); 0 and 7 are both Sunday. Errors name the field and the offending text.

Whether the instant t (to the second, in UTC) is a fire time of c. When both day fields are restricted (neither starts with *), a day matches if either matches, as in Vixie cron: 0 0 1 * MON fires on the 1st and on every Monday. Otherwise both must match.

Whether t is a fire time of c on the wall clock of the zone z.

The first fire time of c strictly after t, in UTC, or none when there is none within nine years (such as 0 0 30 2 *).

The last fire time of c at or before t, in UTC.

The next n fire times of c after t, in UTC (fewer if the expression runs out).

The first fire time of c strictly after t on the wall clock of z, as an instant. Skipped and repeated wall times follow the rules of daylight saving time described in the README.

The last fire time of c at or before t on the wall clock of z, as an instant.

The next n fire times of c after t on the wall clock of z.

Where a job is in its life. Pending jobs wait for their run_at (a retry is a pending job with attempts already made), Running jobs are leased to a worker, and the other three are final: Completed, Dead (out of attempts or discarded: the dead letter set) and Cancelled.

A job to enqueue. Build one with job and change fields with with. Smaller priority runs first. run_at (when set) or delay (from the enqueue time) says when it becomes available. With a unique_key, enqueueing again in the same queue while a job with that key is pending or running, or within unique_for of the first one, returns the existing job instead.

One failed attempt, as recorded in Job.errors.

A stored job.

The result of an enqueue: a new job, or the existing job with the same unique key.

A claimed job. token identifies this claim: finishing calls with an older token (after the lease expired and another worker claimed the job) change nothing and return false.

What a handler decided about a job. Retry waits by the worker's backoff and RetryIn by the given time; both count the attempt, and a job out of attempts goes to Dead. Discard sends it to Dead at once. Snooze runs it again later without counting the attempt.

How long to wait before the next attempt, by the number of attempts made (1 after the first). Exponential doubles base up to cap and then takes off up to jitter (0 to 1) of it at random but repeatably, seeded by the job id; Linear waits step times the attempt, up to cap; Steps takes the list in order and repeats its last element.

What a worker needs: the queue it serves, how long a claim lasts before another worker may take the job over, and the backoff for Retry.

What work did: nothing was available, or it ran a job, with whether the outcome was recorded (false when the lease had been lost).

Filters for list: by queue, state and kind (none means any), job ids above after_id (for keyset paging), at most limit jobs in id order.

Counts per queue. available are pending and due, scheduled pending and due later; oldest_due is the earliest run_at of the available ones, a measure of how far behind the workers are.

Creates or upgrades the tables this package uses (jobs_jobs, jobs_schedules and the version table jobs_schema), each step in a transaction, and returns how many steps it applied. It is separate from db.migrate, so an application's own migrations are not affected. Safe to call on every start, from several processes.

A job for queue of kind kind with payload (usually JSON from json.encode): priority 0, available at once, 20 attempts, not unique.

Adds a job at time now, or finds the pending, running or recent job with its unique key.

Adds every job in one transaction: all of them or, if one fails, none. The results are in order.

enqueue at the current time.

The id of an enqueue result, new or existing.

The job with id id.

Any queue, state and kind, from the start, 100 at a time.

Jobs that pass f, in id order. For the next page, set after_id to the last id returned.

Counts for every queue that has jobs, in queue order, at time now.

Returns jobs whose lease expired at now to their queues (or to dead when they were on their last attempt) and gives how many. claim does this for its own queue, so call it only to see crashed work sooner, for example from a periodic task.

Claims up to n available jobs of queue for lease from now, highest priority (smallest number) first, then earliest run_at, then oldest. Each claim counts an attempt. The claim is one BEGIN IMMEDIATE transaction, so concurrent workers in any number of threads or processes never get the same job; expired leases of the queue are rescued first.

Claims the next available job of queue, as claim_many with n = 1.

Extends a lease to by after now (a heartbeat for long jobs). None when the lease was lost.

Marks a leased job completed. False when the lease was lost (the job was rescued and claimed again, or cancelled).

Records a failed attempt: the job runs again after backoff, or goes to dead when it has used its attempts. False when the lease was lost.

Records a failed attempt that should run again after after (or go to dead when it has used its attempts).

Sends a leased job to dead at once, whatever attempts it has left.

Puts a leased job back to run after after without counting this attempt.

Records a handler's outcome for a leased job, using backoff for Retry.

Cancels a pending or running job. A worker that still holds it can no longer record a result.

Makes a dead or cancelled job pending again, with its attempts reset and available at now.

retry for every dead job of queue; gives how many.

Moves a pending job to run at at (sooner or later). False for jobs in other states.

Deletes a job in any state.

Deletes jobs in the final state s (Completed, Dead or Cancelled) that finished before before, and gives how many. Pending and running jobs are never purged.

Exponential backoff from 1 second up to 1 hour, with a quarter of jitter.

The wait before the attempt after attempt attempts, for a job seeded by seed (its id): the same inputs always give the same wait, so retries are spread out but repeatable in tests.

A worker for queue with a 5 minute lease and the default backoff.

Claims one job of the worker's queue at now, runs handler on it and records the outcome at now. Handlers report failure through their Outcome; a handler that traps or never returns leaves the job leased, and it is retried when the lease expires.

work_at with the clock: claims now and records the outcome when the handler returns.

Runs work until the queue has nothing available or max jobs ran, and gives how many ran. For concurrency, start several in par and pass a top-level function (or a lambda written inside the task), since tasks can't share function values: for i in par(0..4) then jobs.drain(c, w, send_email, 1000).

Serves the worker's queue until stop holds a non-zero value: runs jobs while there are any and sleeps idle_ms when there are none. Gives how many jobs ran. Set stop from another task, or from a signal-handling path of the program, to finish after the current job.

What tick does about fire times that passed while nothing ticked (the process was down): CatchUp enqueues each of them, at most the limit most recent; Latest enqueues only the most recent; Skip enqueues the most recent only if it is at most grace old, and drops the rest.

A recurring job: cron (see parse_cron) on the wall clock of the IANA zone zone ("UTC", "Europe/Berlin", or a fixed offset such as "+05:30"), enqueueing kind with payload into queue. name identifies it.

One run that tick enqueued: the schedule, its fire time and the enqueue result.

A schedule named name in UTC, enabled, with priority 0, 20 attempts and Latest for missed runs.

Adds or replaces the schedule s.name, checking its cron expression and zone. Its first run is the first fire time after now; replacing a schedule with the same expression and zone keeps its progress, so nothing fires twice. An error names what is wrong.

Removes a schedule. Jobs it already enqueued stay.

Turns a schedule on or off. Turning one on counts from now, so the time it was off is not caught up.

Every schedule, by name.

The fire times of c in z after last and at or before now that missed lets through, oldest first. tick enqueues these.

Enqueues every run of every enabled schedule that is due at now, once: each run gets the unique key schedule:NAME:MILLIS and the schedule's progress moves to now in the same transaction, so ticking from several processes, or twice, enqueues nothing twice. Call it every few seconds or every minute; missed runs follow each schedule's missed.