orc.runtime
Class OrcEngine

java.lang.Object
  orc.runtime.OrcEngine

All Implemented Interfaces:

java.lang.Runnable

public class OrcEngine
extends java.lang.Object
implements java.lang.Runnable

The Orc Engine provides the main loop for executing active tokens. Tokens are always processed in a single thread, but tokens might be activated or resumed from other threads, so some synchronization is necessary.

Author:

wcook, dkitchin, quark, jthywiss

Field Summary

static Globals<OrcEngine,java.lang.Object>

globals

Constructor Summary

OrcEngine(Config config)

Method Summary

void	activate(Token t) Activate a token by adding it to the queue of active tokens
java.lang.String	addGlobal(java.lang.Object value)
java.io.File	createTmpdir() Create a new temporary directory and return the path to that directory.
void	debug(int level, java.lang.String s) Output some debugging information at the given level.
boolean	deleteTmpdir(java.io.File directory) Delete a temporary directory
Config	getConfig()
Execution	getExecution()
boolean	isDead()
Token	newExecution(Expression ex, Token initiator) Create a new toplevel token hosted by this engine.
void	onDebug(java.lang.String s) Override this to change how debugging output is handled.
void	onError(TokenException problem) Handle an error token.
void	onPublish(java.lang.Object v) Handle a published value.
void	onTerminate() Override this to customize termination.
void	pause() Pause execution.
void	print(java.lang.String value, boolean newline) Print something (for use by the print and println sites).
void	publish(java.lang.Object v) Publish a result.
void	reportRound()
void	resume(Token t) Activate a token by adding it to the queue of returning tokens
void	run() Process active nodes, running indefinitely until signalled to stop by a call to terminate().
void	run(Expression root) Run Orc given a root node.
void	scheduleTimer(java.util.TimerTask task, long delay) Schedule a timed task (used by Rtimer).
boolean	shouldDebug(int level) Return true if a debug report at the given level will be used.
void	start(Expression root)
void	terminate() Terminate execution.
void	tokenError(TokenException problem) A token owned by this engine has encountered an exception.
void	unpause() Unpause execution.

Methods inherited from class java.lang.Object

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

Field Detail

globals

public static final Globals<OrcEngine,java.lang.Object> globals

Constructor Detail

OrcEngine

public OrcEngine(Config config)

Method Detail

isDead

public final boolean isDead()

run

public final void run()

Process active nodes, running indefinitely until signalled to stop by a call to terminate(). Typically you will use one of the other run methods to queue an active token to process first.

Specified by:

run in interface java.lang.Runnable

newExecution

public final Token newExecution(Expression ex,
                                Token initiator)

Create a new toplevel token hosted by this engine. Used to implement the Site site. Returns null if the operation could not be performed because a token limit was reached, or because the engine is halted, or due to some other restriction.

Parameters:

ex -

initiator -

Returns:

The token, or null

onTerminate

public void onTerminate()

Override this to customize termination.

terminate

public final void terminate()

Terminate execution.

pause

public final void pause()

Pause execution.

unpause

public final void unpause()

Unpause execution.

run

public final void run(Expression root)

Run Orc given a root node. Creates an initial environment and then executes the main loop. Convenience method for start(root); run();.

Parameters:

root - node to run

start

public final void start(Expression root)

activate

public final void activate(Token t)

Activate a token by adding it to the queue of active tokens

Parameters:

t - the token to be added

resume

public final void resume(Token t)

Activate a token by adding it to the queue of returning tokens

Parameters:

t - the token to be added

publish

public final void publish(java.lang.Object v)

Publish a result. This method is called by the Pub node when a publication is 'escaping' the bottom of the execution graph.

Parameters:

v -

onPublish

public void onPublish(java.lang.Object v)

Handle a published value. The default implementation prints the value's string representation to the console. Change this behavior by extending OrcEngine and overriding this method.

tokenError

public final void tokenError(TokenException problem)

A token owned by this engine has encountered an exception. The token dies, remaining silent and leaving the execution, and then calls this method so that the engine can report or otherwise handle the failure.

onError

public void onError(TokenException problem)

Handle an error token.

shouldDebug

public final boolean shouldDebug(int level)

Return true if a debug report at the given level will be used. Useful if you want to avoid some expensive computation just to generate debug output which will be ignored.

debug

public final void debug(int level,
                        java.lang.String s)

Output some debugging information at the given level. Level 1 is the least verbose (most important information) debugging level, and higher numbers are used for more verbose (less important information).

Parameters:

level -

s -

onDebug

public void onDebug(java.lang.String s)

Override this to change how debugging output is handled.

Parameters:

s -

reportRound

public final void reportRound()

print

public void print(java.lang.String value,
                  boolean newline)

Print something (for use by the print and println sites). By default, this prints to stdout, but this can be overridden to do something else if appropriate.

See Also:

Token.print(String, boolean)

scheduleTimer

public final void scheduleTimer(java.util.TimerTask task,
                                long delay)

Schedule a timed task (used by Rtimer).

addGlobal

public final java.lang.String addGlobal(java.lang.Object value)

getConfig

public final Config getConfig()

getExecution

public final Execution getExecution()

createTmpdir

public final java.io.File createTmpdir()
                                throws java.io.IOException

Create a new temporary directory and return the path to that directory. The directory will be deleted automatically when the engine halts, or you can delete it earlier with deleteTmpdir

Throws:

java.io.IOException

deleteTmpdir

public final boolean deleteTmpdir(java.io.File directory)

Delete a temporary directory