Struct Promise

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

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().

Implementations

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

pub 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> + Send + 'static, F2: FnOnce(E) -> Result<T2, E2> + Send + 'static,

Chains a function to be called after this promise resolves.

pub 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> + Send + 'static,

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

pub fn ok_then<T2, F>(self, callback: F) -> Promise<T2, E>

where T2: Send + 'static, F: Send + 'static + 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.

pub fn err_then<E2, F>(self, errback: F) -> Promise<T, E2>

where F: FnOnce(E) -> Result<T, E2> + 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.

pub fn new<F>(func: F) -> Promise<T, E>

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

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

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

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

pub 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.

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

Creates a promise that resolves to a value

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

Creates a promise that resolves to an error.

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

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