Skip to content

Core Concepts Overview

This section covers the runtime primitives for defining, scheduling, executing, and testing background tasks in litestar-queues.

  • Defining & Enqueuing Tasks

    Register async and sync task functions with @task, discover task modules, and enqueue single or batch workloads through QueueService.

    Defining & Enqueuing Tasks

  • Task Options & Uniqueness

    Configure priority, delayed starts, expiration deadlines, runtime timeouts, sync thread-pool offloading, and terminal or forever deduplication keys.

    Task Options & Uniqueness

  • Task Results & Waiting

    Inspect live task state with TaskResult handles, refresh records from storage, and await terminal completion across push or polling backends.

    Task Results & Waiting

  • Failures, Retries & Cancellation

    Configure exponential RetryBackoff, raise terminal non_retryable() or job_cancelled() exits, and cancel queued or running tasks cooperatively.

    Failures, Retries & Cancellation

  • Recurring Schedules

    Declare fixed-interval and five-field cron schedules directly on @task, synchronize schedule records at startup, and preserve retry budgets across restarts.

    Recurring Schedules

  • Workers & Execution Lifecycle

    Choose between server, asgi, and external worker placements, tune per-queue concurrency and adaptive polling, and configure heartbeats and stale recovery.

    Workers & Execution Lifecycle

  • Task Dependency Injection

    Inject attempt-scoped async context managers via task_dependency_provider or stateless keyword mappings via task_dependency_resolver.

    Task Dependency Injection

  • Post-Response Background Tasks

    Compare in-handler await queue_service.enqueue(...) durability with post-response QueuedBackgroundTask execution.

    Post-Response Background Tasks

  • :material-Sliders:{ .lg .middle } Plugin & Service Configuration

    Wire QueueConfig, WorkerConfig, QueueMaintenanceConfig, QueueEventsConfig, and ObservabilityConfig into QueuePlugin.

    Plugin & Service Configuration

  • Runtime Namespace Customization

    Customize DI state keys, ASGI lifespan names, and OpenTelemetry logger/tracer names with QueueNamespace.

    Runtime Namespace Customization

  • Testing Tasks & Workers

    Test task callables directly, run full enqueue lifecycles inline with execution_backend="immediate", and test single-claim execution with consume_one.

    Testing Tasks & Workers