Struct Scope 

pub struct Scope { /* private fields */ }

Available on crate feature std only.

A node in a cancellation tree, held strongly.

A scope is first cancelled (graceful phase: stop taking new work, finish what runs) and then aborted (hard phase: stop now); aborted implies cancelled. Both phases flow from a parent to its children, never upwards, and the earliest cause wins.

Every holder keeps the drain of this scope and its ancestors open, see Scope::join; a WeakScope observes without holding. Dropping a scope cancels nothing.

Scope::child_of makes one scope below several parents: it ends when any of them does, and holds each of them.

The with_* methods change the nodes themselves, so every clone sees them; they only ever move a phase earlier.

Implementations

impl Scope

pub fn new() -> Scope

Create a standalone root scope, active until cancelled.

pub const fn detached() -> Scope

Create a detached scope: never cancelled, and no join waits for work in it.

pub const fn is_detached(&self) -> bool

Whether this is Scope::detached, which tracks nothing and is never cancelled.

pub fn child(&self) -> Scope

Create a child scope: cancelled when this scope is, never the other way around.

The child of Scope::detached is a new root.

pub fn child_of<'a>(parents: impl IntoIterator<Item = &'a Scope>) -> Scope

Create a scope below all of parents: cancelled or aborted as soon as any of them is, and holding each of them, so the Scope::join of every parent waits for it.

Its own phases, holds and builders are those of the new scope only, never of the parents. A parent that is an ancestor of another parent adds nothing, and neither does Scope::detached; without any other parent the new scope is a root.

pub fn maybe_with_timeout(self, timeout: Option<Duration>) -> Scope

Cancel this scope once timeout passed, counted from now.

pub fn maybe_set_timeout(&mut self, timeout: Option<Duration>) -> &mut Scope

Cancel this scope once timeout passed, counted from now.

pub fn with_timeout(self, timeout: Duration) -> Scope

Cancel this scope once timeout passed, counted from now.

pub fn set_timeout(&mut self, timeout: Duration) -> &mut Scope

Cancel this scope once timeout passed, counted from now.

pub fn maybe_with_deadline(self, deadline: Option<Instant>) -> Scope

Cancel this scope at deadline; a deadline in the past counts from now.

pub fn maybe_set_deadline(&mut self, deadline: Option<Instant>) -> &mut Scope

Cancel this scope at deadline; a deadline in the past counts from now.

pub fn with_deadline(self, deadline: Instant) -> Scope

Cancel this scope at deadline; a deadline in the past counts from now.

pub fn set_deadline(&mut self, deadline: Instant) -> &mut Scope

Cancel this scope at deadline; a deadline in the past counts from now.

pub fn maybe_with_hard_timeout(self, timeout: Option<Duration>) -> Scope

Abort this scope once timeout passed, counted from now.

pub fn maybe_set_hard_timeout( &mut self, timeout: Option<Duration>, ) -> &mut Scope

Abort this scope once timeout passed, counted from now.

pub fn with_hard_timeout(self, timeout: Duration) -> Scope

Abort this scope once timeout passed, counted from now.

pub fn set_hard_timeout(&mut self, timeout: Duration) -> &mut Scope

Abort this scope once timeout passed, counted from now.

pub fn maybe_with_hard_deadline(self, deadline: Option<Instant>) -> Scope

Abort this scope at deadline; a deadline in the past counts from now.

pub fn maybe_set_hard_deadline( &mut self, deadline: Option<Instant>, ) -> &mut Scope

Abort this scope at deadline; a deadline in the past counts from now.

pub fn with_hard_deadline(self, deadline: Instant) -> Scope

Abort this scope at deadline; a deadline in the past counts from now.

pub fn set_hard_deadline(&mut self, deadline: Instant) -> &mut Scope

Abort this scope at deadline; a deadline in the past counts from now.

pub fn maybe_with_grace(self, grace: Option<Duration>) -> Scope

Abort this scope grace after it is cancelled, for any cause.

pub fn maybe_set_grace(&mut self, grace: Option<Duration>) -> &mut Scope

Abort this scope grace after it is cancelled, for any cause.

pub fn with_grace(self, grace: Duration) -> Scope

Abort this scope grace after it is cancelled, for any cause.

pub fn set_grace(&mut self, grace: Duration) -> &mut Scope

Abort this scope grace after it is cancelled, for any cause.

