Common mistakes

Do not treat run success as task success

An Ok(()) result from Supervisor::run means the supervisor lifecycle and cleanup workflow completed. It does not report each task's final outcome. When application logic needs that outcome, use serve, add(spec).watch().execute(), TaskWaiter::wait, and then shutdown. See Run Taskvisor and Final outcomes and lifecycle events.

Do not treat submit success as admission

submit(request).execute().await? means that the controller accepted the command. It does not confirm slot admission or runtime registration. The controller may process the command before or after the call returns. Use submit(request).watch().execute() and await its TaskWaiter when the application must distinguish rejection from an admitted task outcome. See Coordinate work by key.

Do not drive application logic from events

The event bus and subscriber queues are bounded and best-effort. Use TaskWaiter for the direct in-process final-outcome path. Reserve events for logs, metrics, tracing, and live diagnostics. See Final outcomes and lifecycle events.

Make resident work observe cancellation

Await TaskContext::cancelled, check is_cancelled between work units, or wrap a drop-safe future with run_until_cancelled. Return TaskError::Canceled after cooperative cleanup. See Cancellation and shutdown.

Do not use a controller slot as task identity

A slot coordinates admission. It is not a registered task name or a cancellation key. Use the returned TaskId for queued work. The same ID continues to identify the task after registry admission, and registered work can also be addressed by name. Taskvisor has no slot-wide cancel operation. See Coordinate work by key.

Move blocking and CPU-heavy work off Tokio

Use a separate blocking executor, worker pool, or external runtime. Keep attempt-future destructors short. The CPU example uses Rayon and shows that cancellation drops the receiver but does not stop computation already running. See Define a task and cpu_job.rs.

Do not retry an ambiguous side effect blindly

A retry creates a fresh attempt. It can repeat an external side effect whose previous result was ambiguous, and Taskvisor does not roll that effect back. Classify the failure as retryable only when repeating the operation is acceptable. See Choose task behavior.

Treat timeouts as stop requests, not rollback

An attempt timeout cancels the context and drops the attempt future. ForceAborted can become final before physical execution exits. Neither action undoes external side effects. Check cancellation safety and use an explicit commit or acknowledgement protocol when dropping an operation is unsafe. See Cancellation and shutdown and Production boundaries.

Do not treat an ownership timeout as a task deadline

Ownership-specific timeout methods bound only the wait for cleanup ownership before command intake. They do not bound later command queues, controller admission, registry admission, task execution, or final outcome delivery. See Manage tasks at runtime and Coordinate work by key.

Continue learning

Resource	Next step
Examples guide	Choose a complete runnable scenario.
API documentation	Read exact contracts for public types and methods.
crates.io	Find published versions and package details.
Benchmark guide	Run and interpret the Criterion suites.
Contributor map	Follow runtime ownership and source boundaries.