Struct async_scoped::Scope

pub struct Scope<'a, T, Sp: Spawner<T> + Blocker> { /* private fields */ }

A scope to allow controlled spawning of non ’static futures. Futures can be spawned using spawn or spawn_cancellable methods.

Safety

This type uses Drop implementation to guarantee safety. It is not safe to forget this object unless it is driven to completion.

Implementations

impl<'a, T: Send + 'static, Sp: Spawner<T> + Blocker> Scope<'a, T, Sp>

pub unsafe fn create() -> Self

Create a Scope object.

This function is unsafe as futs may hold futures which have to be manually driven to completion.

pub fn spawn<F: Future<Output = T> + Send + 'a>(&mut self, f: F)

Spawn a future with the executor’s task::spawn functionality. The future is expected to be driven to completion before ’a expires.

pub fn spawn_cancellable<F: Future<Output = T> + Send + 'a, Fu: FnOnce() -> T + Send + 'a>(
    &mut self,
    f: F,
    default: Fu
)

Spawn a cancellable future with the executor’s task::spawn functionality.

The future is cancelled if the Scope is dropped pre-maturely. It can also be cancelled by explicitly calling (and awaiting) the cancel method.

pub fn spawn_blocking<F: FnOnce() -> T + Send + 'a>(&mut self, f: F)where
    Sp: FuncSpawner<T, SpawnHandle = <Sp as Spawner<T>>::SpawnHandle>,

Spawn a function as a blocking future with executor’s spawn_blocking functionality.

The future is cancelled if the Scope is dropped pre-maturely. It can also be cancelled by explicitly calling (and awaiting) the cancel method.

impl<'a, T, Sp: Spawner<T> + Blocker> Scope<'a, T, Sp>

pub fn cancel(&mut self)

Cancel all futures spawned with cancellation.

pub fn len(&self) -> usize

Total number of futures spawned in this scope.

pub fn remaining(&self) -> usize

Number of futures remaining in this scope.

pub async fn collect(&mut self) -> Vec<Sp::FutureOutput>

A slighly optimized collect on the stream. Also useful when we can not move out of self.

impl<'a, T, Sp: Spawner<T> + Blocker> Scope<'a, T, Sp>

pub unsafe fn scope<R, F>(f: F) -> (Self, R)where
    T: Send + 'static,
    Sp: Spawner<T> + Blocker,
    F: FnOnce(&mut Scope<'a, T, Sp>) -> R,

Creates a Scope to spawn non-’static futures. The function is called with a block which takes an &mut Scope. The spawn method on this arg. can be used to spawn “local” futures.

Returns

The function returns the created Scope, and the return value of the block passed to it. The returned stream and is expected to be driven completely before being forgotten. Dropping this stream causes the stream to be driven while blocking the current thread. The values returned from the stream are the output of the futures spawned.

Safety

The returned stream is expected to be run to completion before being forgotten. Dropping it is okay, but blocks the current thread until all spawned futures complete.

pub fn scope_and_block<R, F>(f: F) -> (R, Vec<Sp::FutureOutput>)where
    T: Send + 'static,
    Sp: Spawner<T> + Blocker,
    F: FnOnce(&mut Scope<'a, T, Sp>) -> R,

A function that creates a scope and immediately awaits, blocking the current thread for spawned futures to complete. The outputs of the futures are collected as a Vec and returned along with the output of the block.

Safety

This function is safe to the best of our understanding as it blocks the current thread until the stream is driven to completion, implying that all the spawned futures have completed too. However, care must be taken to ensure a recursive usage of this function doesn’t lead to deadlocks.

When scope is used recursively, you may also use the unsafe scope_and_* functions as long as this function is used at the top level. In this case, either the recursively spawned should have the same lifetime as the top-level scope, or there should not be any spurious future cancellations within the top level scope.

pub async unsafe fn scope_and_collect<R, F>(f: F) -> (R, Vec<Sp::FutureOutput>)where
    T: Send + 'static,
    F: FnOnce(&mut Scope<'a, T, Sp>) -> R,

An asynchronous function that creates a scope and immediately awaits the stream. The outputs of the futures are collected as a Vec and returned along with the output of the block.

Safety

This function is not completely safe: please see cancellation_soundness in tests.rs for a test-case that suggests how this can lead to invalid memory access if not dealt with care.

The caller must ensure that the lifetime ’a is valid until the returned future is fully driven. Dropping the future is okay, but blocks the current thread until all spawned futures complete.

Trait Implementations

impl<'a, T, Sp: Spawner<T> + Blocker> Drop for Scope<'a, T, Sp>

fn drop(&mut self)

Executes the destructor for this type.

impl<'a, T, Sp: Spawner<T> + Blocker> Stream for Scope<'a, T, Sp>

type Item = <Sp as Spawner<T>>::FutureOutput

Values yielded by the stream.

fn poll_next(
    self: Pin<&mut Self>,
    cx: &mut Context<'_>
) -> Poll<Option<Self::Item>>

Attempt to pull out the next value of this stream, registering the current task for wakeup if the value is not yet available, and returning None if the stream is exhausted.

fn size_hint(&self) -> (usize, Option<usize>)

Returns the bounds on the remaining length of the stream.

impl<'pin, 'a, T, Sp: Spawner<T> + Blocker> Unpin for Scope<'a, T, Sp>where
    __Scope<'pin, 'a, T, Sp>: Unpin,