Struct ScopeActiveGuard

pub struct ScopeActiveGuard(/* private fields */);

Holds a guard on the creating scope, holding off cancelation.

ScopeActiveGuard allows Scopes to perform cooperative cancellation. ScopeActiveGuard::on_cancel returns a future that resolves when Scope::cancel and ScopeHandle::cancel are called. That is the signal sent to cooperative tasks to stop doing work and finish.

A ScopeActiveGuard is obtained via ScopeHandle::active_guard. ScopeActiveGuard releases the guard on the originating scope on drop.

Implementations

impl ScopeActiveGuard

pub fn as_handle(&self) -> &ScopeHandle

Returns a borrow of the scope handle associated with this guard.

pub fn to_handle(&self) -> ScopeHandle

Returns a clone of the scope handle associated with this guard.

pub async fn on_cancel(&self)

Retrieves a future from this guard that can be polled on for cancellation.

The returned future resolves when the scope is cancelled. Callers should perform teardown and drop the guard when done.

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 Clone for ScopeActiveGuard

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for ScopeActiveGuard

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

Formats the value using the given formatter.

impl Deref for ScopeActiveGuard

type Target = ScopeHandle

The resulting type after dereferencing.

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

Dereferences the value.

impl Drop for ScopeActiveGuard

fn drop(&mut self)

Executes the destructor for this type.