Crate taskvisor 

taskvisor

Taskvisor is a task supervisor for Tokio: it restarts background tasks on failure and reports every step through typed events.

It helps you run named async tasks with:

• restart policies,
• retry backoff,
• per-attempt timeout,
• cooperative cancellation,
• lifecycle events,
• optional final outcomes through *_and_watch APIs.

The crate is meant to be a building block for services, agents, workers, and higher-level orchestration SDKs.

Core Model

TaskFn / impl Task
       |
       v
    TaskSpec
       |
       v
  Supervisor ---- publishes ----> Event bus ----> Subscribe
       |
       v
   TaskActor
  (attempt loop)

A Task is the user unit of work. A TaskSpec configures how that task runs. A Supervisor owns the runtime and manages task lifecycle. A Subscribe implementation can observe lifecycle events.

Task Lifecycle

add task
  -> TaskStarting
  -> task attempt runs
  -> TaskStopped / TaskFailed / TimeoutHit / TaskCanceled
  -> restart, backoff, or finish
  -> TaskRemoved

Events are best-effort observability. If you need a guaranteed final result for one task, use SupervisorHandle::add_and_watch or, with the controller feature, submit_and_watch.

Main Types

Area	Types
Tasks	Task, TaskFn, TaskContext, TaskSpec
Runtime	Supervisor, SupervisorHandle, SupervisorConfig
Outcomes	TaskWaiter, TaskOutcome
Policies	RestartPolicy, BackoffPolicy, JitterPolicy
Events	Event, EventKind, Subscribe
Errors	Error, TaskError, RuntimeError

All main types are re-exported at the crate root. For the concept behind each area, read the module pages: tasks, policies, events, subscribers, core, identity, and controller (feature-gated).

Optional Features

• tokio-util-interop: exposes raw tokio_util::sync::CancellationToken interop through TaskContext and the prelude.
• controller: slot-based admission control with ControllerSpec, AdmissionPolicy, and ControllerConfig.
• tracing: built-in TracingBridge subscriber that forwards runtime events to the tracing ecosystem.
• logging: built-in LogWriter subscriber for examples and simple logs (dev, preview only).
• test-util: test helpers (TaskContext::detached(), TaskId::for_tests(), TaskOutcome::*_for_tests).

Quick Start

use taskvisor::prelude::*;

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

    let hello: TaskRef = TaskFn::arc("hello", |_ctx| async move {
        println!("Hello from task!");
        Ok(())
    });

    sup.run(vec![TaskSpec::once(hello)]).await?;
    Ok(())
}

Examples

All examples run as-is, from simple to advanced (browse them on GitHub):

Example	What it shows
basic	Run one task and exit — the minimal wiring
worker	A long-running worker that stops cleanly on Ctrl+C
periodic	Run a job every N seconds, forever
multiple	Several tasks with different restart rules under one supervisor
queue_consumer	A message consumer that reconnects after failures
cpu_job	Run CPU-heavy work on rayon, supervised, without blocking Tokio
subscriber	React to lifecycle events with your own handler
tracing	Send supervisor events into your logs (feature tracing)
metrics	Count lifecycle events as Prometheus metrics
dynamic	Add, cancel, and remove tasks while the app is running
outcomes	Wait for a task’s final result: done, failed, or canceled
slots	Limit concurrency per slot: queue, replace, or drop the newcomer
admission	Find out if your submission ran or was rejected

Re-exports

pub use identity::TaskId;

pub use core::Supervisor;

pub use core::SupervisorBuilder;

pub use core::SupervisorConfig;

pub use core::SupervisorHandle;

pub use core::TaskOutcome;

pub use core::TaskWaiter;

pub use tasks::BoxTaskFuture;

pub use tasks::Task;

pub use tasks::TaskContext;

pub use tasks::TaskFn;

pub use tasks::TaskRef;

pub use tasks::TaskSpec;

pub use policies::BackoffError;

pub use policies::BackoffPolicy;

pub use policies::JitterPolicy;

pub use policies::RestartPolicy;

pub use error::BoxError;

pub use error::Error;

pub use error::RuntimeError;

pub use error::SharedError;

pub use error::TaskError;

pub use events::BackoffSource;

pub use events::Event;

pub use events::EventKind;

pub use subscribers::Subscribe;

pub use controller::AdmissionPolicy;controller

pub use controller::ControllerConfig;controller

pub use controller::ControllerError;controller

pub use controller::ControllerSnapshot;controller

pub use controller::ControllerSpec;controller

pub use controller::SlotStatusKind;controller

pub use controller::SlotView;controller

pub use subscribers::LogWriter;logging

pub use subscribers::TracingBridge;tracing

Modules

controllercontroller

Controller

core

Runtime core.

error

Error types for runtime orchestration and task execution.

events

Runtime events.

identity

Runtime task identity.

policies

Retry and restart policies.

prelude

Common re-exports.

reasons

Stable reason strings.

subscribers

Subscriber.

tasks

Task abstractions.