sleep.runtime

Class ScriptInstance

public class ScriptInstance extends Object implements Serializable, Runnable

Every piece of information related to a loaded script. This includes the scripts runtime environment, code in compiled form, variable information, and listeners for runtime issues.
Nested Class Summary
static classScriptInstance.ProfilerStatistic
A container for a profile statistic about a sleep function
static classScriptInstance.SleepStackElement
A container for Sleep strack trace elements.
Field Summary
protected intdebug
track all of the flagged debug options for this script (set to DEBUG_SHOW_ERRORS by default)
static intDEBUG_NONE
debug should be absolutely quiet, never fire any runtime warnings
static intDEBUG_REQUIRE_STRICT
fire runtime warning whenever an undeclared variable is fired
static intDEBUG_SHOW_ERRORS
fire runtime warnings for all critical flow interrupting errors
static intDEBUG_SHOW_WARNINGS
fire runtime warnings for anything flagged for retrieval with checkError()
static intDEBUG_THROW_WARNINGS
throw exceptions for anything flagged for retrieval with checkError()
static intDEBUG_TRACE_CALLS
fire a runtime warning describing each function call
static intDEBUG_TRACE_LOGIC
fire a runtime warning describing each predicate decision made
static intDEBUG_TRACE_PROFILE_ONLY
forces function call tracing to occur (for the sake of profiling a script) but supresses all runtime warnings as a result of the tracing
protected static intDEBUG_TRACE_SUPPRESS
users shouldn't need to flag this, it is just a general method of saying we're suppressing trace messages...
protected ScriptEnvironmentenvironment
The script environment which contains all of the runtime info for a script
protected booleanloaded
true by default, indicates wether or not the script is loaded.
protected Stringname
the name of this script
protected IOObjectparent
protected Blockscript
The compiled sleep code for this script, the ScriptLoader will set this value upon loading a script.
protected ScriptVariablesvariables
The script variables which contains all of the variable information for a script
protected LinkedListwatchers
A list of listeners watching for a runtime error
Constructor Summary
ScriptInstance(Hashtable environmentToShare)
Constructs a script instance, if the parameter is null a default implementation will be used.
ScriptInstance(Variable varContainerToUse, Hashtable environmentToShare)
Constructs a script instance, if either of the parameters are null a default implementation will be used.
ScriptInstance()
Constructs a new script instance
Method Summary
voidaddWarningWatcher(RuntimeWarningWatcher w)
Register a runtime warning watcher listener.
ScalarcallFunction(String funcName, Stack parameters)
Calls a subroutine/built-in function using this script.
voidclearStackTrace()
Removes the top element of the stack trace
voidcollect(String function, int lineNo, long ticks)
this function is used internally by the sleep interpreter to collect profiler statistics when DEBUG_TRACE_CALLS or DEBUG_TRACE_PROFILE_ONLY is enabled
voidfireWarning(String message, int line)
Fire a runtime script warning
voidfireWarning(String message, int line, boolean isTrace)
Fire a runtime script warning
ScriptInstancefork()
Creates a forked script instance.
intgetDebugFlags()
retrieve the debug flags for this script
StringgetName()
Returns the name of this script (typically a full pathname) as a String
ListgetProfilerStatistics()
Returns a sorted (in order of total ticks used) list of function call statistics for this script environment.
BlockgetRunnableBlock()
Returns the compiled form of this script
ScriptEnvironmentgetScriptEnvironment()
Returns this scripts runtime environment
ScriptVariablesgetScriptVariables()
Returns the variable container used by this script
ListgetStackTrace()
Returns the last stack trace.
voidinstallBlock(Block _script)
Install a block as the compiled script code
booleanisLoaded()
Returns wether or not this script is loaded.
booleanisProfileOnly()
a quick way to check if we are profiling and not tracing the script steps
voidprintProfileStatistics(OutputStream out)
Dumps the profiler statistics to the specified stream
voidrecordStackFrame(String description, String source, int lineNumber)
Records a stack frame into this environments stack trace tracker thingie.
voidrecordStackFrame(String description, int lineNumber)
Records a stack frame into this environments stack trace tracker thingie.
voidremoveWarningWatcher(RuntimeWarningWatcher w)
Removes a runtime warning watcher listener
voidrun()
Executes this script, same as runScript() just here for Runnable compatability
ScalarrunScript()
Executes this script, should be done first thing once a script is loaded
voidsetDebugFlags(int options)
set the debug flags for this script
voidsetName(String sn)
Sets the name of this script
voidsetParent(IOObject p)
Sets up the parent of this script (in case it is being run via &fork()).
voidsetScriptVariables(ScriptVariables v)
Sets the variable container to be used by this script
voidsetUnloaded()
Flag this script as unloaded

Field Detail

debug

protected int debug
track all of the flagged debug options for this script (set to DEBUG_SHOW_ERRORS by default)

DEBUG_NONE

public static final int DEBUG_NONE
debug should be absolutely quiet, never fire any runtime warnings

DEBUG_REQUIRE_STRICT

public static final int DEBUG_REQUIRE_STRICT
fire runtime warning whenever an undeclared variable is fired

DEBUG_SHOW_ERRORS

public static final int DEBUG_SHOW_ERRORS
fire runtime warnings for all critical flow interrupting errors

DEBUG_SHOW_WARNINGS

public static final int DEBUG_SHOW_WARNINGS
fire runtime warnings for anything flagged for retrieval with checkError()

