Struct rshark::Future [−] [src]

pub struct Future<T> where T: Send {
    // some fields omitted
}

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> where T: Send

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 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 chain<F, U>(self, func: F) -> Future<U> where U: Send + 'static, F: FnOnce(Option<T>) -> Option<U> + Send + 'static, T: '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, S: Spawner, U: Send + 'static

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

fn then_opt<F, U>(self, func: F) -> Future<U> where U: Send + 'static, F: FnOnce(Option<T>) -> Option<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 U: Send + 'static, F: FnOnce(T) -> 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 U: Send + 'static, F: FnOnce(Option<T>, Promise<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))

Trait Implementations

impl<T> Debug for Future<T> where T: Send + Debug

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

impl<T> IntoIterator for Future<T> where T: Send

type Item = T

type IntoIter = FutureIter<T>

fn into_iter(self) -> Future<T>::IntoIter

impl<T> From<Option<T>> for Future<T> where T: Send

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