Intrinsic Functions: "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() – allocates a new property ID value, which is a property not previously used by any object in the program. Note that property ID's are a somewhat limited resource: only about 65,000 can be allocated, including those defined statically in the program.

t3DebugTrace(mode, …) – debugger interface. The mode parameter indicates the function to be performed. Any arguments after mode are specific to the mode. The valid mode values are:

• 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 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() – returns a LookupTable object populated with all of the program's global compile-time symbols. The symbol table is available during pre-initialization (i.e., when t3GetVMPreinitMode() returns true), and during normal execution when the program was compiled for debugging; at all other times, the symbol table is not available, and this function returns nil. For more information, see Reflection.

t3GetStackTrace() - returns information on the current call stack. This function returns a list of T3StackInfo objects; 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.

T3StackInfo is an ordinary class defined in the standard run-time 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() – returns the T3 VM banner string, which is a string identifying the VM, its version number, and its copyright information. This string is suitable for displaying as a start-up banner.

t3GetVMID() – returns the T3 VM identification string. This is a short string identifying the particular VM implementation; each different implementation has a unique identifier. Mike Roberts's T3 VM implementation has the identifying string 'mjr-T3'.

Note that the VM identification string identifies the VM itself, not the host application environment.

t3GetVMPreinitMode() – returns true if the VM is operating in pre-initialization mode, nil if the VM is operating in normal execution mode.

t3GetVMVsn() – get the T3 VM version number. This returns an integer value; the high-order 16 bits of the value give the major version number of the VM; the next 8 bits give the minor version number; and the low-order 8 bits give the patch release number. So, if V is the return value of this function,

• ((V >> 16) & 0xffff) yields the major version number
• ((V >> 8) & 0xff) yields the minor version number
• (V & 0xff) yields the patch release number

t3RunGC() – explicitly runs the garbage collector. Since the garbage collector runs automatically from time to time, it is never necessary to call this function explicitly. However, if the programmer identifies a particular point at which a large number of objects have suddenly become unreachable, and when a large number of objects are likely to be allocated soon, it might be advantageous to run the garbage collector explicitly so that it can optimize memory. It might also be desirable to run garbage collection explicitly when a natural user-interface pause is about to occur anyway, since this would take advantage of the natural pause to hide any delay that would occur running the collector. No return value.

t3SetSay(val) – set the default output function or method to the given value:

• 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:

o There is a valid "self" object (i.e., a method is being executed, not a stand-alone function).

o A default display method has been defined with t3SetSay().

o The current "self" object defines or inherits the default display method.

If these conditions aren't all true, the VM uses the default display function instead.

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