Module task 

Utilities for creating and managing tasks.

The Task component encapsulates a unit of work to be executed, along with its associated context, metadata, and execution status. The Parts struct contains metadata, attempt tracking, extensions, and scheduling information for each task.

Overview

In apalis, tasks are designed to represent discrete units of work that can be scheduled, retried, and tracked throughout their lifecycle. Each task consists of arguments (args) describing the work to be performed, and an Parts (parts) containing metadata and control information.

Task

The Task struct is generic over:

• Args: The type of arguments or payload for the task.
• Ctx: Ctxdata associated with the task, such as custom fields or backend-specific information.
• IdType: The type used for uniquely identifying the task (defaults to RandomId).

Parts

The Parts struct provides the following:

• task_id: Optionally stores a unique identifier for the task.
• data: An Extensions container for storing arbitrary per-task data (e.g., middleware extensions).
• attempt: Tracks how many times the task has been attempted.
• metadata: Custom metadata for the task, provided by the backend or user.
• status: The current Status of the task (e.g., Pending, Running, Completed, Failed).
• run_at: The UNIX timestamp (in seconds) when the task should be run.

The execution context is essential for tracking the state and metadata of a task as it moves through the system. It enables features such as retries, scheduling, and extensibility via the Extensions type.

Modules

• attempt: Tracks the number of attempts a task has been executed.
• builder: Utilities for constructing tasks.
• data: Data types for task payloads.
• extensions: Extension storage for tasks.
• metadata: Ctxdata types for tasks.
• status: Status tracking for tasks.
• task_id: Types for uniquely identifying tasks.

Examples

Creating a new task with default metadata

let task: Task<String, ()> = TaskBuilder::new("my work".to_string()).build();

Creating a task with custom metadata

#[derive(Default, Clone)]
struct MyCtx { priority: u8 }
let task: Task<String, Extensions> = TaskBuilder::new("important work".to_string())
    .meta(MyCtx { priority: 5 })
    .build();

Accessing and modifying the execution context

use apalis_core::task::{Task, Parts, status::Status};
let mut task = Task::<String, ()>::new("work".to_string());
task.parts.status = Status::Running.into();
task.parts.attempt.increment();

Using Extensions for per-task data

use apalis_core::task::{Task, extensions::Extensions};
#[derive(Debug, Clone, PartialEq)]
pub struct TracingId(String);
let mut extensions = Extensions::default();
extensions.insert(TracingId("abc123".to_owned()));
let task: Task<String, ()> = TaskBuilder::new("work".to_string()).with_data(extensions).build();
assert_eq!(task.parts.data.get::<TracingId>(), Some(&TracingId("abc123".to_owned())));

See Also

• Task: Represents a unit of work to be executed.
• Parts: Holds metadata, status, and control information for a task.
• Extensions: Type-safe storage for per-task data.
• Status: Enum representing the lifecycle state of a task.
• Attempt: Tracks the number of execution attempts for a task.
• TaskId: Unique identifier type for tasks.
• FromRequest: Trait for extracting data from task contexts.
• IntoResponse: Trait for converting tasks into response types.
• TaskBuilder: Fluent builder for constructing tasks with optional configuration.
• RandomId: Default unique identifier type for tasks.

Modules

attempt

A thread-safe tracker for counting the number of attempts made by a task.

builder

Task Builder

data

Utilities for task runtime data extension.

extensions

A type-safe container for storing protocol extensions.

metadata

Task metadata extension trait and implementations

status

The status of a task

task_id

Defines the TaskId type and related functionality.

Structs

Parts

Component parts of a Task

Task

Represents a task which will be executed Should be considered a single unit of work