Struct Queue 

pub struct Queue { /* private fields */ }

An in-memory background job queue.

Create via Queue::builder() or Queue::new(). Register handlers with register(), then push jobs with push() or push_delayed().

The queue must be started with start() to spawn background worker tasks that process jobs.

Implementations

impl Queue

pub fn new() -> Queue

Create a queue with default settings (4 workers, no retries).

pub fn builder() -> QueueBuilder

Create a builder for customizing the queue.

pub fn register<F, Fut>(&self, name: impl Into<String>, handler: F)

where F: Fn(Job) -> Fut + Send + Sync + 'static, Fut: Future<Output = Result<(), QueueError>> + Send + 'static,

Register a named job handler.

The handler receives a Job and returns Result<(), QueueError>.

Examples

queue.register("process_order", |job: Job| async move {
    let order_id: u64 = job.deserialize()?;
    // process the order ...
    Ok(())
});

pub async fn push( &self, name: impl Into<String>, payload: &(impl Serialize + ?Sized), ) -> Result<u64, QueueError>

Push a job for immediate execution.

The payload is serialized to JSON. Returns the job ID.

pub async fn push_delayed( &self, name: impl Into<String>, payload: &(impl Serialize + ?Sized), delay: Duration, ) -> Result<u64, QueueError>

Push a job for delayed execution.

The job will not be picked up by a worker until delay has elapsed.

pub async fn push_dedup( &self, name: impl Into<String>, payload: &(impl Serialize + ?Sized), dedup_key: impl Into<String>, ) -> Result<u64, QueueError>

Push with a dedup key — the job is queued at most once concurrently.

If a job with the same dedup_key is currently in pending, this is a no-op and the existing id is returned. Useful for idempotent triggers (e.g. flush a cache only once per minute regardless of how many requests arrived). The dedup window ends when the job is picked up.

pub fn start(&self)

Available on crate feature compio only.

Start background worker tasks (compio runtime).

pub async fn shutdown(&self, timeout: Duration)

Gracefully shut down the queue.

Stops accepting new jobs and waits for in-flight jobs to complete (up to the given timeout).

pub fn dead_letters(&self) -> Vec<DeadJob>

Returns a snapshot of jobs in the dead letter queue.

Allocates a new Vec<DeadJob> and deep-clones every entry. For monitoring code that just iterates entries read-only, prefer Self::dead_letters_arc (atomic refcount per entry, no payload copies) or Self::dead_letter_count (no allocation at all).

pub fn dead_letters_arc(&self) -> Vec<Arc<DeadJob>>

Returns a cheap snapshot of the dead letter queue.

Each entry is shared via Arc rather than deep-cloned, so this is suitable for emitting from metrics endpoints or hot paths. Returned Arc<DeadJob> handles remain valid even if Self::clear_dead_letters is called concurrently.

pub fn dead_letter_count(&self) -> usize

Returns the number of jobs currently in the dead letter queue.

pub fn clear_dead_letters(&self)

Clear all dead letters.

pub fn pending_count(&self) -> usize

Returns the number of pending jobs.

pub fn inflight_count(&self) -> u64

Returns the number of currently in-flight jobs.

Trait Implementations

impl Clone for Queue

fn clone(&self) -> Queue

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Queue

fn default() -> Queue

Returns the “default value” for a type.