Trait conch_runtime::future::EnvFuture [] [src]

pub trait EnvFuture<E: ?Sized> {
    type Item;
    type Error;
    fn poll(&mut self, env: &mut E) -> Poll<Self::Item, Self::Error>;
fn cancel(&mut self, env: &mut E); fn pin_env(self, env: E) -> Pinned<E, Self>
    where
        E: Sized,
        Self: Sized
, { ... }
fn fuse(self) -> Fuse<Self>
    where
        Self: Sized
, { ... }
fn boxed_result<'a>(self) -> BoxedResult<'a, Self>
    where
        Self: Sized,
        Self::Item: 'a + Future
, { ... } }

A trait for objects that behave exactly like the Future trait from the futures crate, however, each object must be polled in the context of some environment.

Note that EnvFuture differs from Future when it comes to dropping or cancelling: callers may need to ensure they call cancel on the EnvFuture before dropping it to ensure all environment state has been reset correctly. See documentation on poll and cancel for more details.

Associated Types

The type of value that this future will resolved with if it is successful.

The type of error that this future will resolve with if it fails in a normal fashion.

Required Methods

Behaves identical to Future::poll when polled with a provided environment.

Caller should take care to always poll this future with the same environment. An implementation may panic or yield incorrect results if it is polled with different environments.

Panics

Once a future has completed (returned Ready or Err from poll, or cancel invoked), then any future calls to poll may panic, block forever, or otherwise cause wrong behavior. The EnvFuture trait itself provides no guarantees about the behavior of poll after a future has completed.

Callers who may call poll too many times may want to consider using the fuse adaptor which defines the behavior of poll, but comes with a little bit of extra cost.

Additionally, calls to poll must always be made from within the context of a task. If a current task is not set then this method will likely panic.

Cancel a future and consider it as completed, thus giving it a chance to run any clean up as if it had resolved on its own.

Although dropping an EnvFuture will effectively cancel it by freeing all resources and not doing any further work, there is no guarantee that the future may not have made temporary changes to the environment it wishes to undo (e.g. temporarily overriding a file descriptor).

Thus if a caller cares about returning the environment to a valid state, they must call cancel before dropping the future. Cancelling a future which has never been polled is considered a valid use case, and should be supported by the implementation.

Caller should take care to cancel this future with the same environment that was provided to poll. An implementation may panic or yield incorrect results if it is polled with a different environment.

Panics

If a future has completed (returned Ready or Err from poll, or cancel invoked) then any future calls to cancel may panic, block forever, or otherwise cause wrong behavior. The EnvFuture trait itself provides no guarantees about the behavior of cancel after a future has completed.

Callers who may call cancel too many times may want to consider using the fuse adaptor which defines the behavior of cancel, but comes with a little bit of extra cost.

Provided Methods

Pin an environment to this future, allowing the resulting future to be polled from anywhere without needing the caller to specify an environment.

Fuse a future such that poll and cancel will never again be called once it has completed.

Currently once a future has returned Ready or Err from poll or if cancel was invoked, any further calls to either method could exhibit bad behavior such as blocking forever, panicking, never returning, etc. If it is known that poll or cancel may be called too often then this method can be used to ensure that it has defined semantics.

Once a future has been fused and it returns a completion from poll or cancelled via cancel, then it will forever returnNotReadyfrompoll(never resolve) and will ignore future calls tocancel. This, unlike the trait'spollandcancel` methods, is guaranteed.

Converts the resulting future into a boxed trait object.

In other words, instead of returning a concrete type, this adapter will return Box<Future> which is useful when type erasure is desired.

Implementations on Foreign Types

impl<'a, T: ?Sized, E: ?Sized> EnvFuture<E> for &'a mut T where
    T: EnvFuture<E>, 
[src]

[src]

[src]

[src]

[src]

[src]

impl<T: ?Sized, E: ?Sized> EnvFuture<E> for Box<T> where
    T: EnvFuture<E>, 
[src]

[src]

[src]

[src]

[src]

[src]

impl<T: ?Sized, E: ?Sized> EnvFuture<E> for Option<OwnedSpawnRefRc<T, E>> where
    T: 'static + SpawnBoxed<E>,
    E: 'static, 
[src]

[src]

[src]

[src]

[src]

[src]

impl<T: ?Sized, E: ?Sized> EnvFuture<E> for Option<OwnedSpawnRefArc<T, E>> where
    T: 'static + SpawnBoxed<E>,
    E: 'static, 
[src]

[src]

[src]

[src]

[src]

[src]

Implementors