jist.runtime
Class Controller

java.lang.Object
  jist.runtime.Controller

All Implemented Interfaces:

java.lang.Runnable, java.rmi.Remote, ControllerRemote

public final class Controller
extends java.lang.Object
implements ControllerRemote, java.lang.Runnable

Maintains all the data structures of a single simulation thread of execution. The Controller also contains the implementation of static callbacks from the simulation application to the JiST system.

Since:

JIST1.0

Field Summary

static Controller	activeController Active controller, iff controllerCount==1.
Event.ContinuationFrame	callbackState Incoming callback state for returning (blocking) call event.
Event.ContinuationFrame	callState Outgoing callback state for (blocking) call event.
Event	currentCaller Incoming caller information for returning (blocking) call event.
BlockingSleep	entityBlockingSleep Blocking sleep singleton entity.
static GuiLog	guilog GUI logger.
static org.apache.log4j.Logger	log Controller logger.
static java.lang.reflect.Method	method_entityInvocation Method stub for callback to invoke a method on an entity.
static java.lang.reflect.Method	method_entityInvocationCont Method stub for callback to invoke a method on an entity, with continuation -- a blocking call.
static java.lang.reflect.Method	method_getEntityReference Method stub for callback to get an entity references for an entity.
static java.lang.reflect.Method	method_getTHIS Method stub for callback to return the current active entity.
static java.lang.reflect.Method	method_isModeRestore Method stub for callback to determine whether current event invocation is in restore mode.
static java.lang.reflect.Method	method_isModeSave Method stub for callback to determine whether current event invocation is in save mode.
static java.lang.reflect.Method	method_newEntityReference Method stub for callback to register an new entity, creating an entity reference.
static java.lang.reflect.Method	method_popStateInFrame Return next frame of incoming event continuation state.
static java.lang.reflect.Method	method_pushStateOutFrame Store next frame of outgoing event continuation state.

Method Summary

