fj.control.parallel
Class Promise<A>

java.lang.Object
  fj.control.parallel.Promise<A>

public final class Promise<A>
extends java.lang.Object

Represents a non-blocking future value. Products, functions, and actors, given to the methods on this class, are executed concurrently, and the Promise serves as a handle on the result of the computation. Provides monadic operations so that future computations can be combined

Author: Runar

Method Summary

<B> Promise<B>	apply(Promise<F<A,B>> pf) Performs function application within a promise (applicative functor pattern).
<B> Promise<B>	bind(F<A,Promise<B>> f) Binds the given function over this promise, with a final join.
<B,C> Promise<C>	bind(P1<Promise<B>> p, F<A,F<B,C>> f) Binds the given function to this promise and the given promise, with a final join.
<B,C> Promise<C>	bind(Promise<B> pb, F<A,F<B,C>> f) Binds the given function to this promise and the given promise, with a final join.
A	claim() Waits if necessary for the computation to complete, and then retrieves its result.
Option<A>	claim(long timeout, java.util.concurrent.TimeUnit unit) Waits if necessary for the computation to complete, and then retrieves its result.
<B> Promise<B>	cobind(F<Promise<A>,B> f) Binds the given function across a promise of this promise (Comonad pattern).
Promise<Promise<A>>	cojoin() Duplicates this promise to a promise of itself (Comonad pattern).
static <A,B> F<Promise<A>,Promise<B>>	fmap_(F<A,B> f) Promotes any function to a transformation between promises (covariant functor pattern).
<B> Promise<B>	fmap(F<A,B> f) Provides a promise to apply the given function to this promise's future value (covariant functor pattern).
static <A,B> F<List<A>,Promise<B>>	foldRight(Strategy<Unit> s, F<A,F<B,B>> f, B b) Performs a right-fold reduction across a list in constant stack space.
static <A,B> F<Stream<A>,Promise<B>>	foldRightS(Strategy<Unit> s, F<A,F<P1<B>,B>> f, B b) Performs a right-fold reduction across a Stream in constant stack space.
boolean	isFulfilled() Returns true if this promise has been fulfilled.
static <A> Promise<A>	join(Promise<Promise<A>> p) Turns a promise of a promise into just a promise.
static <A> Promise<A>	join(Strategy<Unit> s, P1<Promise<A>> p) Turns a product of a promise into just a promise.
static <A,B,C> F<Promise<A>,F<Promise<B>,Promise<C>>>	liftM2(F<A,F<B,C>> f) Promotes a function of arity-2 to a function on promises.
static <A> F<P1<A>,Promise<A>>	promise(Strategy<Unit> s) Provides a first-class unit function for promises.
static <A> Promise<java.util.concurrent.Callable<A>>	promise(Strategy<Unit> s, java.util.concurrent.Callable<A> a) Provides a promise to call the given Callable in the future.
static <A,B> F<A,Promise<B>>	promise(Strategy<Unit> s, F<A,B> f) Transforms any function so that it returns a promise of a value instead of an actual value.
static <A> Promise<A>	promise(Strategy<Unit> s, P1<A> a) Promises to provide the value of the given 1-product, in the future.
static <A> F<List<Promise<A>>,Promise<List<A>>>	sequence(Strategy<Unit> s) First-class version of the sequence function through a List.
static <A> Promise<List<A>>	sequence(Strategy<Unit> s, List<Promise<A>> as) Turns a List of promises into a single promise of a List.
static <A> Promise<P1<A>>	sequence(Strategy<Unit> s, P1<Promise<A>> p) Transforms a product of a promise to a promise of a product.
static <A> Promise<Stream<A>>	sequence(Strategy<Unit> s, Stream<Promise<A>> as) Turns a Stream of promises into a single promise of a Stream.
static <A> F<List<Promise<A>>,Promise<List<A>>>	sequenceS(Strategy<Unit> s) First-class version of the sequence function through a Stream.
<B> Stream<B>	sequenceW(Stream<F<Promise<A>,B>> fs) Applies a stream of comonadic functions to this promise, returning a stream of values.
void	to(Actor<A> a) Promises to send a value to the given actor in the future.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

