edu.rice.hj.experimental.api

Interface HjEureka<T,C,V>

Type Parameters:

T - the type of the value offered to the Eureka object.

C - the type of the value accepted by the Eureka object while checking.

V - the type of the value returned by the Eureka object.

All Known Subinterfaces:

HjBinaryEureka<L,R>, HjConvergenceEureka<T>, HjCountEureka<T>, HjEngineEureka<T>, HjExtremaEureka<T>, HjSearchEureka<T>, HjTimerEureka<T>, HjVersionEureka<T>

All Known Implementing Classes:

HjBinaryEurekaImpl, HjBinaryEurekaImpl.HjConjunctiveEurekaImpl, HjBinaryEurekaImpl.HjDisjunctiveEurekaImpl, HjConvergenceEurekaImpl, HjCountEurekaImpl, HjEngineEurekaImpl, HjExtremaEurekaImpl, HjFastBarrierEureka, HjFastBarrierEurekaImpl, HjSearchEurekaImpl, HjTimerEurekaImpl, HjVersionEurekaImpl

public interface HjEureka<T,C,V>

Eureka constructs support nondeterminism in applications such as search where a bunch of speculative computations can be aborted as soon as a result (the eureka event) has been found.

A HjEureka wraps a value of type T. A eureka object must be registered on a finish scope. Once a eureka has been resolved, all other asynchronous tasks executing inside the same finish scope may safely be aborted.

Author:

Shams Imam (shams@rice.edu)

Method Summary

Modifier and Type	Method and Description
default boolean	check(C localValue) Checks whether the locally known value can lead to a better estimate than the globally known value.
boolean	check(C localValue, boolean triggerAbort) Checks whether the locally known value can lead to a better estimate than the globally known value.
V	get() Return the value stored in the eureka object.
default boolean	offer(T newValue) Attempts to update the eureka object with a new value.
boolean	offer(T newValue, boolean triggerAbort) Attempts to update the eureka object with a new value.
void	onCleanup() Invoked by the runtime at the end of the finish scope in which the eureka has been registered.
void	onRegistration() Invoked by the runtime at the start of the finish scope in which the eureka has been registered.
boolean	resolved() Return true if the eureka has been resolved.
boolean	shouldAbortOnOffer(boolean offerResult) Return true if the eureka should abort the current task on a successful update.

Method Detail

onRegistration

void onRegistration()

Invoked by the runtime at the start of the finish scope in which the eureka has been registered.

onCleanup

void onCleanup()

Invoked by the runtime at the end of the finish scope in which the eureka has been registered.

resolved

boolean resolved()

Return true if the eureka has been resolved. If there are finish scopes registered on a eureka, all tasks executing under the finish scope are canceled or aborted once the eureka has been resolved.

Returns:

true if the eureka has been resolved.

shouldAbortOnOffer

boolean shouldAbortOnOffer(boolean offerResult)

Return true if the eureka should abort the current task on a successful update.

Parameters:

offerResult - The result of offer() if this method is called from inside the offer() method.

Returns:

true if the eureka should abort the current task on a successful update.

get

V get()

Return the value stored in the eureka object. It can be interpreted as the current 'best' known value.

Returns:

the value stored in the eureka object. If nothing has been set, return the default value with which the eureka object was created.

offer

boolean offer(T newValue,
              boolean triggerAbort)
       throws SuspendableException

Attempts to update the eureka object with a new value.
If shouldAbortOnOffer() returns true and triggerAbort is true, the task will abort instead of returning true.

Parameters:

newValue - The new value to try and update the eureka object with.

triggerAbort - Boolean value that conmfigures whether task is aborted inside this method call.

Returns:

true if the call to offer should trigger task abortion.

Throws:

SuspendableException - Marker to notify that this method is suspendable

offer

default boolean offer(T newValue)
               throws SuspendableException

Attempts to update the eureka object with a new value.
If shouldAbortOnOffer() returns true and triggerAbort is true, the task will abort instead of returning true.

Parameters:

newValue - The new value to try and update the eureka object with.

Returns:

true if the call to offer should trigger task abortion.

Throws:

SuspendableException - Marker to notify that this method is suspendable

check

boolean check(C localValue,
              boolean triggerAbort)
       throws SuspendableException

Checks whether the locally known value can lead to a better estimate than the globally known value. If true, then the method returns normally. If the locally known value is guaranteed to produce a worse result than the globally known value, then the method aborts the current task.

Parameters:

localValue - The local value used to compare with the globally known eureka value

triggerAbort - Boolean value that conmfigures whether task is aborted inside this method call.

Returns:

true if the call to offer should trigger task abortion.

Throws:

SuspendableException - Marker to notify that this method is suspendable

check

default boolean check(C localValue)
               throws SuspendableException

Checks whether the locally known value can lead to a better estimate than the globally known value. If true, then the method returns normally. If the locally known value is guaranteed to produce a worse result than the globally known value, then the method aborts the current task.

Parameters:

localValue - The local value used to compare with the globally known eureka value

Returns:

true if the call to offer should trigger task abortion.

Throws:

SuspendableException - Marker to notify that this method is suspendable