void	addEvent(Event ev) Insert event in into event queue.
void	addEvent(java.lang.reflect.Method meth, EntityRef ref, java.lang.Object[] params) Insert event in into event queue (performance: avoids need to get controller instance to create event - shaves off around 10%).
void	addEvent(java.lang.reflect.Method meth, EntityRef ref, java.lang.Object[] params, long time) Insert event in into event queue (performance: avoids need to get controller instance to create event - shaves off around 10%).
void	advanceSimulationTime(long i) Advance the current simulation time.
java.lang.Object	clearRestoreState() Clear restore state of current event, and callback result.
void	disposeEvent(Event ev) Dispose event into the event pool, and clear any references in the event object to allow for GC.
void	endAt(long time) End simulation after given time-step.
static void	entityInvocation(java.lang.reflect.Method meth, Entity entity, java.lang.Object[] params) Application callback method to perform (intercept) an entity method invocation at the appropriate simulation time.
static void	entityInvocation(java.lang.reflect.Method meth, EntityRef ref, java.lang.Object[] params) Application callback method to perform (intercept) an entity method invocation at the appropriate simulation time.
static void	entityInvocation(java.lang.reflect.Method meth, java.lang.Object callee, java.lang.Object[] params) Application callback method to perform (intercept) an entity method invocation at the appropriate simulation time.
static java.lang.Object	entityInvocationCont(java.lang.reflect.Method meth, Entity entity, java.lang.Object[] params) Application callback method to perform (intercept) a BLOCKING entity method invocation at the appropriate simulation time.
static java.lang.Object	entityInvocationCont(java.lang.reflect.Method meth, EntityRef ref, java.lang.Object[] params) Application callback method to perform (intercept) a BLOCKING entity method invocation at the appropriate simulation time.
static java.lang.Object	entityInvocationCont(java.lang.reflect.Method meth, java.lang.Object callee, java.lang.Object[] params) Application callback method to perform (intercept) a BLOCKING entity method invocation at the appropriate simulation time.
static Controller	getActiveController() Return active controller instance.
java.lang.ClassLoader	getClassLoader() Return class loader used by this Controller instance.
Event	getCurrentEvent() Return event currently being processed.
Entity	getEntity(int index) Return an entity owned by this Controller.
java.lang.Class	getEntityClass(int index) Return type of specific entity at this Controller.
static EntityRef	getEntityReference(java.lang.Object o) Application callback method to return the entity reference for a given object.
long	getSimulationTime() Get current simulation time.
java.lang.String	getSimulationTimeString() Return time string in simulation time units.
long	getStartTime() Return the simulation starting time.
EntityRef	getStaticEntityRef() Return the entity reference to the "static" entity.
static EntityRef	getTHIS() Return current entity.
static boolean	isModeRestore() Return whether the event invocation is currently in restore mode.
boolean	isModeRestoreInst() Return whether the event invocation is currently in restore mode.
static boolean	isModeSave() Return whether the event invocation is currently in save mode.
boolean	isModeSaveInst() Return whether the event invocation is currently in save mode.
boolean	isRunning() Return whether the simulation controller is running.
void	join() Wait for simulation to finish.
void	log(java.lang.String s) Emit message in JisT log.
static Controller	newController(java.lang.ClassLoader loader) Create and initialize a new Controller instance.
static EntityRef	newEntityReference(Entity entity) Application callback method to register an new entity, creating an entity reference.
static Event.ContinuationFrame	popStateInFrame() Pop a frame from the incoming execution stack.
static void	pushStateOutFrame(Event.ContinuationFrame f) Push a frame onto the outgoing execution stack.
void	registerCallEvent(java.lang.reflect.Method method, EntityRef ref, java.lang.Object[] args) Create and register an outgoing call event.
EntityRef	registerEntity(Entity entity) Register an entity with the Controller.
java.lang.Throwable	reset() Create internal event queue and entity list.
void	run() Begin execution of simulation events.
void	setClassLoader(java.lang.ClassLoader loader) Set the Controller class loader (rewriter).
void	setLog(java.lang.Class loggerClass) Set logging implementation.
void	setLog(JistAPI.Logger logger) Set logging implementation.
void	setSimUnits(long ticks, java.lang.String name) Set the simulation time units.
void	start() Start the Controller processing thread with given rewriter instance.
java.lang.Thread	startDisplayThread() Start thread to display status of simulation every so often.
Event	switchCaller(Event caller) Switch caller (return) event.
static java.lang.String	toString(java.lang.Object o) String of given object or entity.
java.lang.String	toStringEntity(int index) Return string of entity at given index.

Methods inherited from class java.lang.Object

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

Field Detail

method_getTHIS

public static final java.lang.reflect.Method method_getTHIS

Method stub for callback to return the current active entity.

method_newEntityReference

public static final java.lang.reflect.Method method_newEntityReference

Method stub for callback to register an new entity, creating an entity reference.

method_getEntityReference

public static final java.lang.reflect.Method method_getEntityReference

Method stub for callback to get an entity references for an entity.

method_entityInvocation

public static final java.lang.reflect.Method method_entityInvocation

Method stub for callback to invoke a method on an entity.

method_entityInvocationCont

public static final java.lang.reflect.Method method_entityInvocationCont

Method stub for callback to invoke a method on an entity, with continuation -- a blocking call.

method_popStateInFrame

public static final java.lang.reflect.Method method_popStateInFrame

Return next frame of incoming event continuation state.

method_pushStateOutFrame

public static final java.lang.reflect.Method method_pushStateOutFrame

Store next frame of outgoing event continuation state.

method_isModeRestore

public static final java.lang.reflect.Method method_isModeRestore

Method stub for callback to determine whether current event invocation is in restore mode.

method_isModeSave

public static final java.lang.reflect.Method method_isModeSave

Method stub for callback to determine whether current event invocation is in save mode.

activeController

public static final Controller activeController

Active controller, iff controllerCount==1.

log

public static final org.apache.log4j.Logger log

Controller logger.

guilog

public static final GuiLog guilog

GUI logger.

callState

