Struct identity_common::TaskGroup
source · pub struct TaskGroup { /* private fields */ }Expand description
TaskGroup manages spawning and gracefully terminating asynchronous tasks on a multi-threaded Fuchsia executor, where individual tasks receive cancellation signals and are in control of terminating themselves. This allows the TaskGroup owner to await for completion of the tasks. TaskGroups can also be nested, allowing for independent cancellation of a child TaskGroup, or cancelling parent and child TaskGroups together (through cancelling the parent). Note that a dropped TaskGroup will cancel its own tasks, but not its childrens’ tasks. Hence, it is not recommended to rely on std::ops::drop, but rather to always use cancel() prior to destruction. (This might be changed in the future).
A TaskGroup has three implicit states: (1) active, (2) cancellation in progress and (3)
complete. State (1) is reflected in the success of spawn, and (3) is reflected as the success
of the cancel method. The possible state transitions are (1)->(2) and (2)->(3); note that
once a TaskGroup is cancelled new tasks can never be spawned on it again.
Implementations§
source§impl TaskGroup
impl TaskGroup
sourcepub async fn spawn<F, Fut>(&self, f: F) -> Result<(), TaskGroupError>where
F: FnOnce(TaskGroupCancel) -> Fut + Send + 'static,
Fut: Future<Output = ()> + Send + 'static,
pub async fn spawn<F, Fut>(&self, f: F) -> Result<(), TaskGroupError>where F: FnOnce(TaskGroupCancel) -> Fut + Send + 'static, Fut: Future<Output = ()> + Send + 'static,
Spawn a task on the Fuchsia executor, with a handle to the cancellation future for this TaskGroup. Tasks are themselves responsible for polling the future, and if they do not complete as a response, the TaskGroup will not be able to cancel at all, so well-behaved tasks should poll or select over the cancellation signal whenever it is able to terminate itself gracefully.
If a TaskGroup cancellation is (2) already in progress or (3) completed,
Err(TaskGroupError::AlreadyCancelled) will be returned.
sourcepub fn cancel(&self) -> BoxFuture<'_, Result<(), TaskGroupError>>
pub fn cancel(&self) -> BoxFuture<'_, Result<(), TaskGroupError>>
Cancel ongoing tasks and await for their completion. Note that all tasks that were successfully added will be driven to completion. If more tasks are attempted to be spawn during the lifetime of this method, they will be rejected with an AlreadyCancelled error.
If this TaskGroup has children, they will be cancelled (concurrently, in no particular order) before the tasks of this TaskGroup are cancelled.
If a TaskGroup cancellation is (2) already in progress or (3) completed,
Err(TaskGroupError::AlreadyCancelled) will be returned.
sourcepub fn cancel_no_wait(&self) -> BoxFuture<'_, Result<(), TaskGroupError>>
pub fn cancel_no_wait(&self) -> BoxFuture<'_, Result<(), TaskGroupError>>
Cancel ongoing tasks, but do not wait for their completion. Tasks are allowed to continue running to respond to the cancelation request. If more tasks are attempted to be spawn during the lifetime of this method, they will be rejected with an AlreadyCancelled error.
If this TaskGroup has children, they will be cancelled (concurrently, in no particular order) before the tasks of this TaskGroup are cancelled.
If a TaskGroup cancellation is (2) already in progress or (3) completed,
Err(TaskGroupError::AlreadyCancelled) will be returned.
sourcepub async fn create_child(&self) -> Result<Self, TaskGroupError>
pub async fn create_child(&self) -> Result<Self, TaskGroupError>
Create a child TaskGroup that will be automatically cancelled when the parent is cancelled.