taskq 0.1.0

A thread-safe in-memory task queue with async consumption and optional idempotency keys
Documentation

taskq

A small, thread-safe, in-memory task queue for synchronous producers and async or synchronous consumers.

Features

  • thread-safe submission and consumption
  • async task consumption without blocking runtime workers
  • synchronous non-blocking task polling
  • queue-local, internally generated i64 task IDs
  • optional idempotency with generic task keys
  • task lifecycle status and timestamps
  • bounded capacity with explicit QueueFull signaling
  • generic payload types
  • finished task cleanup after a configurable TTL
  • running task timeout detection
  • single-process, multi-threaded operation
  • metrics and tracing
  • task priorities
  • task cancellation
  • persistent or distributed backends

Installation

cargo add taskq

Usage

use taskq::{SimpleTaskQueue, TaskError};

async fn run() -> Result<(), TaskError> {
    let queue = SimpleTaskQueue::<&str>::new();

    // Without a key, every submission creates a new task.
    let task_id = queue.submit_task("payload")?;

    // Supplying a key enables deduplication for that task.
    queue.submit_task_with_key("request-123", "keyed payload")?;

    // Wait asynchronously without blocking the runtime worker.
    let task = queue.pop_task().await?;
    assert_eq!(task.id(), task_id);
    assert_eq!(task.payload(), &"payload");
    queue.mark_task_success(task.id())?;

    // Task keys can use any supported hashable type.
    let numeric_key_queue = SimpleTaskQueue::<&str, u64>::new();
    numeric_key_queue.submit_task_with_key(123_u64, "payload")?;

    Ok(())
}

Use try_pop_task when a synchronous consumer must poll without waiting. Received tasks can be consumed with into_payload or into_parts when the consumer needs ownership of the payload.

Queue semantics

  • The queue is bounded. submit_task and submit_task_with_key never wait for capacity; they return TaskError::QueueFull so callers can retry, back off, or reject work according to their own policy.
  • Task IDs are unique only within one queue instance. They are not durable or globally unique identifiers.
  • A task key remains reserved until its terminal status is removed after the configured finished-task TTL.
  • pop_task waits asynchronously, while try_pop_task returns immediately.
  • Tasks and statuses live only in memory and are lost when the process exits.
  • Every queue instance owns one background maintenance thread for status cleanup and running-task timeout detection.

Benchmark

cargo run --release --bin benchmark -- \
  --producers 4 --consumers 4 --tasks 100000 \
  --payload-bytes 128 --capacity 1024

The benchmark retries submissions that receive QueueFull, so producer-heavy configurations measure bounded-queue contention instead of terminating early.

License

Licensed under either of the Apache License, Version 2.0 or the MIT license, at your option.