pub fn with_signal(self, signal: impl Future + Send + 'static) -> Scope

Cancel this scope when signal completes.

The signal is polled by futures waiting on this scope or its children, never by a spawned task; until one of them observed its completion, Scope::is_cancelled does not report it.

pub fn set_signal(&mut self, signal: impl Future + Send + 'static) -> &mut Scope

Cancel this scope when signal completes.

The signal is polled by futures waiting on this scope or its children, never by a spawned task; until one of them observed its completion, Scope::is_cancelled does not report it.

pub fn with_delayed_signal( self, signal: impl Future + Send + 'static, delay: Duration, ) -> Scope

Cancel this scope delay after signal completes, as Scope::with_signal does once the delay passed. Ancestor phases and hard limits still apply at once.

pub fn set_delayed_signal( &mut self, signal: impl Future + Send + 'static, delay: Duration, ) -> &mut Scope

Cancel this scope delay after signal completes, as Scope::with_signal does once the delay passed. Ancestor phases and hard limits still apply at once.

pub fn with_default_signal(self) -> Scope

Cancel this scope on Ctrl+C, SIGTERM or the platform’s equivalent, see default_signal.

pub fn set_default_signal(&mut self) -> &mut Scope

Cancel this scope on Ctrl+C, SIGTERM or the platform’s equivalent, see default_signal.

pub fn with_hard_signal(self, signal: impl Future + Send + 'static) -> Scope

Abort this scope when signal completes, polled as for Scope::with_signal.

pub fn set_hard_signal( &mut self, signal: impl Future + Send + 'static, ) -> &mut Scope

Abort this scope when signal completes, polled as for Scope::with_signal.

pub fn cancel(&self, cause: Cause)

Cancel this scope; the first cause is kept. No effect on Scope::detached.

pub fn abort(&self, cause: Cause)

Abort this scope, which also cancels it. No effect on Scope::detached.

pub fn run_until_cancelled<F>( &self, future: F, ) -> impl Future<Output = Option<<F as Future>::Output>> + use<F>

where F: Future,

Run future until this scope is cancelled: None once it is, the output otherwise.

Cancellation is checked first, so a cancelled scope never polls future.

pub fn run_until_aborted<F>( &self, future: F, ) -> impl Future<Output = Option<<F as Future>::Output>> + use<F>

where F: Future,

Run future until this scope is aborted: None once it is, the output otherwise.

Abort is checked first, so an aborted scope never polls future.

pub async fn join(self) -> Result<Joined, JoinAborted>

Give up this hold and wait until no holder of this scope or its subtree is left.

Returns once drained, even when the scope was never cancelled: work already done leaves nothing to wait for. From then on the scope is closed and WeakScope::into_scope fails; a scope made by Scope::child_of is closed as a whole once any of its parts is. Returns JoinAborted as soon as the scope is aborted, even when holders remain; await WeakScope::drained for their end. Scope::detached tracks no holders, so it returns at once and is never closed: upgrading it keeps giving Scope::detached. See Scope::join_once_cancelled to wait for the cancel first.

pub async fn join_once_cancelled(self) -> Result<Joined, JoinAborted>

Wait until this scope is cancelled, then Scope::join it: the shutdown of a root whose work may end before it is cancelled. Never returns for Scope::detached.

pub fn cancelled(&self) -> Cancelled

Future that completes once this scope is cancelled (or aborted).

pub fn aborted(&self) -> Aborted

Future that completes once this scope is aborted.

pub fn drained(&self) -> Drained

Future that completes once no strong holder is left in this scope’s subtree.

Holding this scope keeps it from completing. Scope::detached tracks no holders, so its drain is complete at once.

pub fn is_cancelled(&self) -> bool

Whether this scope is cancelled (or aborted).

pub fn is_aborted(&self) -> bool

Whether this scope is aborted.

pub fn cause(&self) -> Option<Cause>

Why this scope is cancelled, if it is: for a scope made by Scope::child_of, the earliest cause, fixed once observed.

pub fn abort_cause(&self) -> Option<Cause>

Why this scope is aborted, if it is, as for Scope::cause.

pub fn into_weak_scope(self) -> WeakScope

Turn this into a WeakScope, giving up this hold.

pub fn clone_weak(&self) -> WeakScope

Get a WeakScope for the same nodes.

impl Scope

pub fn spawn_task<F>( &self, future: F, ) -> JoinHandle<Option<<F as Future>::Output>>

where F: Future + Send + 'static, <F as Future>::Output: Send + 'static,

Spawn a future that holds this scope until it ends: it runs through the graceful phase, so it can drain, and is dropped at the hard phase.

Never refused: this handle holds the scope, so it cannot be closed. Take a hold from a WeakScope with WeakScope::try_hold.

pub fn into_spawn_task<F>( self, future: F, ) -> JoinHandle<Option<<F as Future>::Output>>

where F: Future + Send + 'static, <F as Future>::Output: Send + 'static,

As Scope::spawn_task, giving this handle’s hold to the task.

pub fn spawn_cancellable_task<F>( &self, future: F, ) -> JoinHandle<Option<<F as Future>::Output>>

where F: Future + Send + 'static, <F as Future>::Output: Send + 'static,

Spawn a future that holds this scope and is dropped once the scope is cancelled: work with nothing to drain.

pub fn into_spawn_cancellable_task<F>( self, future: F, ) -> JoinHandle<Option<<F as Future>::Output>>

where F: Future + Send + 'static, <F as Future>::Output: Send + 'static,

As Scope::spawn_cancellable_task, giving this handle’s hold to the task.

pub fn spawn_task_to_completion<F>( &self, future: F, ) -> JoinHandle<<F as Future>::Output>

where F: Future + Send + 'static, <F as Future>::Output: Send + 'static,

Spawn a future that holds this scope and is never stopped by it, not at the hard phase either: it ends on its own, typically by observing Scope::aborted.

For work that has to act at the hard phase itself, such as closing a connection or flushing output. A Scope::join that returns at the hard phase does not wait for it; await its handle when its end matters.

pub fn into_spawn_task_to_completion<F>( self, future: F, ) -> JoinHandle<<F as Future>::Output>

where F: Future + Send + 'static, <F as Future>::Output: Send + 'static,

As Scope::spawn_task_to_completion, giving this handle’s hold to the task.

Trait Implementations

impl Clone for Scope

fn clone(&self) -> Scope

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Scope

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

Formats the value using the given formatter.

impl Default for Scope

fn default() -> Scope

Returns the “default value” for a type.

impl Drop for Scope

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl From<&Scope> for WeakScope

fn from(scope: &Scope) -> WeakScope

Converts to this type from the input type.

impl From<Scope> for WeakScope

fn from(scope: Scope) -> WeakScope

Gives up the hold of scope.