Struct futures::executor::Spawn

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

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.

Methods

impl<F: Future> Spawn<F>

fn poll_future(&mut self, unpark: Arc<Unpark>) -> Poll<F::Item, F::Error>

Deprecated

: recommended to use poll_future_notify instead

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

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

If this function returns NotReady, then the unpark 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.

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.

fn execute(self, exec: Arc<Executor>) where
    F: Future<Item = (), Error = ()> + Send + 'static, 

A specialized function to request running a future to completion on the specified executor.

This function only works for futures whose item and error types are () and also implement the Send and 'static bounds. This will submit units of work (instances of Run) to the exec argument provided necessary to drive the future to completion.

When the future would block, it's arranged that when the future is again ready it will submit another unit of work to the exec provided. This will happen in a loop until the future has completed.

This method is not appropriate for all futures, and other kinds of executors typically provide a similar function with perhaps relaxed bounds as well.

Note that this method is likely to be deprecated in favor of the futures::Executor trait and execute method, but if this'd cause difficulty for you please let us know!

impl<S: Stream> Spawn<S>

fn poll_stream(
    &mut self,
    unpark: Arc<Unpark>
) -> Poll<Option<S::Item>, S::Error>

Deprecated

: recommended to use poll_stream_notify instead

Like poll_future, except polls the underlying stream.

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>

fn start_send(
    &mut self,
    value: S::SinkItem,
    unpark: &Arc<Unpark>
) -> StartSend<S::SinkItem, S::SinkError>

Deprecated

: recommended to use start_send_notify instead

Invokes the underlying start_send method with this task in place.

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

fn poll_flush(&mut self, unpark: &Arc<Unpark>) -> Poll<(), S::SinkError>

Deprecated

: recommended to use poll_flush_notify instead

Invokes the underlying poll_complete method with this task in place.

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

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.

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.

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>

fn get_ref(&self) -> &T

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

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

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

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

Consume the Spawn, returning its inner object

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.

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.

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.

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.

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.