sleep.runtime
Class ScriptInstance

java.lang.Object
  sleep.runtime.ScriptInstance

All Implemented Interfaces:

java.io.Serializable, java.lang.Runnable

public class ScriptInstance
extends java.lang.Object
implements java.io.Serializable, java.lang.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.

See Also:

Serialized Form

Nested Class Summary

static class	ScriptInstance.ProfilerStatistic A container for a profile statistic about a sleep function
static class	ScriptInstance.SleepStackElement A container for Sleep strack trace elements.

Field Summary

protected int	debug track all of the flagged debug options for this script (set to DEBUG_SHOW_ERRORS by default)
static int	DEBUG_NONE debug should be absolutely quiet, never fire any runtime warnings
static int	DEBUG_REQUIRE_STRICT fire runtime warning whenever an undeclared variable is fired
static int	DEBUG_SHOW_ERRORS fire runtime warnings for all critical flow interrupting errors
static int	DEBUG_SHOW_WARNINGS fire runtime warnings for anything flagged for retrieval with checkError()
static int	DEBUG_THROW_WARNINGS throw exceptions for anything flagged for retrieval with checkError()
static int	DEBUG_TRACE_CALLS fire a runtime warning describing each function call
static int	DEBUG_TRACE_LOGIC fire a runtime warning describing each predicate decision made
static 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
protected static int	DEBUG_TRACE_SUPPRESS users shouldn't need to flag this, it is just a general method of saying we're suppressing trace messages...
static int	DEBUG_TRACE_TAINT trace the passage of tainted data
protected ScriptEnvironment	environment The script environment which contains all of the runtime info for a script
protected boolean	loaded true by default, indicates wether or not the script is loaded.
protected long	loadTime track the time this script was loaded
protected java.lang.String	name the name of this script
protected IOObject	parent
protected SleepClosure	script The compiled sleep code for this script, the ScriptLoader will set this value upon loading a script.
protected java.util.List	sourceFiles list of source files associated with this script (to account for &include)
protected ScriptVariables	variables The script variables which contains all of the variable information for a script
protected java.util.LinkedList	watchers A list of listeners watching for a runtime error

Constructor Summary

ScriptInstance()
Constructs a new script instance

ScriptInstance(java.util.Hashtable environmentToShare)
Constructs a script instance, if the parameter is null a default implementation will be used.

ScriptInstance(Variable varContainerToUse, java.util.Hashtable environmentToShare)
Constructs a script instance, if either of the parameters are null a default implementation will be used.

Method Summary

