Trait Task

Source

pub trait Task: Send {
    type Input: Send;
    type Output: Send + Sync;

    // Required method
    fn run(
        self,
        input: Self::Input,
    ) -> impl Future<Output = Self::Output> + Send;
}

Expand description

A unit of async work with typed inputs and outputs.

Use the task macro to implement this trait. The macro automatically derives Input and Output types from your run() method signature.

§Task Patterns

dagx supports three main task patterns:

§1. Stateless Tasks (Pure Functions)

Tasks with no internal state - just transform inputs to outputs:

use dagx::{task, Task};

struct Add;

#[task]
impl Add {
    async fn run(a: &i32, b: &i32) -> i32 {
        a + b
    }
}

§2. Stateful Tasks with Shared State (`&self`)

Tasks that read from internal state but don’t modify it:

use dagx::{task, Task};

struct Multiplier {
    factor: i32,
}

#[task]
impl Multiplier {
    async fn run(&self, input: &i32) -> i32 {
        input * self.factor
    }
}

§3. Stateful Tasks with Mutable State (`&mut self`)

Tasks that modify internal state during execution:

use dagx::{task, Task};

struct Counter {
    count: i32,
}

#[task]
impl Counter {
    async fn run(&mut self, increment: &i32) -> i32 {
        self.count += increment;
        self.count
    }
}

§Input Patterns

(): No dependencies (source task)
&T: Single dependency
&A, &B, &C, ...: Multiple dependencies (up to 8, order matters)

§The Underlying Trait

The #[task] macro generates an implementation of this trait:

§Output Wrapping

Task outputs are automatically wrapped in Arc<T> internally for efficient fan-out. You define Output = T, but the framework wraps it in Arc<T> before sending to channels. This enables O(1) sharing for 1:N dependencies - Arc is cloned (cheap), not your data.

Downstream tasks receive &T after ExtractInput extracts from the Arc. This is transparent to your task code - you work with T, the framework handles Arc wrapping/unwrapping.