promise

public static <A> Promise<A> promise(Strategy<Unit> s,
                                     P1<A> a)

Promises to provide the value of the given 1-product, in the future. Represents the unit function for promises.

Parameters:

s - The strategy with which to fulfil the promise.

a - The 1-product to evaluate concurrently.

Returns:

A promise representing the future result of evaluating the given 1-product.

promise

public static <A> F<P1<A>,Promise<A>> promise(Strategy<Unit> s)

Provides a first-class unit function for promises.

Parameters:

s - The strategy with which to fulfil promises.

Returns:

A function that, given a 1-product, yields a promise of that product's value.

promise

public static <A> Promise<java.util.concurrent.Callable<A>> promise(Strategy<Unit> s,
                                                                    java.util.concurrent.Callable<A> a)

Provides a promise to call the given Callable in the future.

Parameters:

s - The strategy with which to fulfil the promise.

a - The Callable to evaluate concurrently.

Returns:

A promise of a new Callable that will return the result of calling the given Callable.

promise

public static <A,B> F<A,Promise<B>> promise(Strategy<Unit> s,
                                            F<A,B> f)

Transforms any function so that it returns a promise of a value instead of an actual value. Represents the Kleisli arrow for the Promise monad.

Parameters:

s - The strategy with which to fulfil the promise.

f - The function to turn into a promise-valued function.

Returns:

The given function transformed into a function that returns a promise.

to

public void to(Actor<A> a)

Promises to send a value to the given actor in the future.

Parameters:

a - An actor that will receive this Promise's value in the future.

fmap

public <B> Promise<B> fmap(F<A,B> f)

Provides a promise to apply the given function to this promise's future value (covariant functor pattern).

Parameters:

f - The function to apply to this promise's future value.

Returns:

A promise representing the future result of applying the given function to this promised value.

fmap_

public static <A,B> F<Promise<A>,Promise<B>> fmap_(F<A,B> f)

Promotes any function to a transformation between promises (covariant functor pattern).

Parameters:

f - The function to promote to a transformation between promises.

Returns:

That function lifted to a function on Promises.

join

public static <A> Promise<A> join(Promise<Promise<A>> p)

Turns a promise of a promise into just a promise. The join function for the Promise monad. Promise to give it a Promise of an A, and it will promise you an A in return.

Parameters:

p - A promise of a promise.

Returns:

The promised promise.

join

public static <A> Promise<A> join(Strategy<Unit> s,
                                  P1<Promise<A>> p)

Turns a product of a promise into just a promise. Does not block on the product by calling it, but creates a new promise with a final join.

Parameters:

s - The strategy with which to fulfil the promise.

p - A product-1 of a promise to turn into just a promise.

Returns:

The joined promise.

bind

public <B> Promise<B> bind(F<A,Promise<B>> f)

Binds the given function over this promise, with a final join. The bind function for the Promise monad.

Parameters:

f - The function to bind over this promise.

Returns:

The result of applying the given function to this promised value.

apply

public <B> Promise<B> apply(Promise<F<A,B>> pf)

Performs function application within a promise (applicative functor pattern).

Parameters:

pf - The promised function to apply.

Returns:

A new promise after applying the given promised function to this promise.

bind

public <B,C> Promise<C> bind(Promise<B> pb,
                             F<A,F<B,C>> f)

Binds the given function to this promise and the given promise, with a final join.

Parameters:

pb - A promise with which to bind the given function.

f - The function to apply to the given promised values.

Returns:

A new promise after performing the map, then final join.

bind

public <B,C> Promise<C> bind(P1<Promise<B>> p,
                             F<A,F<B,C>> f)

Binds the given function to this promise and the given promise, with a final join.

Parameters:

p - A promise with which to bind the given function.

f - The function to apply to the given promised values.

Returns:

A new promise after performing the map, then final join.

liftM2

public static <A,B,C> F<Promise<A>,F<Promise<B>,Promise<C>>> liftM2(F<A,F<B,C>> f)

Promotes a function of arity-2 to a function on promises.

Parameters:

f - The function to promote.

Returns:

A function of arity-2 promoted to map over promises.

sequence

public static <A> Promise<List<A>> sequence(Strategy<Unit> s,
                                            List<Promise<A>> as)

Turns a List of promises into a single promise of a List.

Parameters:

s - The strategy with which to sequence the promises.

as - The list of promises to transform.

Returns:

A single promise for the given List.

sequence

public static <A> F<List<Promise<A>>,Promise<List<A>>> sequence(Strategy<Unit> s)

First-class version of the sequence function through a List.

Parameters:

s - The strategy with which to sequence a given list of promises.

Returns:

A function that turns a list of promises into a single promise of a list.

sequence

public static <A> Promise<Stream<A>> sequence(Strategy<Unit> s,
                                              Stream<Promise<A>> as)

Turns a Stream of promises into a single promise of a Stream.

Parameters:

s - The strategy with which to sequence the promises.

as - The Stream of promises to transform.

Returns:

A single promise for the given Stream.

sequenceS

public static <A> F<List<Promise<A>>,Promise<List<A>>> sequenceS(Strategy<Unit> s)

First-class version of the sequence function through a Stream.

Parameters:

s - The strategy with which to sequence a given Stream of promises.

Returns:

A function that turns a list of promises into a single promise of a Stream..

sequence

public static <A> Promise<P1<A>> sequence(Strategy<Unit> s,
                                          P1<Promise<A>> p)

Transforms a product of a promise to a promise of a product.

Parameters:

s - The strategy with which to traverse the promise.

p - A product of a promise to traverse.

Returns:

A promised product.

foldRight

public static <A,B> F<List<A>,Promise<B>> foldRight(Strategy<Unit> s,
                                                    F<A,F<B,B>> f,
                                                    B b)

Performs a right-fold reduction across a list in constant stack space.

Parameters:

s - The strategy with which to fold the list.

f - The function to apply on each element of the list.

b - The beginning value to start the application from.

Returns:

The final result after the right-fold reduction.

foldRightS

public static <A,B> F<Stream<A>,Promise<B>> foldRightS(Strategy<Unit> s,
                                                       F<A,F<P1<B>,B>> f,
                                                       B b)

Performs a right-fold reduction across a Stream in constant stack space.

Parameters:

s - The strategy with which to fold the Stream.

f - The function to apply on each element of the Stream.

b - The beginning value to start the application from.

Returns:

The final result after the right-fold reduction.

claim

public A claim()

Waits if necessary for the computation to complete, and then retrieves its result.

Returns:

The promised value.

claim

public Option<A> claim(long timeout,
                       java.util.concurrent.TimeUnit unit)

Waits if necessary for the computation to complete, and then retrieves its result.

Parameters:

timeout - the maximum time to wait

unit - the time unit of the timeout argument

Returns:

The promised value, or none if the timeout was reached.

isFulfilled

public boolean isFulfilled()

Returns true if this promise has been fulfilled.

Returns:

true if this promise has been fulfilled.

cobind

public <B> Promise<B> cobind(F<Promise<A>,B> f)

Binds the given function across a promise of this promise (Comonad pattern).

Parameters:

f - A function to apply within a new promise of this promise.

Returns:

A new promise of the result of applying the given function to this promise.

cojoin

public Promise<Promise<A>> cojoin()

Duplicates this promise to a promise of itself (Comonad pattern).

Returns:

a promise of this promise.

sequenceW

public <B> Stream<B> sequenceW(Stream<F<Promise<A>,B>> fs)

Applies a stream of comonadic functions to this promise, returning a stream of values.

Parameters:

fs - A stream of functions to apply to this promise.

Returns:

A stream of the results of applying the given stream of functions to this promise.