public Event.ContinuationFrame callState

Outgoing callback state for (blocking) call event.

callbackState

public Event.ContinuationFrame callbackState

Incoming callback state for returning (blocking) call event.

currentCaller

public Event currentCaller

Incoming caller information for returning (blocking) call event.

entityBlockingSleep

public BlockingSleep entityBlockingSleep

Blocking sleep singleton entity.

Method Detail

newController

public static Controller newController(java.lang.ClassLoader loader)
                                throws java.rmi.RemoteException

Create and initialize a new Controller instance. May return a single controller, if JiST is SINGLE_CONTROLLER mode.

Parameters:

loader - class loader (rewriter) to use

Returns:

Controller instance

Throws:

java.rmi.RemoteException - distributed simulation failure

See Also:

Main.SINGLE_CONTROLLER

reset

public java.lang.Throwable reset()

Create internal event queue and entity list.

Returns:

any unhandled (non-application) exception (such as VirtualMachineError) thrown by previous simulation run

isRunning

public boolean isRunning()

Return whether the simulation controller is running.

Returns:

whether the simulation controller is running

getStartTime

public long getStartTime()

Return the simulation starting time.

Returns:

the simulation starting time

run

public void run()

Begin execution of simulation events. This method will exit when there are no more events to process, or when the simulation time limit is reached, whichever comes first.

Specified by:

run in interface java.lang.Runnable

startDisplayThread

public java.lang.Thread startDisplayThread()

Start thread to display status of simulation every so often.

Returns:

display thread

start

public void start()

Start the Controller processing thread with given rewriter instance. The thread will die when there are no more events to process, or simulation time limit is reached, whichever comes first.

Specified by:

start in interface ControllerRemote

join

public void join()
          throws java.lang.InterruptedException

Wait for simulation to finish.

Throws:

java.lang.InterruptedException - interrupted simulation thread

getCurrentEvent

public Event getCurrentEvent()

Return event currently being processed.

Returns:

event currently being processed

registerCallEvent

public void registerCallEvent(java.lang.reflect.Method method,
                              EntityRef ref,
                              java.lang.Object[] args)

Create and register an outgoing call event. This event will be kept by the active Controller until the state saving is complete, and then scheduled (back in the processing loop).

Parameters:

method - invocation method for event

ref - invocation entity reference for event

args - invocation parameters for event

disposeEvent

public void disposeEvent(Event ev)

Dispose event into the event pool, and clear any references in the event object to allow for GC.

Parameters:

ev - event instance to dispose

addEvent

public void addEvent(Event ev)

Insert event in into event queue.

Specified by:

addEvent in interface ControllerRemote

Parameters:

ev - event to schedule

addEvent

public void addEvent(java.lang.reflect.Method meth,
                     EntityRef ref,
                     java.lang.Object[] params)

Insert event in into event queue (performance: avoids need to get controller instance to create event - shaves off around 10%).

Specified by:

addEvent in interface ControllerRemote

Parameters:

meth - method of event to schedule

ref - entity reference of event to schedule

params - parameters of event to schedule

addEvent

public void addEvent(java.lang.reflect.Method meth,
                     EntityRef ref,
                     java.lang.Object[] params,
                     long time)

Insert event in into event queue (performance: avoids need to get controller instance to create event - shaves off around 10%).

Specified by:

addEvent in interface ControllerRemote

Parameters:

meth - method of event to schedule

ref - entity reference of event to schedule

params - parameters of event to schedule

time - event invocation time

getSimulationTime

public long getSimulationTime()

Get current simulation time. The simulation time is the base simulation time of the current event, plus all the sleeps incurred during processing.

Returns:

current simulation time

getSimulationTimeString

public java.lang.String getSimulationTimeString()

Return time string in simulation time units.

Returns:

time string in simulation time units

advanceSimulationTime

public void advanceSimulationTime(long i)

Advance the current simulation time.

Parameters:

i - number of steps to advance simulation time

endAt

public void endAt(long time)

End simulation after given time-step.

Specified by:

