Struct TaskGroup 

pub struct TaskGroup { /* private fields */ }

Represents a task-group owner.

Cloning a task group keeps the same owner and cancellation token. Use Self::try_child when work needs an independently cancellable owner whose lifetime remains bounded by this parent.

Dropping a handle does not request cancellation or wait for cleanup. Active descendants retain their ancestor ownership path. Call Self::shutdown_until to close admission, cancel and await the subtree. A task panic poisons its group against new submissions; it remains owned and can still be shut down and reported.

Implementations

impl TaskGroup

pub fn diagnostics_task_details( &self, scan_budget: usize, output_budget: usize, ) -> RuntimeTaskDetails

Samples sanitized task details without computing subtree aggregates.

At most scan_budget tasks and scan_budget descendant registrations are examined; at most output_budget details are returned. Enumeration and temporary group storage obey the same budget, including empty or expired groups. Concurrent changes are not a globally atomic snapshot.

impl TaskGroup

pub fn id(&self) -> TaskGroupId

Returns the id.

pub fn parent_id(&self) -> Option<TaskGroupId>

Returns the parent id.

pub fn name(&self) -> &str

Returns the name.

pub fn cancellation_token(&self) -> CancellationToken

Returns the cancellation token.

pub fn shutdown_deadline(&self) -> Option<ShutdownDeadline>

Returns the earliest absolute deadline installed by a shutdown owner.

pub fn lifecycle_state(&self) -> TaskGroupLifecycleState

Returns the lifecycle state.

pub fn task_count(&self) -> usize

Returns the active count registered directly in this group.

Descendants are excluded; subtree diagnostics aggregate them separately.

pub fn component_count(&self) -> usize

Returns the number of active component groups directly owned by this group.

pub fn owns_task(&self, task_id: TaskId) -> bool

Returns whether task_id was issued by this group, whether or not the task is still registered.

pub fn contains_task(&self, task_id: TaskId) -> bool

Returns whether task_id is a registered task of this group.

Returns false for an id issued by another group.

pub fn event_counts(&self) -> TaskGroupEventCounts

Returns the counts of absorbed failures over this group’s whole tree.

pub fn try_child(&self, name: impl Into<Arc<str>>) -> RuntimeResult<Self>

Creates an independently cancellable child owned by this task group.

Parent cancellation propagates to the returned child. Cancelling the child does not cancel this parent or any sibling child. In contrast, Clone::clone keeps the same owner and cancellation token.

Errors

Returns a crate::RuntimeErrorKind::Closed failure after this owner starts shutting down, or crate::RuntimeErrorKind::Poisoned after a task panic poisoned it.

pub fn spawn<F>( &self, name: impl Into<TaskName>, kind: TaskKind, future: F, ) -> RuntimeResult<TaskId>

where F: Future<Output = ()> + Send + 'static,

Spawns the supplied task.

pub fn spawn_critical<F>( &self, name: impl Into<TaskName>, kind: TaskKind, failures: CriticalFailureState, future: F, ) -> RuntimeResult<TaskId>

where F: Future<Output = ()> + Send + 'static,

Spawns a task whose panic is recorded as a critical failure.

Registration is explicit and opt-in: a task spawned the ordinary way keeps today’s behavior. A normal completion is not a failure here, because a worker or job may legitimately return; use Self::spawn_critical_service when returning before owner cancellation must be treated as one.

Errors

Returns an error when this task group is shutting down or closed.

pub fn spawn_critical_service<F>( &self, name: impl Into<TaskName>, failures: CriticalFailureState, future: F, ) -> RuntimeResult<TaskId>

where F: Future<Output = ()> + Send + 'static,

Spawns a critical service that must run until its owner is cancelled.

Both a panic and a return before owner cancellation are recorded as critical failures. Owner cancellation is an expected exit and records nothing, so an ordinary shutdown never triggers failure handling.

Errors

Returns an error when this task group is shutting down or closed.

pub fn spawn_service<F>( &self, name: impl Into<TaskName>, future: F, ) -> RuntimeResult<TaskId>

where F: Future<Output = ()> + Send + 'static,

Spawns a service that owns its shutdown protocol.

