Struct Scope

pub struct Scope { /* private fields */ }

A scope for managing async tasks. This scope is aborted when dropped.

Scopes are how fuchsia-async implements structured concurrency. Every task is spawned on a scope, and runs until either the task completes or the scope is cancelled or aborted. In addition to owning tasks, scopes may own child scopes, forming a nested structure.

Scopes are usually joined or cancelled when the owning code is done with them. This makes it easier to reason about when a background task might still be running. Note that in multithreaded contexts it is safer to cancel and await a scope explicitly than to drop it, because the destructor is not synchronized with other threads that might be running a task.

Task::spawn and related APIs spawn on the root scope of the executor. New code is encouraged to spawn directly on scopes instead, passing their handles as a way of documenting when a function might spawn tasks that run in the background and reasoning about their side effects.

Scope lifecycle

When a scope is created it is open, meaning it accepts new tasks. Scopes are closed when one of the following happens:

1. When close() is called.
2. When the scope is aborted or dropped, the scope is closed immediately.
3. When the scope is cancelled, the scope is closed when all active guards are dropped.
4. When the scope is joined and all tasks complete, the scope is closed before the join future resolves.

When a scope is closed it no longer accepts tasks. Tasks spawned on the scope are dropped immediately, and their Task or JoinHandle futures never resolve. This applies transitively to all child scopes. Closed scopes cannot currently be reopened.

Scopes can also be detached, in which case they are never closed, and run until the completion of all tasks.

Implementations

impl Scope

pub fn new() -> Scope

Create a new scope.

The returned scope is a child of the current scope.

Panics

May panic if not called in the context of an executor (e.g. within a call to run).

pub fn new_with_name(name: impl Into<String>) -> Scope

Create a new scope with a name.

The returned scope is a child of the current scope.

Panics

May panic if not called in the context of an executor (e.g. within a call to run).

pub fn current() -> ScopeHandle

Get the scope of the current task, or the global scope if there is no task being polled.

Panics

May panic if not called in the context of an executor (e.g. within a call to run).

pub fn global() -> ScopeHandle

Get the global scope of the executor.

This can be used to spawn tasks that live as long as the executor. Usually, this means until the end of the program or test. This should only be done for tasks where this is expected. If in doubt, spawn on a shorter lived scope instead.

In code that uses scopes, you are strongly encouraged to use this API instead of the spawn APIs on Task.

All scopes are descendants of the global scope.

Panics

May panic if not called in the context of an executor (e.g. within a call to run).

pub fn new_child(&self) -> Scope

Create a child scope.

pub fn new_child_with_name(&self, name: impl Into<String>) -> Scope

Create a child scope with a name.

pub fn name(&self) -> &str

Returns the name of the scope.

pub fn to_handle(&self) -> ScopeHandle

Create a ScopeHandle that may be used to spawn tasks on this scope.

This is a shorthand for scope.as_handle().clone().

Scope holds a ScopeHandle and implements Deref to make its methods available. Note that you should not call scope.clone(), even though the compiler allows it due to the Deref impl. Call this method instead.

pub fn as_handle(&self) -> &ScopeHandle

Get a reference to a ScopeHandle that may be used to spawn tasks on this scope.

Scope holds a ScopeHandle and implements Deref to make its methods available. If you have a Scope but need a &ScopeHandle, prefer calling this method over the less readable &*scope.

pub fn join(self) -> Join

Wait for all tasks in the scope and its children to complete.

New tasks will be accepted on the scope until every task completes and this future resolves.

Note that you can await a scope directly because it implements IntoFuture. scope.join().await is a more explicit form of scope.await.

pub fn close(self) -> Join

Stop accepting new tasks on the scope. Returns a future that waits for every task on the scope to complete.

pub fn cancel(self) -> Join

Cancel all tasks cooperatively in the scope and its children recursively.

cancel first gives a chance to all child tasks (including tasks of child scopes) to shutdown cleanly if they’re holding on to a ScopeActiveGuard. Once no child tasks are holding on to guards, then cancel behaves like Scope::abort, dropping all tasks and stopping them from running at the next yield point. A ScopeActiveGuard provides a cooperative cancellation signal that is triggered by this call, see its documentation for more details.