endAt in interface ControllerRemote

Parameters:

time - simulation time to end

setSimUnits

public void setSimUnits(long ticks,
                        java.lang.String name)

Set the simulation time units.

Specified by:

setSimUnits in interface ControllerRemote

Parameters:

ticks - number of simulation quanta

name - unit of time name

registerEntity

public EntityRef registerEntity(Entity entity)

Register an entity with the Controller.

Parameters:

entity - entity to register with current controller

Returns:

entity reference to given entity

getEntity

public Entity getEntity(int index)

Return an entity owned by this Controller.

Parameters:

index - local entity identifier

Returns:

requested entity object

getEntityClass

public java.lang.Class getEntityClass(int index)
                               throws java.rmi.RemoteException

Return type of specific entity at this Controller.

Specified by:

getEntityClass in interface ControllerRemote

Parameters:

index - local entity identifier

Returns:

request entity object type

Throws:

java.rmi.RemoteException - rpc failure

getStaticEntityRef

public EntityRef getStaticEntityRef()

Return the entity reference to the "static" entity.

Returns:

entity reference of the static entity

toStringEntity

public java.lang.String toStringEntity(int index)
                                throws java.rmi.RemoteException

Return string of entity at given index.

Specified by:

toStringEntity in interface ControllerRemote

Parameters:

index - entity id

Returns:

string of entity at given index

Throws:

java.rmi.RemoteException - distributed simulation failure

toString

public static java.lang.String toString(java.lang.Object o)
                                 throws java.rmi.RemoteException

String of given object or entity.

Parameters:

o - object or entity to stringify

Returns:

string of given object to stringify

Throws:

java.rmi.RemoteException - distributed simulation failure

getActiveController

public static Controller getActiveController()

Return active controller instance. This is the controller instance from the controller slot of the thread group of the current thread.

Returns:

active Controller instance

getClassLoader

public java.lang.ClassLoader getClassLoader()

Return class loader used by this Controller instance.

Returns:

class loader used by this Controller instance.

setClassLoader

public void setClassLoader(java.lang.ClassLoader loader)

Set the Controller class loader (rewriter).

Parameters:

loader - class loader / rewriter for controller

getTHIS

public static EntityRef getTHIS()

Return current entity.

Returns:

current entity

newEntityReference

public static EntityRef newEntityReference(Entity entity)

Application callback method to register an new entity, creating an entity reference.

Parameters:

entity - newly created entity to be registered

Returns:

new entity reference to give entity

getEntityReference

public static EntityRef getEntityReference(java.lang.Object o)

Application callback method to return the entity reference for a given object. If an Entity is provided, then the corresponding EntityRef is returned. Otherwise, an EntityRef is assumed, and returned verbatim.

Parameters:

o - object of either Entity or EntityRef type

Returns:

EntityRef of given object

entityInvocation

public static void entityInvocation(java.lang.reflect.Method meth,
                                    EntityRef ref,
                                    java.lang.Object[] params)

Application callback method to perform (intercept) an entity method invocation at the appropriate simulation time.

Parameters:

meth - method to be invoked

ref - reference to entity being invoked

params - invocation parameters

entityInvocation

public static void entityInvocation(java.lang.reflect.Method meth,
                                    Entity entity,
                                    java.lang.Object[] params)

Application callback method to perform (intercept) an entity method invocation at the appropriate simulation time.

Parameters:

meth - method to be invoked

entity - entity to be invoked

params - invocation parameters

entityInvocation

public static void entityInvocation(java.lang.reflect.Method meth,
                                    java.lang.Object callee,
                                    java.lang.Object[] params)

Application callback method to perform (intercept) an entity method invocation at the appropriate simulation time.

Parameters:

meth - method to be invoked

callee - object (either entity or entityreference) to be invoked

params - invocation parameters

entityInvocationCont

public static java.lang.Object entityInvocationCont(java.lang.reflect.Method meth,
                                                    EntityRef ref,
                                                    java.lang.Object[] params)
                                             throws JistAPI.Continuation,
                                                    java.lang.Throwable

