edu.rice.hj.api

Interface HjRuntime

All Known Implementing Classes:

BaseRuntime, ForkJoinRuntime, JavaForkJoinRuntime, SequentialRuntime, SimtRuntime, WorkSharingSimtRuntime, WorkStealingSimtRuntime

public interface HjRuntime

The HjRuntime interface support by all runtime implementations.

Author:

Shams Imam (shams@rice.edu)

Method Summary

Modifier and Type	Method and Description
void	abort() Aborts the currently executing task.
HjMetrics	abstractMetrics() abstractMetrics.
<T> void	asyncAwait(List<HjFuture<T>> dependences, HjRunnable runnable) Will execute the body of the runnable only after the dependences have been satisfied.
void	asyncPhased(List<HjPhaserPair> phaserList, HjSuspendable suspendable) asyncPhased.
void	asyncSeqAt(boolean sequentialize, HjPlace place, HjRunnable runnable) Runs the body of code (possibly) asynchronously at the specified place.
void	asyncSimt(long estimatedWorkInMilliseconds, int maxParallelism, int start, int end, HjSuspendingProcedureInt2D runnable) asyncSimt
void	asyncSuspAt(HjPlace place, HjSuspendable suspendable) Runs the body of code (possibly) asynchronously at the specified place.
<T> void	asyncSuspAwait(List<HjFuture<T>> dependences, HjSuspendable suspendable) Will execute the body of the runnable only after the dependences have been satisfied.
void	asyncWhen(HjExpression.HjAwaitExpression expression, HjRunnable runnable) Mechanism to create an asynchronous task where the await expression is designed to coordinate relationships of this parallel tasks with other tasks (using the HjFuture handles.
<T> void	checkEureka(T eurekaValue)
void	cleanup() Cleans up the runtime in anticipation for shutdown.
Object	currentActivity() Returns The currently executing activity.
HjPlace	currentPlace()
void	doWait() Perform the wait operation on all registered phasers in an activity.
void	doWork(long n) Registers n units of work against the currently running activity.
void	dumpEventLog(PrintStream printStream) Dumps the events tracked by the runtime.
void	emergencyShutdown(Throwable cause) Shutdown the runtime, this means also shutting down all places associated with this runtime and all currently executing activities.
void	finish(HjEureka<?,?,?> hjEureka, HjSuspendable suspendable) Registers a HjEureka with the finish scope and continues to execute the body of the finish scope.
void	finish(HjSuspendable suspendable) Runs the body of code in a finish block.
void	finish(List<HjFinishAccumulator> accumulators, HjSuspendable suspendable) finish.
<T,V> HjFuture<V>	futureAwait(List<HjFuture<T>> dependencies, HjCallable<V> callable) Equivalent of asyncAwait(java.util.List, HjRunnable) which returns a futureNb.
<V> HjFuture<V>	futureSeq(boolean sequentialize, HjCallable<V> callable) Creates an asynchronous task and returns the futureNb object representing the value of the computation.
<V> HjFuture<V>	futureSusp(HjSuspendingCallable<V> callable) Creates an asynchronous task and returns the futureNb object representing the value of the computation.
<T,V> HjFuture<V>	futureSuspAwait(List<HjFuture<T>> dependencies, HjSuspendingCallable<V> callable) Equivalent of asyncAwait(java.util.List, HjRunnable) which returns a future.
<V> HjFuture<V>	futureWhen(HjExpression.HjAwaitExpression expression, HjCallable<V> callable) Mechanism to create an asynchronous task where the await expression is designed to coordinate relationships of this parallel tasks with other tasks (using the HjFuture handles.
void	initialize() Initializes the runtime.
void	isolated(HjRunnable runnable) isolated.
void	isolated(Object[] participants, HjRunnable runnable) Isolated statement identifies a critical section.
void	isolated(Object participant, HjRunnable runnable) Isolated statement identifies a critical section.
<V> V	isolatedWithReturn(HjCallable<V> callable) isolatedWithReturn.
<V> V	isolatedWithReturn(Object[] participants, HjCallable<V> callable) isolatedWithReturn.
<V> V	isolatedWithReturn(Object participant, HjCallable<V> callable) isolatedWithReturn.
<L,R> HjBinaryEureka<L,R>	newBinaryEureka(HjLogicalOperator operator, HjEureka<L,Object,L> leftEureka, HjEureka<R,Object,R> rightEureka) Factory method to create a new HjBinaryEureka instance.
<T> HjConvergenceEureka<T>	newConvergenceEureka(T initialValue, java.util.function.BiPredicate<T,T> checker, HjProcedure<T> convergenceCallback) Factory method to create a new HjConvergenceEureka instance.
<T> HjCountEureka<T>	newCountEureka(long maxCount, int spaceForResult) Factory method to create a new HjCountEureka instance.
<V> HjDataDrivenFuture<V>	newDataDrivenFuture(boolean allowDuplicatePuts) Factory method for a DataDrivenFuture.
<T> HjEngineEureka<T>	newEngineEureka(int maxUnits) Factory method to create a new HjEngineEureka instance.
HjEventCount	newEventCount(int initialCount) Returns a new instance of an HjEventCount.
<T> HjExtremaEureka<T>	newExtremaEureka(T initialValue, Comparator<T> comparator, boolean shouldAbortOnOffer) Factory method to create a new HjExtremaEureka instance.
HjFastBarrierEureka	newFastBarrierEureka(int numPhases) Factory method to create a new HjFastBarrierEureka instance.
HjFinishAccumulator	newFinishAccumulator(HjOperator ope, Class type) newFinishAccumulator.
HjPhaser	newPhaser(HjPhaserMode phaserMode, int busyWaitLimit) Create a new phaser in the specified registration mode..
<T> HjSearchEureka<T>	newSearchEureka(T initialValue) Factory method to create a new HjSearchEureka instance.
<T> HjTimerEureka<T>	newTimerEureka(int timeUnitsInMillis) Factory method to create a new HjTimerEureka instance.
<T> HjVersionEureka<T>	newVersionEureka(int n) Factory method to create a new HjVersionEureka instance.
void	next() Perform the next operation on all registered phasers in an activity.
int	numWorkerThreads() Returns the number of worker threads employed by the runtime for the current place.
<T> void	offerEureka(T eurekaValue)
<T> T	readEureka() Return the current value stored on the registered eureka.
Object	readMode(Object wrappee) readMode.
<T> HjEureka<T,T,T>	retrieveEureka() Return the eureka to be registered in the finish scope.
HjEventLogger	retrieveEventLogger() Retrieves the HjEventLogger used by the runtime.
void	runKernel(HjSuspendable suspendable) Entry of the user's program body into the Habanero runtime.
void	scheduleActivity(HjPlace hjPlace, Runnable runnable) Schedules an activity whose body is represented by the Runnable instance.
void	scheduleActivity(Runnable runnable) Schedules an activity whose body is represented by the Runnable instance.
void	signal() Perform the signal operation on all registered phasers in an activity.
Object	writeMode(Object wrappee) writeMode.

Method Detail

initialize

void initialize()

Initializes the runtime.

cleanup

void cleanup()

Cleans up the runtime in anticipation for shutdown.

runKernel

void runKernel(HjSuspendable suspendable)

Entry of the user's program body into the Habanero runtime.

Parameters:

suspendable - The body of the kernel

currentActivity

Object currentActivity()

Returns The currently executing activity.

Returns:

The currently executing activity.

scheduleActivity

void scheduleActivity(Runnable runnable)

Schedules an activity whose body is represented by the Runnable instance.

Parameters:

runnable - The runnable activity to schedule.

scheduleActivity

void scheduleActivity(HjPlace hjPlace,
                      Runnable runnable)

Schedules an activity whose body is represented by the Runnable instance.

Parameters:

hjPlace - The place at which to schedule this activity.

runnable - The runnable activity to schedule.

numWorkerThreads

int numWorkerThreads()

Returns the number of worker threads employed by the runtime for the current place.

Returns:

the number of worker threads employed by the runtime for the current place.

currentPlace

HjPlace currentPlace()

Returns:

the current place of execution

finish

void finish(HjSuspendable suspendable)
     throws SuspendableException

Runs the body of code in a finish block.

Parameters:

suspendable - The body of the code to run wrapped in a finish block.

Throws:

SuspendableException

asyncSeqAt

void asyncSeqAt(boolean sequentialize,
                HjPlace place,
                HjRunnable runnable)

Runs the body of code (possibly) asynchronously at the specified place.

Parameters:

sequentialize - The flag that determines whether the runtime should consider running the body asynchronously.

place - The place where the async task should run. This parameter may be ignored if the task is to be run sequentially.

runnable - The body of the code to run, possibly asynchronously.

asyncSuspAt

void asyncSuspAt(HjPlace place,
                 HjSuspendable suspendable)

Runs the body of code (possibly) asynchronously at the specified place.

Parameters:

place - The place where the async task should run. This parameter may be ignored if the task is to be run sequentially.

suspendable - The body of the code to run, possibly asynchronously. The body of the code possibly contains a suspendable condition.

futureSeq

<V> HjFuture<V> futureSeq(boolean sequentialize,
                          HjCallable<V> callable)

Creates an asynchronous task and returns the futureNb object representing the value of the computation. Run the body of code (a)synchronously based on boolean parameter.

Type Parameters:

V - The return type of the body.

Parameters:

sequentialize - The flag that determines whether the runtime should consider running the body asynchronously.

callable - The body of the callable to run, possibly asynchronously.

Returns:

The futureNb object representing the value of the computation.

futureSusp

<V> HjFuture<V> futureSusp(HjSuspendingCallable<V> callable)

Creates an asynchronous task and returns the futureNb object representing the value of the computation. Run the body of code (a)synchronously based on boolean parameter.

Type Parameters:

V - The return type of the body.

Parameters:

callable - The body of the callable to run, possibly asynchronously.

Returns:

The futureNb object representing the value of the computation.

futureAwait

<T,V> HjFuture<V> futureAwait(List<HjFuture<T>> dependencies,
                              HjCallable<V> callable)

Equivalent of asyncAwait(java.util.List, HjRunnable) which returns a futureNb.

Type Parameters:

V - The return type of the body.

Parameters:

dependencies - The data dependencies of the asynchronous task

callable - The body of the callable to run, possibly asynchronously.

Returns:

The futureNb object representing the value of the computation.

futureSuspAwait

<T,V> HjFuture<V> futureSuspAwait(List<HjFuture<T>> dependencies,
                                  HjSuspendingCallable<V> callable)

Equivalent of asyncAwait(java.util.List, HjRunnable) which returns a future.

Type Parameters:

V - The return type of the body.

Parameters:

dependencies - The data dependencies of the asynchronous task

callable - The body of the callable to run, possibly asynchronously.

Returns:

The futureNb object representing the value of the computation.

newDataDrivenFuture

<V> HjDataDrivenFuture<V> newDataDrivenFuture(boolean allowDuplicatePuts)

Factory method for a DataDrivenFuture.

Type Parameters:

V - The type of the data wrapped in the DDF.

Returns:

a new instance of a HjDataDrivenFuture

asyncAwait

<T> void asyncAwait(List<HjFuture<T>> dependences,
                    HjRunnable runnable)

Will execute the body of the runnable only after the dependences have been satisfied.

Parameters:

dependences - The data dependencies of the asynchronous task

runnable - The body of the code to run, possibly asynchronously.

asyncSuspAwait

<T> void asyncSuspAwait(List<HjFuture<T>> dependences,
                        HjSuspendable suspendable)

Will execute the body of the runnable only after the dependences have been satisfied.

Parameters:

dependences - The data dependencies of the asynchronous task

suspendable - The body of the code to run, possibly asynchronously.

isolated

void isolated(HjRunnable runnable)

isolated.

Parameters:

runnable - The body of the code to run using weak isolation.

isolated

void isolated(Object participant,
              HjRunnable runnable)

Isolated statement identifies a critical section. Two tasks executing isolated statements must perform them in mutual exclusion.

Parameters:

participant - The object involved in the atomic block.

runnable - The body of the code to run using weak isolation.

isolated

void isolated(Object[] participants,
              HjRunnable runnable)

Isolated statement identifies a critical section. Two tasks executing isolated statements must perform them in mutual exclusion.

Parameters:

participants - The objects involved in the atomic block.

runnable - The body of the code to run using weak isolation.

isolatedWithReturn

<V> V isolatedWithReturn(HjCallable<V> callable)

isolatedWithReturn.

Type Parameters:

V - a V object.

Parameters:

callable - The body of the code to run using weak isolation.

Returns:

a V object.

isolatedWithReturn

<V> V isolatedWithReturn(Object participant,
                         HjCallable<V> callable)

isolatedWithReturn.

Type Parameters:

V - a V object.

Parameters:

participant - The object involved in the atomic block.

callable - The body of the code to run using weak isolation.

Returns:

a V object.

isolatedWithReturn

<V> V isolatedWithReturn(Object[] participants,
                         HjCallable<V> callable)

isolatedWithReturn.

Type Parameters:

V - a V object.

Parameters:

participants - The objects involved in the atomic block.

callable - The body of the code to run using weak isolation.

Returns:

a V object.

readMode

Object readMode(Object wrappee)

readMode.

Parameters:

wrappee - The Object whose mode to control

Returns:

a wrapper to represent read mode for isolated statement.

writeMode

Object writeMode(Object wrappee)

writeMode.

Parameters:

wrappee - The Object whose mode to control

Returns:

a wrapper to represent write mode for isolated statement.

newFinishAccumulator

HjFinishAccumulator newFinishAccumulator(HjOperator ope,
                                         Class type)

newFinishAccumulator.

Parameters:

ope - The type of the HjOperator

type - The result type

Returns:

a new FinishAccumulator instance

finish

void finish(List<HjFinishAccumulator> accumulators,
            HjSuspendable suspendable)
     throws SuspendableException

finish.

Parameters:

accumulators - The accumulators registered on the finish.

suspendable - The body of the code to run wrapped in a finish block.

Throws:

SuspendableException

newPhaser

HjPhaser newPhaser(HjPhaserMode phaserMode,
                   int busyWaitLimit)

Create a new phaser in the specified registration mode..

Parameters:

phaserMode - The phaser registration mode.

busyWaitLimit - The number of times to iterate in a busy wait loop before blocking

Returns:

a newly allocated phaser.

asyncPhased

void asyncPhased(List<HjPhaserPair> phaserList,
                 HjSuspendable suspendable)

asyncPhased.

Parameters:

phaserList - The list of phasers the async is registered on.

suspendable - The body of the code to run, possibly asynchronously.

next

void next()
   throws SuspendableException

Perform the next operation on all registered phasers in an activity.

Throws:

SuspendableException

signal

void signal()

Perform the signal operation on all registered phasers in an activity.

doWait

void doWait()
     throws SuspendableException

Perform the wait operation on all registered phasers in an activity.

Throws:

SuspendableException

emergencyShutdown

void emergencyShutdown(Throwable cause)

Shutdown the runtime, this means also shutting down all places associated with this runtime and all currently executing activities.

Parameters:

cause - The exception causing the shutdown.

doWork

void doWork(long n)

Registers n units of work against the currently running activity.

Parameters:

n - units of work done

abstractMetrics

HjMetrics abstractMetrics()

abstractMetrics.

Returns:

The abstract metrics associated with the current HJ instance

retrieveEventLogger

HjEventLogger retrieveEventLogger()

Retrieves the HjEventLogger used by the runtime.

Returns:

the HjEventLogger used by the runtime.

dumpEventLog

void dumpEventLog(PrintStream printStream)

Dumps the events tracked by the runtime.

Parameters:

printStream - The stream to use while dumping the events.

asyncWhen

void asyncWhen(HjExpression.HjAwaitExpression expression,
               HjRunnable runnable)

Mechanism to create an asynchronous task where the await expression is designed to coordinate relationships of this parallel tasks with other tasks (using the HjFuture handles.

The body of this async is only executed when the expression evaluates to true, the expression can only be safely evaluated after all the futures involved in the expression have been resolved when in strict mode (expression contains a NOT). There is also a short-circuit mode (expression contains only AND and OR) where the expression is evaluated early and the asynchronous computation triggered even when some of the other dependent tasks may not yet have completed execution.

The semantics of

   asyncWhen(awaitExpr, () -> S1)
 

are as follows:

   async(() -> {
     boolean exprVal = expr.evaluate();
     if (exprVal) {
       S1;
     }
   });
 

Parameters:

expression - The expression that controls when the async is ready for execution.

runnable - The body of the async.

futureWhen

<V> HjFuture<V> futureWhen(HjExpression.HjAwaitExpression expression,
                           HjCallable<V> callable)

Mechanism to create an asynchronous task where the await expression is designed to coordinate relationships of this parallel tasks with other tasks (using the HjFuture handles. Also returns the futureNb object representing the value of the computation.

The body of this async is only executed when the expression evaluates to true, the expression can only be safely evaluated after all the futures involved in the expression have been resolved when in strict mode (expression contains a NOT). There is also a short-circuit mode (expression contains only AND and OR) where the expression is evaluated early and the asynchronous computation triggered even when some of the other dependent tasks may not yet have completed execution.

The semantics of

   futureWhen(awaitExpr, () -> S1)
 

are as follows:

   futureNb(() -> {
     boolean exprVal = expr.evaluate();
     if (exprVal) {
       S1;
     } else {
       throw new RuntimeException("clause failed!");
     }
   });
 

Parameters:

expression - The expression that controls when the async is ready for execution.

callable - The body of the async.

Returns:

The futureNb object representing the value of the computation.

finish

void finish(HjEureka<?,?,?> hjEureka,
            HjSuspendable suspendable)
     throws SuspendableException

Registers a HjEureka with the finish scope and continues to execute the body of the finish scope.

Parameters:

hjEureka - the eureka to be registered

suspendable - the body of the finish scope

Throws:

SuspendableException

newSearchEureka

<T> HjSearchEureka<T> newSearchEureka(T initialValue)

Factory method to create a new HjSearchEureka instance.

Parameters:

initialValue - The initial value of the search eureka object

Returns:

A new HjSearchEureka instance

newExtremaEureka

<T> HjExtremaEureka<T> newExtremaEureka(T initialValue,
                                        Comparator<T> comparator,
                                        boolean shouldAbortOnOffer)

Factory method to create a new HjExtremaEureka instance.

Parameters:

initialValue - The initial value of the extrema, it should be smaller than expected result.

comparator - The comparator used to maximize the extrema value. The first argument of the comparator is the existing value in the eureka, and the second argument is the new argument passed inside the call to offer and check.

shouldAbortOnOffer - Whether a successful offer should abort the current task

Returns:

a new HjExtremaEureka instance.

newConvergenceEureka

<T> HjConvergenceEureka<T> newConvergenceEureka(T initialValue,
                                                java.util.function.BiPredicate<T,T> checker,
                                                HjProcedure<T> convergenceCallback)

Factory method to create a new HjConvergenceEureka instance.

Parameters:

initialValue - The initial value of the eureka.

checker - The predicate used to check for convergence.

convergenceCallback - A callback invoked once the eureka has converged.

Returns:

a new HjConvergenceEureka instance.

newFastBarrierEureka

HjFastBarrierEureka newFastBarrierEureka(int numPhases)

Factory method to create a new HjFastBarrierEureka instance.

Parameters:

numPhases - The number of phases in the fast barrier.

Returns:

a new HjFastBarrierEureka instance.

newCountEureka

<T> HjCountEureka<T> newCountEureka(long maxCount,
                                    int spaceForResult)

Factory method to create a new HjCountEureka instance.

Parameters:

maxCount - The maximum number of eureka events before the eureka is resolved.

spaceForResult - The maximum number of results to store in the eureka.

Returns:

a new HjCountEureka instance.

newVersionEureka

<T> HjVersionEureka<T> newVersionEureka(int n)

Factory method to create a new HjVersionEureka instance.

Parameters:

n - The number of items that need to match before the eureka is resolved.

Returns:

a new HjVersionEureka instance.

See Also:

newVersionEureka(int)

newEngineEureka

<T> HjEngineEureka<T> newEngineEureka(int maxUnits)

Factory method to create a new HjEngineEureka instance.

Parameters:

maxUnits - The maximum number of time units in the eureka.

Returns:

a new HjEngineEureka instance.

newTimerEureka

<T> HjTimerEureka<T> newTimerEureka(int timeUnitsInMillis)

Factory method to create a new HjTimerEureka instance.

Parameters:

timeUnitsInMillis - The maximum number of milliseconds before the eureka is considered resolved.

Returns:

a new HjTimerEureka instance.

newBinaryEureka

<L,R> HjBinaryEureka<L,R> newBinaryEureka(HjLogicalOperator operator,
                                          HjEureka<L,Object,L> leftEureka,
                                          HjEureka<R,Object,R> rightEureka)

Factory method to create a new HjBinaryEureka instance.

Parameters:

operator - The maximum number of milliseconds before the eureka is considered resolved.

leftEureka - The left eureka instance.

rightEureka - The right eureka instance.

Returns:

a new HjTimerEureka instance.

retrieveEureka

<T> HjEureka<T,T,T> retrieveEureka()

Return the eureka to be registered in the finish scope.

Type Parameters:

T - The type of value stored in the Eureka

Returns:

the eureka to be registered in the finish scope.

offerEureka

<T> void offerEureka(T eurekaValue)
              throws SuspendableException

Type Parameters:

T - The type of value stored in the Eureka

Parameters:

eurekaValue - The value to be associated with the eureka

Throws:

SuspendableException

checkEureka

<T> void checkEureka(T eurekaValue)
              throws SuspendableException

Type Parameters:

T - The type of value stored in the Eureka

Parameters:

eurekaValue - The value to be associated with the eureka

Throws:

SuspendableException

readEureka

<T> T readEureka()

Return the current value stored on the registered eureka.

Type Parameters:

T - The type of value stored in the Eureka

Returns:

the current value stored on the registered eureka.

abort

void abort()
    throws SuspendableException

Aborts the currently executing task.

Throws:

SuspendableException

asyncSimt

void asyncSimt(long estimatedWorkInMilliseconds,
               int maxParallelism,
               int start,
               int end,
               HjSuspendingProcedureInt2D runnable)

asyncSimt

Parameters:

estimatedWorkInMilliseconds - Amount of sequential work in ms estimated for this task

maxParallelism - Amount of parallelism present in the task (assumes linear speedup)

start - Start of range of iterations

end - End of range of iterations

runnable - Body of the async

newEventCount

HjEventCount newEventCount(int initialCount)

Returns a new instance of an HjEventCount.

Returns:

a new instance of an HjEventCount