Skip to main content

Crate asyncq

Crate asyncq 

Source
Expand description

Background job processing for Rust.

§Quick start

use asyncq::{Job, Perform, JobContext, JobResult, Queue, Worker};
use asyncq::backends::InMemoryBackend;
use serde::{Serialize, Deserialize};

// 1. Define your job payload and metadata
#[derive(Job, Serialize, Deserialize)]
#[job(queue = "emails", retries = 3)]
struct WelcomeEmail {
    email: String,
}

// 2. Implement the work
impl Perform for WelcomeEmail {
    async fn perform(self, _ctx: JobContext) -> JobResult {
        println!("sending welcome email to {}", self.email);
        Ok(())
    }
}

#[tokio::main]
async fn main() {
    // 3. Create a queue (swap InMemoryBackend for RedisBackend in production)
    let queue = Queue::new(InMemoryBackend::new());

    // 4. Enqueue from anywhere
    queue.enqueue(WelcomeEmail { email: "user@example.com".into() }).await.unwrap();

    // 5. Process
    Worker::new(queue)
        .register::<WelcomeEmail>()
        .concurrency(10)
        .run()
        .await;
}

§Testing without infrastructure

Use backends::InMemoryBackend with Worker::run_once for fast, infrastructure-free tests:

use asyncq::{Queue, Worker, backends::InMemoryBackend};

#[tokio::test]
async fn test_my_job() {
    let backend = InMemoryBackend::new();
    let queue = Queue::new(backend.clone());

    queue.enqueue(WelcomeEmail { email: "test@test.com".into() }).await.unwrap();

    Worker::new(queue).register::<WelcomeEmail>().run_once().await.unwrap();

    assert_eq!(backend.completed_count("emails").await, 1);
}

§Shared state in jobs

Pass your app state (database pool, config, etc.) via Queue::with_state. Jobs access it through ctx.state::<T>() — the same mental model as axum:

ⓘ
use std::sync::Arc;

let queue = Queue::new(backend).with_state(Arc::new(db_pool));

impl Perform for WelcomeEmail {
    async fn perform(self, ctx: JobContext) -> JobResult {
        let db = ctx.state::<Arc<PgPool>>().expect("db not in state");
        // use db ...
        Ok(())
    }
}

Re-exports§

pub use backend::Backend;
pub use backends::InMemoryBackend;
pub use context::JobContext;
pub use error::Error;
pub use error::JobError;
pub use error::JobResult;
pub use error::Result;
pub use job::Job;
pub use job::JobId;
pub use job::JobRecord;
pub use job::JobRecord as RawJobRecord;
pub use job::Perform;
pub use job::QueueStats;
pub use queue::Queue;
pub use worker::Worker;
pub use scheduler::Scheduler;

Modules§

backend
backends
context
error
job
queue
scheduler
Cron-based job scheduling.
worker

Derive Macros§

Job
Derive the Job trait for a struct, registering it as a background job type.