void	addWarningWatcher(RuntimeWarningWatcher w) Register a runtime warning watcher listener.
void	associateFile(java.io.File f) associates the specified source file with this script
Scalar	callFunction(java.lang.String funcName, java.util.Stack parameters) Calls a subroutine/built-in function using this script.
void	chdir(java.io.File f) sets the current working directory value for this script
void	clearStackTrace() Removes the top element of the stack trace
void	collect(java.lang.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
java.io.File	cwd() return the current working directory value associated with this script.
void	fireWarning(java.lang.String message, int line) Fire a runtime script warning
void	fireWarning(java.lang.String message, int line, boolean isTrace) Fire a runtime script warning
ScriptInstance	fork() Creates a forked script instance.
int	getDebugFlags() retrieve the debug flags for this script
java.util.Map	getMetadata() retrieves script meta data for you to update
java.lang.String	getName() Returns the name of this script (typically a full pathname) as a String
java.util.List	getProfilerStatistics() Returns a sorted (in order of total ticks used) list of function call statistics for this script environment.
Block	getRunnableBlock() Returns the compiled form of this script
SleepClosure	getRunnableScript() Returns this toplevel script as a Sleep closure.
ScriptEnvironment	getScriptEnvironment() Returns this scripts runtime environment
ScriptVariables	getScriptVariables() Returns the variable container used by this script
java.util.List	getStackTrace() Returns the last stack trace.
boolean	hasChanged() this script instance checks if (to the best of its knowledge) any of its source files have changed
void	installBlock(Block _script) Install a block as the compiled script code
boolean	isLoaded() Returns wether or not this script is loaded.
boolean	isProfileOnly() a quick way to check if we are profiling and not tracing the script steps
void	makeSafe() Call this function if you're sharing a script environment with other script instances.
void	printProfileStatistics(java.io.OutputStream out) Dumps the profiler statistics to the specified stream
void	recordStackFrame(java.lang.String description, int lineNumber) Records a stack frame into this environments stack trace tracker thingie.
void	recordStackFrame(java.lang.String description, java.lang.String source, int lineNumber) Records a stack frame into this environments stack trace tracker thingie.
void	removeWarningWatcher(RuntimeWarningWatcher w) Removes a runtime warning watcher listener
void	run() Executes this script, same as runScript() just here for Runnable compatability
Scalar	runScript() Executes this script, should be done first thing once a script is loaded
void	setDebugFlags(int options) set the debug flags for this script
void	setName(java.lang.String sn) Sets the name of this script
void	setParent(IOObject p) Sets up the parent of this script (in case it is being run via &fork()).
void	setScriptVariables(ScriptVariables v) Sets the variable container to be used by this script
void	setUnloaded() Flag this script as unloaded
long	total() return the total number of ticks this script has spent processing

Methods inherited from class java.lang.Object

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

Field Detail

name

protected java.lang.String name

the name of this 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

watchers

protected java.util.LinkedList watchers

A list of listeners watching for a runtime error

environment

protected ScriptEnvironment environment

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

variables

protected ScriptVariables variables

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

script

protected SleepClosure script

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

DEBUG_NONE

public static final int DEBUG_NONE

debug should be absolutely quiet, never fire any runtime warnings

See Also:

Constant Field Values

DEBUG_SHOW_ERRORS

public static final int DEBUG_SHOW_ERRORS

fire runtime warnings for all critical flow interrupting errors

See Also:

Constant Field Values

DEBUG_SHOW_WARNINGS

public static final int DEBUG_SHOW_WARNINGS

fire runtime warnings for anything flagged for retrieval with checkError()

See Also:

Constant Field Values

DEBUG_REQUIRE_STRICT

public static final int DEBUG_REQUIRE_STRICT

fire runtime warning whenever an undeclared variable is fired

See Also:

Constant Field Values

DEBUG_TRACE_CALLS

public static final int DEBUG_TRACE_CALLS

fire a runtime warning describing each function call

See Also:

Constant Field Values

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

See Also:

Constant Field Values

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...

See Also:

Constant Field Values

DEBUG_THROW_WARNINGS

public static final int DEBUG_THROW_WARNINGS

throw exceptions for anything flagged for retrieval with checkError()

See Also:

Constant Field Values

DEBUG_TRACE_LOGIC

public static final int DEBUG_TRACE_LOGIC

fire a runtime warning describing each predicate decision made

See Also:

Constant Field Values

DEBUG_TRACE_TAINT

public static final int DEBUG_TRACE_TAINT

trace the passage of tainted data

See Also:

Constant Field Values

debug

protected int debug

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

loadTime

protected long loadTime

track the time this script was loaded

sourceFiles

protected java.util.List sourceFiles

list of source files associated with this script (to account for &include)

parent

protected IOObject parent

Constructor Detail

ScriptInstance

public ScriptInstance(java.util.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,
                      java.util.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

associateFile

public void associateFile(java.io.File f)

associates the specified source file with this script

hasChanged

public boolean hasChanged()

this script instance checks if (to the best of its knowledge) any of its source files have changed

setDebugFlags

public void setDebugFlags(int options)

set the debug flags for this script

getDebugFlags

public int getDebugFlags()

retrieve the debug flags for this script

installBlock

public void installBlock(Block _script)

Install a block as the compiled script code

getScriptEnvironment

public ScriptEnvironment getScriptEnvironment()

Returns this scripts runtime environment

setScriptVariables

public void setScriptVariables(ScriptVariables v)

Sets the variable container to be used by this script

getScriptVariables

public ScriptVariables getScriptVariables()

Returns the variable container used by this script

getName

public java.lang.String getName()

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

setName

public void setName(java.lang.String sn)

Sets the name of this script

runScript

public Scalar runScript()

Executes this script, should be done first thing once a script is loaded

recordStackFrame

public void recordStackFrame(java.lang.String description,
                             java.lang.String source,
                             int lineNumber)

Records a stack frame into this environments stack trace tracker thingie.

cwd

public java.io.File cwd()

return the current working directory value associated with this script.

chdir

public void chdir(java.io.File f)

sets the current working directory value for this script

recordStackFrame

public void recordStackFrame(java.lang.String description,
                             int lineNumber)

Records a stack frame into this environments stack trace tracker thingie.

clearStackTrace

public void clearStackTrace()

Removes the top element of the stack trace

getStackTrace

public java.util.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.

total

public long total()

return the total number of ticks this script has spent processing

collect

public void collect(java.lang.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

isProfileOnly

public boolean isProfileOnly()

a quick way to check if we are profiling and not tracing the script steps

getProfilerStatistics

public java.util.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!

getMetadata

public java.util.Map getMetadata()

retrieves script meta data for you to update

printProfileStatistics

public void printProfileStatistics(java.io.OutputStream out)

Dumps the profiler statistics to the specified stream

makeSafe

public void makeSafe()

Call this function if you're sharing a script environment with other script instances. This will sanitize the current script environment to avoid leakage between closure scopes, coroutines, and continuations. Call this after script loading / bridge installation and before you run any scripts.

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.

run

public void run()

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

Specified by:

run in interface java.lang.Runnable

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.

getRunnableBlock

public Block getRunnableBlock()

Returns the compiled form of this script

See Also:

getRunnableScript()

getRunnableScript

public SleepClosure getRunnableScript()

Returns this toplevel script as a Sleep closure.

callFunction

public Scalar callFunction(java.lang.String funcName,
                           java.util.Stack parameters)

Calls a subroutine/built-in function using this script.

setUnloaded

public void setUnloaded()

Flag this script as unloaded

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

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

removeWarningWatcher

public void removeWarningWatcher(RuntimeWarningWatcher w)

Removes a runtime warning watcher listener

fireWarning

public void fireWarning(java.lang.String message,
                        int line)

Fire a runtime script warning

fireWarning

public void fireWarning(java.lang.String message,
                        int line,
                        boolean isTrace)

Fire a runtime script warning