Package sleep.runtime

Class 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
    • Field Summary

      Fields 
      Modifier and Type Field Description
      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

      Constructors 
      Constructor Description
      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

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      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)
    • 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