DEBUG_THROW_WARNINGS

public static final int DEBUG_THROW_WARNINGS
throw exceptions for anything flagged for retrieval with checkError()

DEBUG_TRACE_CALLS

public static final int DEBUG_TRACE_CALLS
fire a runtime warning describing each function call

DEBUG_TRACE_LOGIC

public static final int DEBUG_TRACE_LOGIC
fire a runtime warning describing each predicate decision made

DEBUG_TRACE_PROFILE_ONLY

public static final int DEBUG_TRACE_PROFILE_ONLY
forces function call tracing to occur (for the sake of profiling a script) but supresses all runtime warnings as a result of the tracing

DEBUG_TRACE_SUPPRESS

protected static final int DEBUG_TRACE_SUPPRESS
users shouldn't need to flag this, it is just a general method of saying we're suppressing trace messages...

environment

protected ScriptEnvironment environment
The script environment which contains all of the runtime info for a script

loaded

protected boolean loaded
true by default, indicates wether or not the script is loaded. Once unloaded this variable must be flagged to false so the bridges know data related to this script is stale

name

protected String name
the name of this script

parent

protected IOObject parent

script

protected Block script
The compiled sleep code for this script, the ScriptLoader will set this value upon loading a script.

variables

protected ScriptVariables variables
The script variables which contains all of the variable information for a script

watchers

protected LinkedList watchers
A list of listeners watching for a runtime error

Constructor Detail

ScriptInstance

public ScriptInstance(Hashtable environmentToShare)
Constructs a script instance, if the parameter is null a default implementation will be used. By specifying the same shared Hashtable container for all scripts, such scripts can be made to environment information

ScriptInstance

public ScriptInstance(Variable varContainerToUse, Hashtable environmentToShare)
Constructs a script instance, if either of the parameters are null a default implementation will be used. By specifying the same shared Variable and Hashtable containers for all scripts, scripts can be made to share variables and environment information

ScriptInstance

public ScriptInstance()
Constructs a new script instance

Method Detail

addWarningWatcher

public void addWarningWatcher(RuntimeWarningWatcher w)
Register a runtime warning watcher listener. If an error occurs while the script is running these listeners will be notified

callFunction

public Scalar callFunction(String funcName, Stack parameters)
Calls a subroutine/built-in function using this script.

clearStackTrace

public void clearStackTrace()
Removes the top element of the stack trace

collect

public void collect(String function, int lineNo, long ticks)
this function is used internally by the sleep interpreter to collect profiler statistics when DEBUG_TRACE_CALLS or DEBUG_TRACE_PROFILE_ONLY is enabled

fireWarning

public void fireWarning(String message, int line)
Fire a runtime script warning

fireWarning

public void fireWarning(String message, int line, boolean isTrace)
Fire a runtime script warning

fork

public ScriptInstance fork()
Creates a forked script instance. This does not work like fork in an operating system. Variables are not copied, period. The idea is to create a fork that shares the same environment as this script instance.

getDebugFlags

public int getDebugFlags()
retrieve the debug flags for this script

getName

public String getName()
Returns the name of this script (typically a full pathname) as a String

getProfilerStatistics

public List getProfilerStatistics()
Returns a sorted (in order of total ticks used) list of function call statistics for this script environment. The list contains ScriptInstance.ProfileStatistic objects. Note!!! For Sleep to provide profiler statistics, DEBUG_TRACE_CALLS or DEBUG_TRACE_PROFILE_ONLY must be enabled!

getRunnableBlock

public Block getRunnableBlock()
Returns the compiled form of this script

getScriptEnvironment

public ScriptEnvironment getScriptEnvironment()
Returns this scripts runtime environment

getScriptVariables

public ScriptVariables getScriptVariables()
Returns the variable container used by this script

getStackTrace

public List getStackTrace()
Returns the last stack trace. Each element of the list is a ScriptInstance.SleepStackElement object. First element is the top of the trace, last element is the origin of the trace. This function also clears the stack trace.

installBlock

public void installBlock(Block _script)
Install a block as the compiled script code

isLoaded

public boolean isLoaded()
Returns wether or not this script is loaded. If it is unloaded it should be removed from data structures and its modifications to the environment should be ignored

isProfileOnly

public boolean isProfileOnly()
a quick way to check if we are profiling and not tracing the script steps

printProfileStatistics

public void printProfileStatistics(OutputStream out)
Dumps the profiler statistics to the specified stream

recordStackFrame

public void recordStackFrame(String description, String source, int lineNumber)
Records a stack frame into this environments stack trace tracker thingie.

recordStackFrame

public void recordStackFrame(String description, int lineNumber)
Records a stack frame into this environments stack trace tracker thingie.

removeWarningWatcher

public void removeWarningWatcher(RuntimeWarningWatcher w)
Removes a runtime warning watcher listener

run

public void run()
Executes this script, same as runScript() just here for Runnable compatability

runScript

public Scalar runScript()
Executes this script, should be done first thing once a script is loaded

setDebugFlags

public void setDebugFlags(int options)
set the debug flags for this script

setName

public void setName(String sn)
Sets the name of this script

setParent

public void setParent(IOObject p)
Sets up the parent of this script (in case it is being run via &fork()). When this script returns a value, the return value will be passed to the parent IOObject to allow retrieval with the &wait function.

setScriptVariables

public void setScriptVariables(ScriptVariables v)
Sets the variable container to be used by this script

setUnloaded

public void setUnloaded()
Flag this script as unloaded