Struct PersistentJobQueue 

pub struct PersistentJobQueue { /* private fields */ }

Available on crate feature jobs and (crate features model-mysql or model-postgres or model-sqlite) only.

A job queue backed by the model layer (model-sqlite / model-postgres / model-mysql): jobs are written to a rws_jobs table before being acknowledged, so pending and retrying jobs survive a process crash or restart, and several replicas can share one queue.

Unlike JobQueue, a job here can’t be an arbitrary closure — a closure can’t be serialized to disk. Instead the queue stores (job_type, payload) as plain text and dispatches to a handler registered for that job_type at execution time. Register every handler you enqueue before calling start, including after a restart — unprocessed rows from a previous run (and any row left running when the process crashed) are picked up automatically.

Since 18.35.0 (#93) a job can wait until a time, go to a named queue with a priority, be unique (EnqueueOptions); a job that exhausts its retries stays in the table as failed — the dead-letter list (failed_jobs, retry, on_dead); and schedule runs a job on a cron schedule once per due time across every replica.

CREATE TABLE IF NOT EXISTS rws_jobs (
    id          VARCHAR(64) PRIMARY KEY,
    job_type    TEXT    NOT NULL,
    payload     TEXT    NOT NULL DEFAULT '',
    status      TEXT    NOT NULL DEFAULT 'pending', -- pending | running | failed
    attempts    INTEGER NOT NULL DEFAULT 0,
    max_retries INTEGER NOT NULL DEFAULT 3,
    next_run_at BIGINT  NOT NULL,
    created_at  BIGINT  NOT NULL,
    last_error  TEXT,
    queue       VARCHAR(64) NOT NULL DEFAULT 'default',
    priority    BIGINT  NOT NULL DEFAULT 0,
    unique_key  VARCHAR(191)
)

A table from before 18.35.0 gets the last three columns added. Completed jobs are deleted.

Implementations

impl PersistentJobQueue

pub async fn new(pool: DbPool) -> Result<Self, DbError>

Creates the queue and its backing rws_jobs table if absent (adding the 18.35.0 columns to an older one), then resets any row left running (interrupted by a previous crash) back to pending so it gets picked up again.

pub fn max_retries(self, n: u32) -> Self

Override the default retry count applied to jobs enqueued via enqueue (default: 3). Use EnqueueOptions::max_retries for a per-job override.

pub fn poll_interval(self, interval: Duration) -> Self

Override how often idle workers poll for due jobs (default: 500 ms).

pub fn backoff(self, initial: Duration, multiplier: u32) -> Self

Override the backoff policy applied between retries: initial delay before the first retry, doubled (or scaled by multiplier) on each subsequent attempt. Default: 500 ms initial, 2x multiplier.

pub fn queues(self, names: &[&str]) -> Self

Only run jobs from these named queues (default: every queue) — one process for mailers, another for the rest.

pub fn schedule( self, name: &str, cron: &str, job_type: &str, payload: &str, ) -> Result<Self, String>

Enqueue job_type with payload on the cron schedule cron (six fields, seconds first, UTC; see Scheduler). Every replica can declare the same schedule: each due time is claimed by exactly one of them (a compare-and-set on the rws_job_schedules row named name), which enqueues the job.

pub fn schedule_with( self, name: &str, cron: &str, job_type: &str, payload: &str, options: EnqueueOptions, ) -> Result<Self, String>

schedule with options for the enqueued jobs.

pub fn on_dead(&self, hook: impl Fn(&JobInfo) + Send + Sync + 'static)

Call hook with each job that exhausts its retries, as it moves to the dead-letter list (status = 'failed').

pub fn register( &self, job_type: &str, handler: impl Fn(&str) -> Result<(), String> + Send + Sync + 'static, )

Register the function that executes jobs of job_type. Call before start — jobs enqueued for an unregistered job_type fail immediately (and retry, same as any other handler error).

pub async fn enqueue( &self, job_type: &str, payload: &str, ) -> Result<String, DbError>

Persist a new job using the queue’s defaults. Returns the job id.

pub async fn enqueue_with_retries( &self, job_type: &str, payload: &str, max_retries: u32, ) -> Result<String, DbError>

Persist a new job with a per-job retry override.

pub async fn enqueue_with( &self, job_type: &str, payload: &str, options: EnqueueOptions, ) -> Result<String, DbError>

Persist a new job with options (18.35.0). Returns its id — for a unique job already pending or running, that job’s id, and nothing is inserted.

pub async fn tick(&self) -> Result<bool, DbError>

Run one poll-claim-execute cycle. Returns Ok(true) if a job was claimed (whether it succeeded, failed, or is retrying), Ok(false) if none was due. Exposed for tests and for embedding in a caller-owned loop; most applications should use start instead.

pub async fn tick_schedules(&self) -> Result<usize, DbError>

Enqueue the scheduled jobs that are due, each due time once across every process sharing the database. Returns how many this call enqueued. start’s first worker calls it about once a second; exposed for tests and caller-owned loops.

pub async fn jobs( &self, status: Option<&str>, limit: usize, ) -> Result<Vec<JobInfo>, DbError>

Jobs with status (pending, running, failed; None: all), highest priority and earliest due first, at most limit.

pub async fn failed_jobs(&self, limit: usize) -> Result<Vec<JobInfo>, DbError>

The dead-letter list: jobs that exhausted their retries.

pub async fn retry(&self, id: &str) -> Result<bool, DbError>

Put a failed job back in the queue, due now, with its attempts reset. false when there’s no failed job id.

pub async fn delete(&self, id: &str) -> Result<bool, DbError>

Delete a job that isn’t running. false when there’s no such job.

pub fn start(self: Arc<Self>, workers: usize) -> Vec<JoinHandle<()>>

Spawn workers background OS threads, each running its own single-threaded Tokio runtime, polling for due jobs at poll_interval (default: 500 ms) whenever the queue is empty; the first also enqueues scheduled jobs. Returns the thread handles; call stop then join them for a graceful shutdown.

pub fn stop(&self)

Signal all worker threads spawned by start to stop after their current tick. Does not itself join the returned thread handles — join them separately to wait for a clean shutdown.

pub fn pool(&self) -> &DbPool

The database the queue uses.