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

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(which?)

Returns information on the program's compile-time symbols.

which determines which type of symbol information to retrieve. This is one of the following constant values:

The which argument is optional. If you omit it, the default is T3GlobalSymbols, to retrieve the global symbol table.

The symbolic information this function retrieves is available during pre-initialization (i.e., when t3GetVMPreinitMode() returns true), and during normal execution if the program was compiled for debugging. At other times, symbol information isn't available, so this function returns nil. Because the return value is an ordinary LookupTable object, though, it's easy to keep it available at all times by adding a little code of your own. Simply call this function during preinit, and store the result in an object property. For example:

symTabSaver: PreinitObject
   execute() { symtab = t3GetGlobalSymbols(); }{
   symtab = nil;
;

With the code above, you can access the symbol table at any time after preinit, even in a regular build, using symTabSaver.symtab.

For more information, see the reflection section.

t3GetNamedArg(name, defval?)

Retrieves the value of the named argument with the given name.

name is a string giving the argument name. If the specified named argument exists, the function returns the value of the argument.

defval is the default value. If the named argument doesn't exist, and defval is provided, the function returns defval. If the argument doesn't exist and defval is omitted, the function instead throws an error.

t3GetNamedArgList()

Retrieves a list of the names of all of the named arguments currently in effect. If no named arguments are in effect, returns an empty list. You can get the current value of a named argument by calling t3GetNamedArg() on the name.

t3GetStackTrace(level?, flags?)

Returns information on the current call stack, or on a given stack 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.)

flags is a combination (with the bitwise OR operator, '|') of the following bit values:

If flags is omitted, the default value is 0.

T3StackInfo is an ordinary class defined in the basic system library. This class defines the following properties:

In addition, the class defines the following method:

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. The reference 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. Pre-initialization mode is the mode that's active during the preinit phase of compilation.

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,

t3RunGC()

Explicitly runs the garbage collector. This traces through memory to determine which objects can be referenced through local variables, properties of reachable objects, and any other ways that the program can refer to objects. Objects that aren't reachable are removed from memory.

The garbage collector runs automatically from time to time, according to memory usage and other factors, so you never have to call this function explicitly. However, it's sometimes useful to make the collector run at particular times.

This function has no return value.

t3SetSay(val)

Set the default output function or method to the given value:

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.