Module queue 

The Postgres job queue, from axa_postgres_job_queue, with BackgroundWorker jobs.

The engine is axa-postgres-job-queue: the axa_queue table, claims with FOR UPDATE SKIP LOCKED, retries, stale recovery, retention, the pool of job loops, delayed jobs, priorities, job status, and recurring schedules. Its crate documentation says how each behaves. This module puts the BackgroundWorker trait over it, so a job type is registered by its type and queued by BackgroundWorker::perform_later, and its errors are crate::Error.

Running it

Nothing runs jobs by itself. A service needs a process calling Queue::run, usually through start --all or start --worker, and warn_if_unserved says so at boot when it has none. Several processes may run at once.

Structs

Act

One act of a person on a job, as axa_job_acts keeps it. It outlives the job’s row, which retention deletes.

Counts

How many jobs are in each state, for metrics.

DateTime

ISO 8601 combined date and time with time zone.

JobInfo

What the queue knows of one job. Its arguments are left out.

NewJob

A job to queue: its type, its arguments, and when and how it runs.

Queue

A Postgres-backed job queue whose jobs are BackgroundWorkers.

QueueOptions

Queue tuning.

Schedule

A job queued every interval. See Schedules.

ScheduleInfo

What the table holds of one schedule.

Utc

The UTC time zone. This is the most efficient time zone when you don’t need the local time. It is also used as an offset (which is also a dummy type).

Enums

ActKind

What a person did to a job.

JobState

Where a job is.

Constants

MAX_REASON_CHARS

The longest by or reason kept on an act, in characters.

SETUP_STATEMENTS

The statements that make the queue’s tables, in order, each safe to repeat. A service whose role may not change the schema runs these in a migration, and calls Queue::connect_existing. They need Postgres 14 or later.

Functions

cancel

Cancel the job id if it is still queued, as an act of by, for reason, kept in the caller’s transaction with the service’s own audit row. Answers whether it was cancelled. A job in any other state, or no such job, writes no act. See axa_postgres_job_queue::cancel.

enqueue_all_on

Add every job in jobs on connection, returning their ids in order. On a transaction they commit or roll back together.

enqueue_job_on

Add job on executor, usually the caller’s transaction, and return its id. Build job with job to delay it or give it a priority.

enqueue_on

Add a job for worker W on executor, usually the caller’s transaction, and return its id. The job then commits or rolls back with the transaction.

job

A job for worker W with args, with W’s name and limit on tries, to delay, prioritise, or queue in a batch.

retry

Queue the job id again for one more try, if it failed or waits for review, as an act of by, for reason, kept in the caller’s transaction with the service’s own audit row. Answers whether it was queued again. A job in any other state, or no such job, writes no act. See axa_postgres_job_queue::retry.

warn_if_unserved

Warn when a service queues jobs and nothing here will run them, returning whether it warned.