Skip to main content

asyncq/
lib.rs

1//! Background job processing for Rust.
2//!
3//! # Quick start
4//!
5//! ```rust,no_run
6//! use asyncq::{Job, Perform, JobContext, JobResult, Queue, Worker};
7//! use asyncq::backends::InMemoryBackend;
8//! use serde::{Serialize, Deserialize};
9//!
10//! // 1. Define your job payload and metadata
11//! #[derive(Job, Serialize, Deserialize)]
12//! #[job(queue = "emails", retries = 3)]
13//! struct WelcomeEmail {
14//!     email: String,
15//! }
16//!
17//! // 2. Implement the work
18//! impl Perform for WelcomeEmail {
19//!     async fn perform(self, _ctx: JobContext) -> JobResult {
20//!         println!("sending welcome email to {}", self.email);
21//!         Ok(())
22//!     }
23//! }
24//!
25//! #[tokio::main]
26//! async fn main() {
27//!     // 3. Create a queue (swap InMemoryBackend for RedisBackend in production)
28//!     let queue = Queue::new(InMemoryBackend::new());
29//!
30//!     // 4. Enqueue from anywhere
31//!     queue.enqueue(WelcomeEmail { email: "user@example.com".into() }).await.unwrap();
32//!
33//!     // 5. Process
34//!     Worker::new(queue)
35//!         .register::<WelcomeEmail>()
36//!         .concurrency(10)
37//!         .run()
38//!         .await;
39//! }
40//! ```
41//!
42//! # Testing without infrastructure
43//!
44//! Use [`backends::InMemoryBackend`] with [`Worker::run_once`] for fast,
45//! infrastructure-free tests:
46//!
47//! ```rust,no_run
48//! use asyncq::{Queue, Worker, backends::InMemoryBackend};
49//!
50//! #[tokio::test]
51//! async fn test_my_job() {
52//!     let backend = InMemoryBackend::new();
53//!     let queue = Queue::new(backend.clone());
54//!
55//!     queue.enqueue(WelcomeEmail { email: "test@test.com".into() }).await.unwrap();
56//!
57//!     Worker::new(queue).register::<WelcomeEmail>().run_once().await.unwrap();
58//!
59//!     assert_eq!(backend.completed_count("emails").await, 1);
60//! }
61//! ```
62//!
63//! # Shared state in jobs
64//!
65//! Pass your app state (database pool, config, etc.) via `Queue::with_state`.
66//! Jobs access it through `ctx.state::<T>()` — the same mental model as axum:
67//!
68//! ```rust,ignore
69//! use std::sync::Arc;
70//!
71//! let queue = Queue::new(backend).with_state(Arc::new(db_pool));
72//!
73//! impl Perform for WelcomeEmail {
74//!     async fn perform(self, ctx: JobContext) -> JobResult {
75//!         let db = ctx.state::<Arc<PgPool>>().expect("db not in state");
76//!         // use db ...
77//!         Ok(())
78//!     }
79//! }
80//! ```
81
82pub mod backend;
83pub mod backends;
84pub mod context;
85pub mod error;
86pub mod job;
87pub mod queue;
88pub mod worker;
89
90#[cfg(feature = "scheduler")]
91pub mod scheduler;
92
93// Flat re-exports — everything a user needs at the top level
94pub use backend::Backend;
95pub use backends::InMemoryBackend;
96pub use context::JobContext;
97pub use error::{Error, JobError, JobResult, Result};
98pub use job::{Job, JobId, JobRecord, JobRecord as RawJobRecord, Perform, QueueStats};
99pub use queue::Queue;
100pub use worker::Worker;
101
102#[cfg(feature = "scheduler")]
103pub use scheduler::Scheduler;
104
105// Re-export the derive macro so users only need `use asyncq::Job`
106pub use asyncq_derive::Job;