[][src]Struct async_scoped::Scope

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

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>[src]

pub unsafe fn create() -> Self[src]

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)[src]

Spawn a future with async_std::task::spawn. 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
)
[src]

Spawn a cancellable future with async_std::task::spawn

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>[src]

pub async fn cancel(&self)[src]

Cancel all futures spawned with cancellation.

pub fn len(&self) -> usize[src]

Total number of futures spawned in this scope.

pub fn remaining(&self) -> usize[src]

Number of futures remaining in this scope.

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

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>[src]

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, 
[src]

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, 
[src]

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, 
[src]

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>[src]

impl<'a, T, Sp: Spawner<T> + Blocker> PinnedDrop for Scope<'a, T, Sp>[src]

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

type Item = Sp::FutureOutput

Values yielded by the stream.

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

impl<'a, T, Sp: Spawner<T> + Blocker> UnsafeUnpin for Scope<'a, T, Sp>[src]

Auto Trait Implementations

impl<'a, T, Sp> !RefUnwindSafe for Scope<'a, T, Sp>[src]

impl<'a, T, Sp> Send for Scope<'a, T, Sp> where
    Sp: Send,
    <Sp as Spawner<T>>::SpawnHandle: Send
[src]

impl<'a, T, Sp> Sync for Scope<'a, T, Sp> where
    Sp: Sync,
    <Sp as Spawner<T>>::SpawnHandle: Sync
[src]

impl<'a, T, Sp> !UnwindSafe for Scope<'a, T, Sp>[src]

Blanket Implementations

impl<T> Any for T where
    T: 'static + ?Sized
[src]

impl<T> Borrow<T> for T where
    T: ?Sized
[src]

impl<T> BorrowMut<T> for T where
    T: ?Sized
[src]

impl<T> From<T> for T[src]

impl<T, U> Into<U> for T where
    U: From<T>, 
[src]

impl<T> StreamExt for T where
    T: Stream + ?Sized
[src]

impl<T> StreamExt for T where
    T: Stream + ?Sized
[src]

impl<S> StreamExt for S where
    S: Stream + ?Sized

impl<T, U> TryFrom<U> for T where
    U: Into<T>, 
[src]

type Error = Infallible

The type returned in the event of a conversion error.

impl<T, U> TryInto<U> for T where
    U: TryFrom<T>, 
[src]

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.

impl<S, T, E> TryStream for S where
    S: Stream<Item = Result<T, E>> + ?Sized
[src]

type Ok = T

The type of successful values yielded by this future

type Error = E

The type of failures yielded by this future

impl<S> TryStreamExt for S where
    S: TryStream + ?Sized
[src]