net.sf.asyncobjects
Class Promise<T>

java.lang.Object
  net.sf.asyncobjects.Promise<T>

Type Parameters:

T - a value type for promise

All Implemented Interfaces:

ExplicitSharing

public final class Promise<T>
extends Object
implements ExplicitSharing

A promise represents outcome of some asynchronous operation. The promise resolves to some value if operation is successful or is smashed with failure otherwise. An asychronous operation might never finish, in such case a promise stays unresolved forever.

A promise should be never directly accessed outside of vat where it were created. There are two indirect ways to access it from other vats:

1. Using resolver interface.
2. Using proxy created with willBe method.

The promise has three fundamental states:

UNRESOLVED

This is an inital state of promise.

RESOLVED

This state means that operation that created this promise has completed successfully. The promise goes into this state after AResolver.resolve(Object) method has been called on promise resolver. This is final state, and promise cannot change state after this state is reached. The promise can be created in the resolved state using the constructor Promise(Object) or the method with(Object)

SMASHED

This state means that operation that created this promise has failed with throwable (exception or error). The promise goes into this state after AResolver.smash(Throwable) method has been called on promise resolver. The promise could be also created in the smashed state using the method smashed(Throwable).

Note if promise is resolved with implementation of AsyncObject interface for which AsyncObject.isImmediate() == false, it does not consider itself resolved. Instead it invokes AsyncObject.dereference(AResolver) method with resolver() in order to receive actual resolution.

When promise is either resolved or smashed, it notifies downstream resolvers that has been registered using dereference(AResolver) method. After downstream resolver is registered, it is notified at most once. If resolver is registered after promise is resolved or smashed, the downstream resolver is notifed immediatly about outcome of operation.

Nested Class Summary

class

Promise.InternalPromiseResolverImpl This is an internal class.

Field Summary

static int	RESOLVED resolved state
static int	SMASHED broken state
static int	UNRESOLVED unresolved state

Constructor Summary

Promise()
A constructor for promise

Promise(T value)
A constructor for promise.

Method Summary

<O> Promise<O>	cast(Class<O> type) Cast promise to another type.
void	dereference(AResolver<? super T> l) Register resolver for the promise.
static void	ensureSharable(Object o) Ensure that value is sharable
Promise<Void>	finished()
static Promise<Void>	finished(Promise<?> in)
boolean	isResolved()
boolean	isSmashed()
boolean	isUnresolved()
static <O> Promise<O>	notNull(Promise<? extends O> p) Return promise that never returns null.
static <O> Promise<O>	notNull(Promise<? extends O> p, String text) Return promise that never returns null.
static <T> Promise<T>	nullPromise() Return a promise resolved to null.
Throwable	problem()
AResolver<T>	resolver() Get resolver for this promise.
static <T> Promise<T>	smashed(Throwable t) Create smashed promise
Promise<Void>	toVoid() Convert promise to promise for void
static Promise<Void>	toVoid(Promise<?> in) Convert promise to promise for void
static <A> Promise<A>	upcast(Promise<? extends A> p) Upcast the promise.
T	value()
<P extends AsyncObject> P	willBe(Class<P> proxyType) This method allows creation of the proxy that allows sending message to resolution before promise is resolved.
static <T> Promise<T>	with(T value) Get promise with value

Methods inherited from class java.lang.Object

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

Field Detail

SMASHED

public static final int SMASHED

broken state

See Also:

Constant Field Values

RESOLVED

public static final int RESOLVED

resolved state

See Also:

Constant Field Values

UNRESOLVED

public static final int UNRESOLVED

unresolved state

See Also:

Constant Field Values

Constructor Detail

Promise

public Promise(T value)

A constructor for promise. Promise starts being in resolved state unless unerolved buffering proxy is passed as the value..

Parameters:

value - a value to resolve promise with.

Promise

public Promise()

A constructor for promise

Method Detail