The service remains tracked during owner shutdown, but its future must observe an appropriate cancellation signal and perform any required ordered cleanup itself. Use Self::spawn_cancellable_service when it is safe to drop the service future as soon as its owner is cancelled.

pub fn spawn_cancellable_service<F>( &self, name: impl Into<TaskName>, future: F, ) -> RuntimeResult<TaskId>

where F: Future<Output = ()> + Send + 'static,

Spawns a service that exits when either its future completes or its owner is cancelled.

Owner cancellation drops future; services that require an ordered cleanup sequence must use Self::spawn_service and observe a cancellation token explicitly.

Errors

Returns an error when this task group is shutting down or closed.

pub fn spawn_operation<F>( &self, context: &OperationContext, name: impl Into<TaskName>, future: F, ) -> RuntimeResult<TaskId>

where F: Future<Output = ()> + Send + 'static,

Spawns work for a bounded operation under this fixed component owner.

The operation context supplies task classification, cancellation, and an optional deadline without creating a child task group.

pub fn spawn_draining_operation<F>( &self, context: &OperationContext, name: impl Into<TaskName>, future: F, ) -> RuntimeResult<TaskId>

where F: Future<Output = ()> + Send + 'static,

Spawns accepted operation work that must drain during owner shutdown.

Unlike Self::spawn_operation, owner cancellation does not drop the supplied future. The operation context still enforces its own cancellation and deadline, and OperationContext::wait aborts work that outlives the caller’s drain deadline. This is intended for work that has already been accepted and whose ordered shutdown protocol is owned by a tracked service.

pub fn spawn_with_handle<F>( &self, name: impl Into<TaskName>, kind: TaskKind, future: F, ) -> RuntimeResult<(TaskId, JoinHandle<()>)>

where F: Future<Output = ()> + Send + 'static,

Spawns with handle.

pub fn spawn_service_with_handle<F>( &self, name: impl Into<TaskName>, future: F, ) -> RuntimeResult<(TaskId, JoinHandle<()>)>

where F: Future<Output = ()> + Send + 'static,

Spawns service with handle.

pub fn cancel(&self)

Signals cancellation to this group and its descendants without waiting.

The signal does not close submission admission or confirm task destruction. Services must observe it and perform their own cleanup. Use Self::shutdown_until for the complete shutdown boundary.

pub fn abort_task(&self, task_id: TaskId) -> bool

Requests cancellation of an active task without waiting for destruction.

Returns whether the task was still registered. Its record and resources remain owned until the executor destroys the future. An id issued by another group is never registered here, so it returns false.

pub async fn abort_task_and_wait( &self, task_id: TaskId, timeout: Duration, ) -> bool

Requests cancellation and waits until the user future is destroyed.

Returns false if the task was already absent, was issued by another group, or the wait expired. A timeout does not remove the task’s record or confirm cancellation.

pub async fn wait_task(&self, task_id: TaskId, timeout: Duration) -> bool

Asynchronously waits for a local task’s future to be destroyed.

Returns true when this group’s task is already absent, including after earlier completion, and false when a registered task outlives the timeout. Unlike Self::abort_task_and_wait, absence is treated as success. An id issued by another group returns false immediately: this group cannot tell whether that task finished; see Self::owns_task. This does not request cancellation or prove business-level success.

pub fn shutdown(&self, timeout: Duration) -> BoxFuture<'_, ShutdownReport>

Closes and asynchronously drains this subtree within a relative budget.

The budget is converted once to an absolute deadline. See Self::shutdown_until for repeated calls and completion semantics.

pub fn shutdown_until( &self, deadline: ShutdownDeadline, ) -> BoxFuture<'_, ShutdownReport>

Closes admission, signals cancellation and asynchronously awaits owned work.

All children share the absolute deadline. A later call can tighten but cannot extend it. Tasks that do not finish in time are asked to abort; the report distinguishes confirmed destruction from remaining work. Once published, the report is retained and returned by subsequent calls.

pub fn shutdown_now(&self) -> ShutdownReport

Requests immediate shutdown without waiting for future destruction.

The retained report may contain unconfirmed remaining work even when cancellation completes shortly afterward. A later graceful call returns that same report; it does not turn this call into an awaited drain.

Trait Implementations

impl Clone for TaskGroup

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for TaskGroup

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.