t3vm Function Set
The t3vm function set provides access to internal operations in the VM. This function set is provided by all T3 VM implementations and all host applications.
t3AllocProp()
t3DebugTrace(mode, ...)
- T3DebugCheck - check to determine if a debugger is present. Returns true if a debugger is present, nil if not.
- T3DebugBreak - break into the debugger, if present. Returns true if a debugger is present, nil if not. If the function returns nil, it will have had no effect, since it's meaningless to break into the debugger if no debugger is present. If a debugger is present, though, the function will activate single-stepping mode, which will cause the debugger to take control immediately after the function returns.
If this function is called with any other values for the mode argument, it simply ignores any additional arguments and returns nil; this allows for compatible extensions to the function in the future by the addition of new mode values.
t3GetGlobalSymbols()
For more information, see the reflection section.
t3GetStackTrace(level?)
If level is omitted, the function returns a list of T3StackInfo objects, one for each level of the entire stack. Each object in the list represents one level, or "frame," of the stack trace. A frame is the data structure that the virtual machine establishes each time the program invokes a method or function; the frame contains information on the function or object method invoked, and the actual parameters (i.e., the argument values).
The first T3StackInfo object in the list represents the current function or method - that is, the code that invoked t3GetStackTrace(). The second element of the list represents the current code's caller, the third element represents the second element's caller, and so on.
If level is specified, it's an integer giving the single stack level to retrieve: 1 is the current active level, 2 is the immediate caller, and so on. The function then returns a single T3StackInfo object giving the description of that level. (The return value isn't a list in this case-it's simply the T3StackInfo object.)
T3StackInfo is an ordinary class defined in the basic system library. This class defines the following properties:
- func_ - the function at this level, as a function pointer, or nil if this is an object method
- obj_ - the object whose method is being invoked, or nil if this is a function. Note that this is not necessarily the same as the self in the frame: this is the object where the method is actually defined, which can be a base class of the self object if the method was inherited.
- prop - the property pointer value for the method invoked, or nil if this is a function.
- self_ - the self object in the frame, or nil if this is a function.
- argList_ - a list of the actual parameters (argument values) to the function or method. The elements of the list are in the same order as the arguments.
- srcInfo_ - the source code location for the next execution point in the frame, or nil if source information is not available. Source information is available only if the program was compiled for debugging, but is never available for system routines. The source information is given as a list of two elements: the first element is a string giving the name of a source file, and the second is an integer giving the line number in the source file. Note that srcInfo_ indicates the location of the next instruction that will be executed when control returns to the frame, so this will frequently indicate the next source code statement after the one that actually invoked the next more nested frame.
In addition, the class defines the following method:
- isSystem() - returns true if the frame represents a call to an intrinsic function or a intrinsic class method. If this returns true, then none of the other information in the frame is available, including the argument list.
t3GetVMBanner()
t3GetVMID()
Note that the VM identification string identifies the VM itself, not the host application environment.
t3GetVMPreinitMode()
t3GetVMVsn()
- ((V >> 16) & 0xffff) yields the major version number
- ((V >> 8) & 0xff) yields the minor version number
- (V & 0xff) yields the patch release number
t3RunGC()
t3SetSay(val)
- If val is a property pointer, this sets the default output
method to the given property. The VM invokes this property on
whatever self object is currently active each time a double-quoted
string is evaluated and each time an embedded expression in a
double-quoted string is to be displayed. The VM invokes this function
only when all of the following conditions are true at the time a
string is to be displayed:
- There is a valid self object (i.e., a method is being executed, not a stand-alone function).
- A default display method has been defined with t3SetSay().
- The current self object defines or inherits the default display method.
- If val is a function pointer (to a user-defined function, not an intrinsic function), this sets the default output function to the function val points to. The function must take a single argument, which is the value to be displayed, and returns no value. The VM invokes this function when a double-quoted string is evaluated, and when an embedded expression in a double-quoted string is to be displayed, except that the default display method is called instead when applicable.
- If val is the special value T3SetSayNoMethod, this removes any default output method.
- If val is the special value T3SetSayNoFunc, this removes any default output function.
This return value gives the previous default output function or method. If val is a property pointer or the special value T3SetSayNoMethod, the return value is the old default output method; otherwise, the return value is the old default output function. The special values T3SetSayNoFunc and T3SetSayNoMethod can also be returned, indicating that there was no previous function or method, respectively. The return value allows the caller to save and later restore the setting being changed, which is useful when the caller just wants to change the setting temporarily while running a particular block of code.