Copyright 2008 - 2009 Tony Morris, Runar Bjarnason, Tom Adams, Brad Clow, Ricky Clarkson, Nick Partridge, Jason Zaugg

This software is released under an open source BSD licence.

fj.control.parallel
Class Promise<A>

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

public final class Promise<A>
extends 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, 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<Callable<A>>
promise(Strategy<Unit> s, 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<Callable<A>> promise(Strategy<Unit> s,
                                               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,
                       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.

Copyright 2008 - 2009 Tony Morris, Runar Bjarnason, Tom Adams, Brad Clow, Ricky Clarkson, Nick Partridge, Jason Zaugg

This software is released under an open source BSD licence.