Struct ScopeStream

pub struct ScopeStream<R> { /* private fields */ }

Similar to a scope but all futures spawned on the scope must finish with the same result type. That allows the scope to return a stream of results. Attempting to spawn tasks using ScopeHandle::spawn (or similar) will result in tasks that are immediately dropped (just as if the scope was closed). Like a regular scope, the scope can be closed, at which point the stream will terminate once all the tasks have finished. This is designed to be a fairly close drop-in replacement to FuturesUnordered, the principle difference being that the tasks run in parallel rather than just concurrently. Another difference is that the futures don’t need to be the same type; only the outputs do. In all other respects, the scope operates like a regular scope i.e. it can have children, you can join them, cancel them, etc.

Implementations

impl<R: Send + 'static> ScopeStream<R>

pub fn new() -> (Self, ScopeStreamHandle<R>)

Creates a new scope stream.

The returned scope stream is a child of the current scope.

Panics

May panic if not called in the context of an executor (e.g. within a call to run).

pub fn new_with_name(name: impl Into<String>) -> (Self, ScopeStreamHandle<R>)

Creates a new scope stream with a name.

The returned scope stream is a child of the current scope.

Panics

May panic if not called in the context of an executor (e.g. within a call to run).

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 async fn on_no_tasks_and_guards(&self)

Wait for there to be no tasks and no guards. This is racy: as soon as this returns it is possible for another task to have been spawned on this scope, or for there to be guards.

pub fn wake_all_with_active_guard(&self)

Wake all the scope’s tasks so their futures will be polled again.

Trait Implementations

impl<R> Borrow<ScopeHandle> for ScopeStream<R>

fn borrow(&self) -> &ScopeHandle

Immutably borrows from an owned value.

impl<R> Deref for ScopeStream<R>

type Target = ScopeHandle

The resulting type after dereferencing.

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

Dereferences the value.

impl<R> Drop for ScopeStream<R>

fn drop(&mut self)

Executes the destructor for this type.

impl<F: Spawnable<Output = R>, R: Send + 'static> FromIterator<F> for ScopeStream<R>

fn from_iter<T: IntoIterator<Item = F>>(iter: T) -> Self

Creates a value from an iterator.

impl<R: Send + 'static> Stream for ScopeStream<R>

type Item = R

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.