Struct futures::executor::Spawn

pub struct Spawn<T: ?Sized> { /* private fields */ }

Representation of a spawned future/stream.

This object is returned by the spawn function in this module. This represents a “fused task and future”, storing all necessary pieces of a task and owning the top-level future that’s being driven as well.

A Spawn can be poll’d for completion or execution of the current thread can be blocked indefinitely until a notification arrives. This can be used with either futures or streams, with different methods being available on Spawn depending which is used.

Implementations

impl<F: Future> Spawn<F>

pub fn wait_future(&mut self) -> Result<F::Item, F::Error>

Waits for the internal future to complete, blocking this thread’s execution until it does.

This function will call poll_future in a loop, waiting for the future to complete. When a future cannot make progress it will use thread::park to block the current thread.

impl<S: Stream> Spawn<S>

pub fn wait_stream(&mut self) -> Option<Result<S::Item, S::Error>>

Like wait_future, except only waits for the next element to arrive on the underlying stream.

impl<S: Sink> Spawn<S>

pub fn wait_send(&mut self, value: S::SinkItem) -> Result<(), S::SinkError>

Blocks the current thread until it’s able to send value on this sink.

This function will send the value on the sink that this task wraps. If the sink is not ready to send the value yet then the current thread will be blocked until it’s able to send the value.

pub fn wait_flush(&mut self) -> Result<(), S::SinkError>

Blocks the current thread until it’s able to flush this sink.

This function will call the underlying sink’s poll_complete method until it returns that it’s ready, proxying out errors upwards to the caller if one occurs.

The thread will be blocked until poll_complete returns that it’s ready.

pub fn wait_close(&mut self) -> Result<(), S::SinkError>

Blocks the current thread until it’s able to close this sink.

This function will close the sink that this task wraps. If the sink is not ready to be close yet, then the current thread will be blocked until it’s closed.

impl<T: ?Sized> Spawn<T>

pub fn get_ref(&self) -> &T

Get a shared reference to the object the Spawn is wrapping.

pub fn get_mut(&mut self) -> &mut T

Get a mutable reference to the object the Spawn is wrapping.

pub fn into_inner(self) -> T where
    T: Sized, 

Consume the Spawn, returning its inner object

pub fn poll_fn_notify<N, F, R>(&mut self, notify: &N, id: usize, f: F) -> R where
    F: FnOnce(&mut T) -> R,
    N: Clone + Into<NotifyHandle>, 

Calls the provided closure, scheduling notifications to be sent to the notify argument.

pub fn poll_future_notify<N>(
    &mut self,
    notify: &N,
    id: usize
) -> Poll<T::Item, T::Error> where
    N: Clone + Into<NotifyHandle>,
    T: Future, 

Polls the internal future, scheduling notifications to be sent to the notify argument.

This method will poll the internal future, testing if it’s completed yet. The notify argument is used as a sink for notifications sent to this future. That is, while the future is being polled, any call to task::current() will return a handle that contains the notify specified.

If this function returns NotReady, then the notify should have been scheduled to receive a notification when poll can be called again. Otherwise if Ready or Err is returned, the Spawn task can be safely destroyed.

Note that notify itself is passed as a shared reference, and is itself not required to be a NotifyHandle. The Clone and Into trait bounds will be used to convert this notify to a NotifyHandle if necessary. This construction can avoid an unnecessary atomic reference count bump in some situations.

Unsafety and id

This function and all other *_notify functions on this type will treat the id specified very carefully, explicitly calling functions like the notify argument’s clone_id and drop_id functions. It should be safe to encode a pointer itself into the id specified, such as an Arc<N> or a Box<N>. The clone_id and drop_id functions are then intended to be sufficient for the memory management related to that pointer.

pub fn poll_stream_notify<N>(
    &mut self,
    notify: &N,
    id: usize
) -> Poll<Option<T::Item>, T::Error> where
    N: Clone + Into<NotifyHandle>,
    T: Stream, 

Like poll_future_notify, except polls the underlying stream.

pub fn start_send_notify<N>(
    &mut self,
    value: T::SinkItem,
    notify: &N,
    id: usize
) -> StartSend<T::SinkItem, T::SinkError> where
    N: Clone + Into<NotifyHandle>,
    T: Sink, 

Invokes the underlying start_send method with this task in place.

If the underlying operation returns NotReady then the notify value passed in will receive a notification when the operation is ready to be attempted again.

pub fn poll_flush_notify<N>(
    &mut self,
    notify: &N,
    id: usize
) -> Poll<(), T::SinkError> where
    N: Clone + Into<NotifyHandle>,
    T: Sink, 

Invokes the underlying poll_complete method with this task in place.

If the underlying operation returns NotReady then the notify value passed in will receive a notification when the operation is ready to be attempted again.

pub fn close_notify<N>(
    &mut self,
    notify: &N,
    id: usize
) -> Poll<(), T::SinkError> where
    N: Clone + Into<NotifyHandle>,
    T: Sink, 

Invokes the underlying close method with this task in place.

If the underlying operation returns NotReady then the notify value passed in will receive a notification when the operation is ready to be attempted again.

Trait Implementations

impl<T: Debug + ?Sized> Debug for Spawn<T>

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

Formats the value using the given formatter.