resolver

public AResolver<T> resolver()

Get resolver for this promise. The resolver could be obtained only once.

Returns:

resolver for this promise

willBe

public <P extends AsyncObject> P willBe(Class<P> proxyType)

This method allows creation of the proxy that allows sending message to resolution before promise is resolved.

If promise is resolved with some value, it is checked if the resolution supports interface represented by _class parameter. If the interface is supported, all pending invocations are sent to resolution including dereference calls.* If the interface is not supported by resolution, the behavior is that same as if promise were smashed with ClassCastException. If promise is resolves to null, the behavior of reference is the same as if it were smashed with NullPointerException. If promise was smashed with some exception, all promises and eventual proxies returned by previous method invocations are smashed with this exception. And the method AResolver.smash(Throwable) will be called on pending dereference() calls.

Type Parameters:

P - A proxy type

Parameters:

proxyType -

Returns:

proxy that records until this promise is resolved or smashed.

isResolved

public boolean isResolved()

Returns:

true, if promise is resolved

isSmashed

public boolean isSmashed()

Returns:

true, if promise is broken

isUnresolved

public boolean isUnresolved()

Returns:

true, if promise is unresolved

problem

public Throwable problem()

Returns:

problem if promise is broken

value

public T value()

Returns:

value if promise is resolved

dereference

public void dereference(AResolver<? super T> l)

Register resolver for the promise. Note that resolver is expected to be asynchronous object.

Parameters:

l - listener to register

ensureSharable

public static void ensureSharable(Object o)

Ensure that value is sharable

Parameters:

o - an object to check

toVoid

public Promise<Void> toVoid()

Convert promise to promise for void

Returns:

converted promise

finished

public Promise<Void> finished()

Returns:

a promise that resolves to null when promise finishes in one way or another. This is done to supress failures.

finished

public static Promise<Void> finished(Promise<?> in)

Parameters:

in - an input promise

Returns:

a promise that resolves to null when promise finishes in one way or another. This is done to supress failures.

toVoid

public static Promise<Void> toVoid(Promise<?> in)

Convert promise to promise for void

Parameters:

in - an input promise

Returns:

converted promise

nullPromise

public static <T> Promise<T> nullPromise()

Return a promise resolved to null.

Type Parameters:

T - a type of promise

Returns:

a promise for null

with

public static <T> Promise<T> with(T value)

Get promise with value

Type Parameters:

T - a value type

Parameters:

value - a value

Returns:

a promise that resolved with value

smashed

public static <T> Promise<T> smashed(Throwable t)

Create smashed promise

Type Parameters:

T - a type of promise

Parameters:

t - a promise value

Returns:

smashed promise

cast

public <O> Promise<O> cast(Class<O> type)

Cast promise to another type. The resulting promise will resolve to casted value or will be smashed with ClassCastException if cast is impossible.

Type Parameters:

O - a new type of promise

Parameters:

type - a new expected type

Returns:

a promise that will resolve to casted value

upcast

public static <A> Promise<A> upcast(Promise<? extends A> p)

Upcast the promise. The only case when this is not a type safe operation is when resolver is got from this promise with resolver().

Type Parameters:

A - a supper type

Parameters:

p - a promise to upcast

Returns:

an upcasted promise

notNull

public static <O> Promise<O> notNull(Promise<? extends O> p)

Return promise that never returns null. Instead, it is automatically smashed with NullPointerException if argument promise resolves to the null.

Type Parameters:

O - a type

Parameters:

p - an arugment promise

Returns:

a promise that is smashed in case of null

notNull

public static <O> Promise<O> notNull(Promise<? extends O> p,
                                     String text)

Return promise that never returns null. Instead, it is automatically smashed with NullPointerException if argument promise resolves to the null.

Type Parameters:

O - a type

Parameters:

p - an arugment promise

text - a text for NullPointerException

Returns:

a promise that is smashed in case of null