Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Enqueuing Jobs

Enqueue a job with Client::enqueue, passing a value of any type that implements JobKind. It returns an EnqueueBuilder that you .await to send the request:

#![allow(unused)]
fn main() {
use serde::{Deserialize, Serialize};
use zizq::{Client, JobKind};
#[derive(Serialize, Deserialize)]
struct SendEmail { to: String }
impl JobKind for SendEmail { const NAME: &'static str = "send_email"; }
async fn run(client: &Client) -> Result<(), zizq::ZizqError> {
let job = client
    .enqueue(SendEmail { to: "alice@example.com".into() })
    .await?;

println!("enqueued {} on queue {}", job.id, job.queue);
Ok(()) }
}

Awaiting the builder returns the created Job — its server-assigned id, resolved queue, priority, and so on.

Per-job overrides

Before awaiting, chain methods to override the type’s defaults for this one call. Anything not overridden falls back to the JobKind constant, then to the server default.

#![allow(unused)]
fn main() {
use serde::{Deserialize, Serialize};
use std::time::Duration;
use zizq::{Client, JobKind};
#[derive(Serialize, Deserialize)]
struct SendEmail { to: String }
impl JobKind for SendEmail { const NAME: &'static str = "send_email"; }
async fn run(client: &Client) -> Result<(), zizq::ZizqError> {
client
    .enqueue(SendEmail { to: "alice@example.com".into() })
    .queue("priority-emails")
    .priority(10)
    .delay(Duration::from_secs(3600))
    .retry_limit(3)
    .await?;
Ok(()) }
}
MethodDescription
queue Override the queue this job is placed on.
priority Override the priority (0–65535, lower runs sooner).
delay Make the job ready after the given Duration from now — it sits in the Scheduled state until then.
ready_at / run_at Schedule the job for an absolute OffsetDateTime. The two names are aliases.
retry_limit Override the retry budget.
backoff Override the BackoffConfig retry-delay curve.
retention Override the RetentionConfig.
unique_key Attach a deduplication key for this enqueue — see Unique Jobs.

Bulk enqueue

To enqueue many jobs in a single request, use Client::enqueue_bulk. It returns a BulkEnqueueBuilder that collects per-job EnqueueBuilders:

#![allow(unused)]
fn main() {
use serde::{Deserialize, Serialize};
use zizq::{Client, JobKind};
#[derive(Serialize, Deserialize)]
struct SendEmail { to: String }
impl JobKind for SendEmail { const NAME: &'static str = "send_email"; }
async fn run(client: &Client) -> Result<(), zizq::ZizqError> {
let jobs = client
    .enqueue_bulk()
    .add(client.enqueue(SendEmail { to: "a@example.com".into() }))
    .add(client.enqueue(SendEmail { to: "b@example.com".into() }).priority(10))
    .await?;

assert_eq!(jobs.len(), 2);
Ok(()) }
}

.add is chainable and consuming. For building a batch in a loop, use the mutating .push instead:

#![allow(unused)]
fn main() {
use serde::{Deserialize, Serialize};
use zizq::{Client, JobKind};
#[derive(Serialize, Deserialize)]
struct SendEmail { to: String }
impl JobKind for SendEmail { const NAME: &'static str = "send_email"; }
async fn run(client: &Client) -> Result<(), zizq::ZizqError> {
let mut batch = client.enqueue_bulk();
for n in 0..1000 {
    batch.push(client.enqueue(SendEmail { to: format!("user{n}@example.com") }));
}
let jobs = batch.await?;
Ok(()) }
}

Different JobKinds can be mixed freely within a single batch. Each batch is enqueued atomically on the server.

Tip

For very large numbers of jobs, send them in chunks (e.g. 1,000 per call) rather than one enormous batch — this bounds memory and keeps the connection responsive.