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.

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.

CREATE TABLE IF NOT EXISTS rws_jobs (
    id          TEXT    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 INTEGER NOT NULL,
    created_at  INTEGER NOT NULL,
    last_error  TEXT
)

Completed jobs are deleted; a job that exhausts its retries is left with status = 'failed' for inspection instead of being deleted.

Implementations

impl PersistentJobQueue

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

Creates the queue and its backing rws_jobs table if absent, 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 enqueue_with_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 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 default retry count. Returns the generated 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 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 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. 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.