Module task 

Async task ownership and bounded shutdown for live components.

This module keeps spawned work attached to its owner until shutdown observes a terminal result. Use TaskGroup for related unit-output tasks and TaskSlot or SharedTaskSlot when one task’s identity or typed result belongs to the owning component. A shutdown timeout retains ownership so the caller can drain the task again instead of detaching it.

Task groups

TaskGroup owns related Future<Output = ()> tasks for one lifecycle generation. TaskGroup::spawn registers each task before its future can poll. Once TaskGroup::begin_shutdown closes admission, concurrent and later spawn attempts return TaskSpawnError.

Generation-bound spawning

TaskSpawner lets an admitted task create children in the same generation. Its cancellation token signals shutdown but does not grant task ownership: child work must still pass through TaskSpawner::spawn. A spawner from a closed generation cannot admit work into a replacement generation.

Group shutdown

TaskGroup::begin_shutdown synchronously closes admission and requests graceful cancellation. TaskGroup::abort closes admission and requests forced cancellation immediately when a synchronous owner cannot offer a graceful completion phase. TaskGroup::finish_shutdown waits for admitted tasks, requests forced cancellation after the graceful deadline, and waits again within the abort deadline. Panics, unexpected cancellation, and tasks that outlive both deadlines remain observable through TaskShutdownError.

A timed-out generation stays closed and retains its tasks for another drain attempt. TaskGroup::start_generation opens a replacement only after the prior generation fully drains. Dropping a group requests forced cancellation but cannot await task termination, so owners that need a proven shutdown must call TaskGroup::finish_shutdown.

Partial setup rollback

TaskGroupGuard closes its task groups and runs a synchronous rollback callback if setup exits while the guard remains armed. Disarm it after setup succeeds. The owner still performs the asynchronous bounded drain after a rollback.

Singular tasks

TaskSlot owns one task and preserves its output type. SharedTaskSlot provides the same ownership for clients that share the task across clones and serializes concurrent drain attempts. finish_task and SharedTaskSlot::finish wait gracefully, abort within a second bound, and retain an unfinished task if the finish future is canceled or the abort deadline expires.

Outcomes and errors

TaskJoinOutcome distinguishes normal completion, owner-requested abort, join failure, and an incomplete task that remains owned. TaskSpawnError reports failed admission or start, TaskGenerationError prevents a replacement generation from opening too early, and TaskShutdownError reports group shutdown state, failures, and remaining tasks.

Structs

SharedTaskSlot

Owns one typed task shared by cloned clients.

TaskGenerationError

Indicates that the prior task group generation has not fully drained.

TaskGroup

Owns a related group of cancellation-aware live tasks, one generation at a time.

TaskGroupGuard

Closes task groups and runs synchronous rollback when dropped while armed.

TaskSlot

Owns one typed task and its forced-abort state across bounded drain attempts.

TaskSpawnError

A task admission failure.

TaskSpawner

A generation-bound capability for cancellation-aware child tasks.

Enums

TaskJoinOutcome

The observed result of bounded shutdown for one explicitly singular task.

TaskShutdownError

A bounded task shutdown failure.

Functions

finish_task

Gracefully joins one task, then aborts and joins it within a second bound.