Struct promising_future::Future [−] [src]

pub struct Future<T>(_);

An undetermined value.

A Future represents an undetermined value. A corresponding Promise may set the value.

It is typically created in a pair with a Promise using the function future_promise().

Methods

impl<T> Future<T>

fn with_value(v: T) -> Future<T>

Construct an already resolved Future with a value. It is equivalent to a Future whose Promise has already been fulfilled.

let fut = Future::with_value(123);
match fut.poll() {
   Pollresult::Resolved(Some(123)) => println!("ok"),
   _ => panic!("unexpected result"),
}

fn never() -> Future<T>

Construct a resolved Future which will never have a value; it is equivalent to a Future whose Promise completed unfulfilled.

let fut = Future::<i32>::never();
match fut.poll() {
   Pollresult::Resolved(None) => println!("ok"),
   _ => panic!("unexpected result"),
}

fn poll(self) -> Pollresult<T>

Test to see if the Future is resolved yet.

It returns an Pollresult, which has two values:

  • Unresolved(Future<T>) - the Future is not yet resolved, so returns itself, or
  • Resolved(Option<T>) - the Future has been resolved, and may have a value.
match fut.poll() {
  Pollresult::Unresolved(fut) => println!("unresolved future {:?}", fut),
  Pollresult::Resolved(None) => println!("resolved, no value"),
  Pollresult::Resolved(Some(v)) => println!("resolved, value {}", v),
}

fn poll_ref(&mut self) -> Result<Option<&T>, ()>

Non-destructively poll a Futures value.

If the Future has been resolved, returns Ok with Some value (or None if unfulfilled). Otherwise returns Err(()).

TODO: Reuse Pollresult with type param for Future/&Future?

let mut fut = Future::with_value(123);
assert_eq!(fut.poll_ref(), Ok(Some(&123)))

fn value(self) -> Option<T>

Block until the Future is resolved.

If the Future is not yet resolved, it will block until the corresponding Promise is either fulfilled, or is completed unfulfilled. In the former case it will return Some(v), otherwise None.

If the Future is already resolved - ie, has no corresponding Promise - then it will return immediately without blocking.

match fut.value() {
  Some(v) => println!("has value {}", v),
  None => println!("no value"),
}

fn value_ref(&mut self) -> Option<&T>

Non-destructively get a reference to the Futures value.

Wait until a Future is resolved - if necessary - and return a reference to the value. The lifetime is tied to the Futures lifetime. Use value() to take ownership of the value and consume the Future.

fn then_opt<F, U>(self, func: F) -> Future<U> where F: FnOnce(Option<T>) -> Option<U> + Send + 'static, U: Send + 'static

Set a synchronous callback to run in the Promise's context.

When the Future<T> completes, call the function on the value (if any), returning a new value which appears in the returned Future<U>.

The function is called within the Promises context, and so will block the thread if it takes a long time. Because the callback returns a value, not a Future it cannot be async. See callback or chain for more general async ways to apply a function to a Future.

let (fut, prom) = future_promise();

let fut = fut.then_opt(|v| v.map(|v| v + 123));
prom.set(1);
assert_eq!(fut.value(), Some(124))

fn then<F, U>(self, func: F) -> Future<U> where F: FnOnce(T) -> U + Send + 'static, U: Send + 'static

Set synchronous callback

Simplest form of callback. This is only called if the promise is fulfilled, and may only allow a promise to be fulfilled.

fn callback<F, U>(self, func: F) -> Future<U> where F: FnOnce(Option<T>, Promise<U>) + Send + 'static, U: Send + 'static

Set a callback to run in the Promise's context.

This function sets a general purpose callback which is called when a Future is resolved. It is called in the Promise's context, so if it is long-running it will block whatever thread that is. (If the Future is already resolved, it is the calling thread.)

The value passed to the callback is an Option - if it is None it means the promise was unfulfilled.

The callback is passed a new Promise<U> which is paired with the Future<U> this function returns; the callback may either set a value on it, pass it somewhere else, or simply drop it leaving the promise unfulfilled.

This is the most general form of a completion callback; see also then and chain for simpler interfaces which are often all that's needed.

let (fut, prom) = future_promise();

let fut = fut.callback(|v, p| {
   match v {
     None => (), // drop p
     Some(v) => p.set(v + 123),
   }
});
prom.set(1);
assert_eq!(fut.value(), Some(124))

fn callback_unit<F>(self, func: F) where F: FnOnce(Option<T>) + Send + 'static

Set a callback which returns ()

Set a callback with a closure which returns nothing, so its only useful for its side-effects.

impl<T: Send> Future<T>

fn chain<F, U>(self, func: F) -> Future<U> where F: FnOnce(Option<T>) -> Option<U> + Send + 'static, T: 'static, U: Send + 'static

Chain two Futures.

Asynchronously apply a function to the result of a Future, returning a new Future for that value. This may spawn a thread to block waiting for the first Future to complete.

The function is passed an Option, which indicates whether the Future ever received a value. The function returns an Option so that the resulting Future can also be valueless.

fn chain_with<F, U, S>(self, func: F, spawner: &S) -> Future<U> where F: FnOnce(Option<T>) -> Option<U> + Send + 'static, T: 'static, U: Send + 'static, S: Spawner

As with chain, but pass a Spawner to control how the thread is created.

Trait Implementations

impl<T> From<Option<T>> for Future<T>

fn from(v: Option<T>) -> Future<T>

impl<T> IntoIterator for Future<T>

type Item = T

type IntoIter = FutureIter<T>

fn into_iter(self) -> Self::IntoIter

Derived Implementations

impl<T: Debug> Debug for Future<T>

fn fmt(&self, __arg_0: &mut Formatter) -> Result