Struct ScopeHandle

pub struct ScopeHandle { /* private fields */ }

A handle to a scope, which may be used to spawn tasks.

Ownership and cycles

Tasks running on a Scope may hold a ScopeHandle to that scope. This does not create an ownership cycle because the task will drop the ScopeHandle once it completes or is cancelled.

Naturally, scopes containing tasks that never complete and that are never cancelled will never be freed. Holding a ScopeHandle does not contribute to this problem.

Implementations

impl ScopeHandle

pub fn new_child(&self) -> Scope

Create a child scope.

pub fn new_child_with_name(&self, name: &str) -> 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 cancel(self) -> impl Future<Output = ()>

Cancel all the scope’s tasks.

Note that if this is called from within a task running on the scope, the task will not resume from the next await point.

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<R> Borrow<ScopeHandle> for ScopeStream<R>

fn borrow(&self) -> &ScopeHandle

Immutably borrows from an owned value.

impl Clone for ScopeHandle

fn clone(&self) -> ScopeHandle

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ScopeHandle

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

Formats the value using the given formatter.