Application callback method to perform (intercept) a BLOCKING entity method invocation at the appropriate simulation time. This method will be called once when the blocking call is initiated, and once when the callback is restoring its state. This ping-pong is necessary to capture the execution stack -- no other way in pure Java.

Parameters:

meth - method to be invoked

ref - reference to entity being invoked

params - invocation parameters

Returns:

whatever was returned by blocking event

Throws:

JistAPI.Continuation - never (marker for rewriter)

java.lang.Throwable - whatever was thrown by blocking event

entityInvocationCont

public static java.lang.Object entityInvocationCont(java.lang.reflect.Method meth,
                                                    Entity entity,
                                                    java.lang.Object[] params)
                                             throws JistAPI.Continuation,
                                                    java.lang.Throwable

Application callback method to perform (intercept) a BLOCKING entity method invocation at the appropriate simulation time. This method will be called once when the blocking call is initiated, and once when the callback is restoring its state. This ping-pong is necessary to capture the execution stack -- no other way in pure Java.

Parameters:

meth - method to be invoked

entity - entity to be invoked

params - invocation parameters

Returns:

whatever was returned by blocking event

Throws:

JistAPI.Continuation - never (marker for rewriter)

java.lang.Throwable - whatever was thrown by blocking event

entityInvocationCont

public static java.lang.Object entityInvocationCont(java.lang.reflect.Method meth,
                                                    java.lang.Object callee,
                                                    java.lang.Object[] params)
                                             throws JistAPI.Continuation,
                                                    java.lang.Throwable

Application callback method to perform (intercept) a BLOCKING entity method invocation at the appropriate simulation time. This method will be called once when the blocking call is initiated, and once when the callback is restoring its state. This ping-pong is necessary to capture the execution stack -- no other way in pure Java.

Parameters:

meth - method to be invoked

callee - object (either entity or entityreference) to be invoked

params - invocation parameters

Returns:

whatever was returned by blocking event

Throws:

JistAPI.Continuation - never (marker for rewriter)

java.lang.Throwable - whatever was thrown by blocking event

isModeRestore

public static boolean isModeRestore()

Return whether the event invocation is currently in restore mode.

Returns:

true if currently restoring an event execution stack

isModeRestoreInst

public boolean isModeRestoreInst()

Return whether the event invocation is currently in restore mode.

Returns:

true if currently restoring an event execution stack

isModeSave

public static boolean isModeSave()

Return whether the event invocation is currently in save mode.

Returns:

true if current save an event execution stack

isModeSaveInst

public boolean isModeSaveInst()

Return whether the event invocation is currently in save mode.

Returns:

true if current save an event execution stack

clearRestoreState

public java.lang.Object clearRestoreState()
                                   throws java.lang.Throwable

Clear restore state of current event, and callback result.

Returns:

callback result

Throws:

java.lang.Throwable - whatever was thrown by the blocking event

popStateInFrame

public static Event.ContinuationFrame popStateInFrame()

Pop a frame from the incoming execution stack.

Returns:

next frame from the incoming execution stack.

pushStateOutFrame

public static void pushStateOutFrame(Event.ContinuationFrame f)

Push a frame onto the outgoing execution stack.

Parameters:

f - next frame of outgoing execution stack.

switchCaller

public Event switchCaller(Event caller)

Switch caller (return) event.

Parameters:

caller - new caller (return) event

Returns:

old caller (return) event

setLog

public void setLog(JistAPI.Logger logger)

Set logging implementation.

Parameters:

logger - logging implementation

setLog

public void setLog(java.lang.Class loggerClass)
            throws java.lang.InstantiationException,
                   java.lang.IllegalAccessException

Set logging implementation.

Parameters:

loggerClass - logging class

Throws:

java.lang.InstantiationException - invalid logger class

java.lang.IllegalAccessException - invalid logger class

log

public void log(java.lang.String s)

Emit message in JisT log.

Specified by:

log in interface ControllerRemote

Parameters:

s - string to log