Struct promises::Promise

pub struct Promise<T: Send, E: Send> { /* fields omitted */ }

A promise is a way of doing work in the background. The promises in this library have the same featureset as those in Ecmascript 5.

Promises

Promises (sometimes known as "futures") are objects that represent asynchronous tasks being run in the background, or results which will exist in the future. A promise will be in state of running, fulfilled, rejected, or done. In order to use the results of a fulfilled promise, one attaches another promise to it (i.e. via then). Like their Javascript counterparts, promises can return an error (of type E). Unlike Javascript, success or failure is indicated by a Result type. This is much more Rustic and allows existing functions which return a Result<T, E> to be used.

Panics

If the function being executed by a promise panics, it does so silently. The panic will not resurface in the thread which created the promise, and promises waiting on its result will never be called. In addition, the all and race proimse methods will ignore "dead" promises. They will remove promises from their lists, and if there aren't any left they will silently exit without doing anything.

Unfortunately, panics must be ignored for two reasons: * Panic messages don't have a concrete type yet in Rust. If they did, promiess would be able to inspect their predecessors' errors. * Although a Receiver can correctly handle its paired Sender being dropped, such as during a panic, for reasons stated above the "message" of the panic is not relayed.

Finally, Ecmascript promises themselves do have the ability to return and error type, represented as a Result<T, E> here. Thus, one should use try! and other error handling rather than calls to unwrap().

Methods

impl<T: Send + 'static, E: Send + 'static> Promise<T, E>

fn then<T2, E2, F1, F2>(self, callback: F1, errback: F2) -> Promise<T2, E2> where
    T2: Send + 'static,
    E2: Send + 'static,
    F1: FnOnce(T) -> Result<T2, E2>,
    F2: FnOnce(E) -> Result<T2, E2>,
    F1: Send + 'static,
    F2: Send + 'static, 

Chains a function to be called after this promise resolves.

fn then_result<T2, E2, F>(self, callback: F) -> Promise<T2, E2> where
    T2: Send + 'static,
    E2: Send + 'static,
    F: FnOnce(Result<T, E>) -> Result<T2, E2>,
    F: Send + 'static, 

Chains a function to be called after this promise resolves, using a Result type.

fn ok_then<T2, F>(self, callback: F) -> Promise<T2, E> where
    T2: Send + 'static,
    F: Send + 'static,
    F: FnOnce(T) -> Result<T2, E>, 

Calls a function on the result of the promise if it is fulfilled.

This is equivalent to a Javascript promise's then with one callback, or Rust's Result::map.

fn err_then<E2, F>(self, errback: F) -> Promise<T, E2> where
    F: FnOnce(E) -> Result<T, E2>,
    F: Send + 'static,
    E2: Send + 'static, 

Calls a function of the result of the promise if it fails.

This is equivalent to Javascript promise's catch.

fn new<F>(func: F) -> Promise<T, E> where
    F: FnOnce() -> Result<T, E>,
    F: Send + 'static, 

Creates a new promsie, which will eventually resolve to one of the values of the Result<T, E> type.

fn race(promises: Vec<Promise<T, E>>) -> Promise<T, E>

Applies a promise to the first of some promises to become fulfilled.

fn all(promises: Vec<Promise<T, E>>) -> Promise<Vec<T>, E>

Calls a function with the result of all of the promises, or the error of the first promise to error.

fn resolve(val: T) -> Promise<T, E>

Creates a promise that resolves to a value

fn reject(val: E) -> Promise<T, E>

Creates a promise that resolves to an error.

fn from_result(result: Result<T, E>) -> Promise<T, E>

Creates a new promise that will resolve to the result value.