Crate taskvisor 

taskvisor

Taskvisor is a lightweight task orchestration library for Rust.

It provides primitives to define, supervise, and restart async tasks with configurable policies. The crate is designed as a building block for higher-level orchestrators and agents.

Architecture

Overview

    ┌──────────────┐   ┌──────────────┐   ┌──────────────┐
    │   TaskSpec   │   │   TaskSpec   │   │   TaskSpec   │
    │(user task #1)│   │(user task #2)│   │(user task #3)│
    └──────┬───────┘   └──────┬───────┘   └──────┬───────┘
           ▼                  ▼                  ▼
┌───────────────────────────────────────────────────────────────────┐
│  Supervisor (runtime orchestrator)                                │
│  - Bus (broadcast events)                                         │
│  - AliveTracker (tracks task state with sequence numbers)         │
│  - SubscriberSet (fans out to user subscribers)                   │
│  - Registry (manages active tasks by name)                        │
└──────┬──────────────────┬──────────────────┬───────────────┬──────┘
       ▼                  ▼                  ▼               │
    ┌──────────────┐   ┌──────────────┐   ┌──────────────┐   │
    │  TaskActor   │   │  TaskActor   │   │  TaskActor   │   │
    │ (retry loop) │   │ (retry loop) │   │ (retry loop) │   │
    └┬─────────────┘   └┬─────────────┘   └┬─────────────┘   │
     │                  │                  │                 │
     │ Publishes        │ Publishes        │ Publishes       │
     │ Events:          │ Events:          │ Events:         │
     │ - TaskStarting   │ - TaskStarting   │ - TaskStarting  │
     │ - TaskFailed     │ - TaskStopped    │ - TimeoutHit    │
     │ - BackoffSched.  │ - ActorExhausted │ - ...           │
     │                  │                  │                 │
     ▼                  ▼                  ▼                 ▼
┌───────────────────────────────────────────────────────────────────┐
│                        Bus (broadcast channel)                    │
│              (capacity: SupervisorConfig::bus_capacity)           │
└─────────────────────────────────┬─────────────────────────────────┘
                                  ▼
                      ┌────────────────────────┐
                      │  subscriber_listener   │
                      │   (in Supervisor)      │
                      └───┬────────────────┬───┘
                          ▼                ▼
                   AliveTracker     SubscriberSet
                 (sequence-based)   (per-sub queues)
                                 ┌─────────┼─────────┐
                                 ▼         ▼         ▼
                                 worker1  worker2  workerN
                                 ▼         ▼         ▼
                            sub1.on   sub2.on   subN.on
                             _event()  _event()  _event()

Lifecycle

TaskSpec ──► Supervisor ──► Registry ──► TaskActor::run()

loop {
  ├─► attempt += 1
  ├─► acquire semaphore (optional, cancellable)
  ├─► publish TaskStarting{ task, attempt }
  ├─► run_once(task, timeout, attempt)
  │       │
  │       ├─ Ok  ──► publish TaskStopped
  │       │          ├─ RestartPolicy::Never     ─► ActorExhausted, exit
  │       │          ├─ RestartPolicy::OnFailure ─► ActorExhausted, exit
  │       │          └─ RestartPolicy::Always    ─► reset delay, continue
  │       │
  │       └─ Err ──► publish TaskFailed{ task, error, attempt }
  │                  ├─ RestartPolicy::Never     ─► ActorExhausted, exit
  │                  └─ RestartPolicy::OnFailure/Always:
  │                       ├─ compute delay = backoff.next(backoff_attempt)
  │                       ├─ publish BackoffScheduled{ delay, attempt }
  │                       ├─ sleep(delay) (cancellable)
  │                       └─ continue
  │
  └─ exit conditions:
       - runtime_token cancelled (OS signal or explicit remove)
       - RestartPolicy forbids continuation ─► ActorExhausted
       - Fatal error ─► ActorDead
       - semaphore closed
}

On exit: actor cleanup removes from Registry (if PolicyExhausted/Fatal)

Features

Area	Description	Key types / traits
Subscriber API	Hook into task lifecycle events (logging, metrics, custom subscribers).	Subscribe
Policies	Configure restart/backoff strategies for tasks.	RestartPolicy, BackoffPolicy
Supervision	Manage groups of tasks and their lifecycle.	Supervisor, SupervisorHandle
Completion	Opt in (via *_and_watch) to await a task’s final result.	TaskWaiter, TaskOutcome
Errors	Typed errors for orchestration and task execution.	TaskError, RuntimeError
Tasks	Define tasks as functions or specs, easy to compose and run.	TaskRef, TaskFn, TaskSpec
Configuration	Centralize runtime settings.	SupervisorConfig

Optional features

• logging: exports a simple built-in LogWriter (demo/reference only).
• controller: exposes controller runtime and admission types.

Example

use taskvisor::prelude::*;

#[tokio::main(flavor = "current_thread")]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let sup = Supervisor::new(SupervisorConfig::default(), vec![]);

    // Define a simple task that runs once and exits
    let hello: TaskRef = TaskFn::arc("hello", |ctx: CancellationToken| async move {
        if ctx.is_cancelled() { return Ok(()); }
        println!("Hello from task!");
        Ok(())
    });

    // One-shot task (runs once, never restarts)
    let spec = TaskSpec::once(hello);

    sup.run(vec![spec]).await?;
    Ok(())
}

Modules

prelude

Convenience re-exports for common use.

Structs

BackoffPolicy

Retry backoff policy.

ControllerConfig

Configuration for the controller.

ControllerSpec

Request to submit a task to the controller.

Event

Runtime event with optional metadata.

LogWriter

Event printer for stdout example.

Supervisor

Orchestrates task actors, event delivery, and graceful shutdown.

SupervisorBuilder

Builder for constructing a Supervisor with optional features.

SupervisorConfig

Global configuration for the supervisor runtime.

SupervisorHandle

Handle for managing a running supervisor.

TaskFn

Closure-based Task implementation.

TaskId

Unique runtime identity of a single task run instance.

TaskSpec

Describes how a Task should run under supervision.

TaskWaiter

Awaitable handle resolving to the TaskOutcome of a single task run.

Enums

AdmissionPolicy

Policy controlling how new submissions are handled when a slot is busy.

BackoffSource

Reason for scheduling the next run/backoff.

ControllerError

Errors returned by SupervisorHandle::submit and try_submit.

EventKind

Classification of runtime events.

JitterPolicy

Policy controlling randomization of retry delays.

RestartPolicy

Policy controlling whether a task is restarted after completion or failure.

RuntimeError

Errors produced by the taskvisor runtime.

TaskError

Errors produced by task execution.

TaskOutcome

Final result of a supervised task run.

Traits

Subscribe

Event subscriber for runtime observability.

Task

Async, cancelable unit of work managed by a Supervisor.

Type Aliases

BoxTaskFuture

Boxed, pinned, Send future: the return type of Task::spawn.

TaskRef

Shared handle to a task: Arc<dyn Task>.