Taskvisor overview

Taskvisor runs and manages Tokio tasks inside a Rust service. It gives tasks a name, retry rules, cancellation, and a final result. An optional controller can queue, replace, or reject work for the same application key.

Taskvisor manages the task lifecycle inside one process. Your application still owns the work itself, external side effects, stored data, deployment, and security.

crates.io · API reference · Source code

What Taskvisor manages

Need	Taskvisor contract
Supervised lifecycle	One-shot, retrying, or periodic tasks with backoff, jitter, retry limits, and attempt timeouts.
Runtime control	Add work and optionally request its final result; inspect, cancel, or remove registrations later.
Direct final outcomes	One process-local TaskOutcome through TaskWaiter, outside the best-effort event path.
Per-key admission	Queue, replace, or reject competing submissions through an optional controller slot.
Typed observability	Lifecycle events for logs, traces, metrics, and live diagnostics.
Explicit resource use	Configurable bounds for attempts, registrations, command queues, subscriber queues, and retained values.

Choose a workflow

Application need	Taskvisor path	Start here
A fixed batch or resident workers known at startup	run, run_until, or run_with_os_signals	Run Taskvisor and graceful_worker.rs
Work discovered while the service is running	serve, then configure and execute add operations through SupervisorHandle	Manage tasks at runtime and dynamic_tasks.rs
Competing work that must coordinate by application key	serve, then configure and execute controller submit operations	Coordinate work by key and tenant_sync.rs

These paths describe how work enters the runtime. TaskSpec::once, restartable, and periodic separately describe what happens after each attempt. Use a watched add or submission whenever application logic needs the final outcome.

Check the fit

Taskvisor can help when a service needs to:

• add, remove, or watch tasks while the service is running;
• set retry limits, timeouts, backoff, or shared cancellation;
• wait for the final result of one task;
• queue, replace, or reject competing work for the same key.

Taskvisor may be more than an application needs for one retrying future or a small fixed set of workers with simple cancellation. It is not a persistent job queue or an external scheduler.

Know the main boundaries

• Tasks, queued submissions, task IDs, events, and watched outcomes do not survive process exit.
• Cancellation is cooperative. Timeouts and force-abort do not roll back external side effects.
• TaskWaiter is the direct result path. Events and subscriber queues are bounded and best-effort.
• Periodic work uses a delay after completion, not cron or missed-run recovery.
• Controller slots and resource budgets belong to one supervisor. They do not coordinate another process or bound operating-system resources.

Read Production boundaries before deploying a service.

Start using Taskvisor

• Complete the Quick start for one retrying watched task.
• Read the Mental model to separate entry paths, task behavior, identities, and result paths.
• Follow the source map to see which module owns each part of the runtime.
• Browse the Taskvisor examples for complete static, dynamic, observability, and keyed-admission programs.
• Use the API documentation for exact signatures, variants, and edge-case contracts.

All guide pages

• Start: Quick start, Mental model, Install Taskvisor.
• Use Taskvisor: Define a task, Choose task behavior, Run Taskvisor, Manage tasks at runtime, Final outcomes and lifecycle events, Cancellation and shutdown, Coordinate work by key.
• Operate: Configure Taskvisor, Production boundaries, Common mistakes.
• Reference: Taskvisor examples, API reference.