Once the returned future resolves, no task on the scope will be polled again.

Cancelling a scope does not immediately prevent new tasks from being accepted. New tasks are accepted as long as there are ScopeActiveGuards for this scope.

pub fn abort(self) -> impl Future<Output = ()>

Cancel all tasks in the scope and its children recursively.

Once the returned future resolves, no task on the scope will be polled again. Unlike Scope::cancel, this doesn’t send a cooperative cancellation signal to tasks or child scopes.

When a scope is aborted it immediately stops accepting tasks. Handles of tasks spawned on the scope will pend forever.

Dropping the Scope object is equivalent to calling this method and discarding the returned future. Awaiting the future is preferred because it eliminates the possibility of a task poll completing on another thread after the scope object has been dropped, which can sometimes result in surprising behavior.

pub fn detach(self)

Detach the scope, allowing its tasks to continue running in the background.

Tasks of a detached scope are still subject to join and cancel operations on parent scopes.

Methods from Deref<Target = ScopeHandle>

pub fn new_child(&self) -> Scope

Create a child scope.

pub fn new_child_with_name(&self, name: impl Into<String>) -> Scope

Create a child scope.

pub fn spawn(&self, future: impl Spawnable<Output = ()>) -> JoinHandle<()>

Spawn a new task on the scope.

pub fn spawn_local( &self, future: impl Future<Output = ()> + 'static, ) -> JoinHandle<()>

Spawn a new task on the scope of a thread local executor.

NOTE: This is not supported with a SendExecutor and will cause a runtime panic. Use ScopeHandle::spawn instead.

pub fn compute<T: Send + 'static>( &self, future: impl Spawnable<Output = T> + Send + 'static, ) -> Task<T>

Like spawn, but for tasks that return a result.

NOTE: Unlike spawn, when tasks are dropped, the future will be cancelled.

pub fn compute_local<T: 'static>( &self, future: impl Future<Output = T> + 'static, ) -> Task<T>

Like spawn, but for tasks that return a result.

NOTE: Unlike spawn, when tasks are dropped, the future will be cancelled.

NOTE: This is not supported with a SendExecutor and will cause a runtime panic. Use ScopeHandle::spawn instead.

pub fn close(&self)

Stop the scope from accepting new tasks.

Note that unlike Scope::close, this does not return a future that waits for all tasks to complete. This could lead to resource leaks because it is not uncommon to access a TaskGroup from a task running on the scope itself. If such a task were to await a future returned by this method it would suspend forever waiting for itself to complete.

pub fn active_guard(&self) -> Option<ScopeActiveGuard>

Retrieves a ScopeActiveGuard for this scope.

Note that this may fail if cancellation has already started for this scope. In that case, the caller must assume any tasks from this scope may be dropped at any yield point.

Creating a ScopeActiveGuard is substantially more expensive than just polling it, so callers should maintain the returned guard when success is observed from this call for best performance.

See Scope::cancel for details on cooperative cancellation behavior.

pub fn is_cancelled(&self) -> bool

Returns true if the scope has been signaled to exit via Scope::cancel or Scope::abort.

pub async fn on_no_tasks(&self)

Wait for there to be no tasks. This is racy: as soon as this returns it is possible for another task to have been spawned on this scope.

pub fn wake_all(&self)

Wake all the scope’s tasks so their futures will be polled again.

Trait Implementations

impl Borrow<ScopeHandle> for Scope

fn borrow(&self) -> &ScopeHandle

Immutably borrows from an owned value.

impl Debug for Scope

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

Formats the value using the given formatter.

impl Deref for Scope

type Target = ScopeHandle

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Drop for Scope

Abort the scope and all of its tasks. Prefer using the Scope::abort or Scope::join methods.

fn drop(&mut self)

Executes the destructor for this type.

impl IntoFuture for Scope

type Output = ()

The output that the future will produce on completion.

type IntoFuture = Join

Which kind of future are we turning this into?

fn into_future(self) -> Self::IntoFuture

Creates a future from a value.