internal.doc

Unix下的MUD客户端程序

VT Internals Documentation


Description
-----------

This file documents some of the methods used by VT to implement its
features.


Organization
------------

The following topics are covered: memory management, primitive
functions, the interpreter, the compiler, and VTC efficiency notes.


Memory management
-----------------

The majority of VT's automatic memory management is done with
reference counting.  Leaks are possible through self-referential array
structures, so there is also a garbage collector.  VT code that
manipulates arrays, regexps, strings or programs must maintain the
reference counts for these structures so that they are not deleted
prematurely or leaked.

Data structures that are deleted at a predetermined time are
"backlisted"-- that is, they store a list of VTC data frames that
refer to them.  User nodes (remotes, windows, key bindings, files) and
some arrays are backlisted.  Pointers to user nodes and backlisted
arrays in the VT program should not be left lying around unless they
are the primary pointers used to find those objects or are encased in
Dframe structures, because the backlisting scheme is designed to
handle Dframes used by VTC code.  When backlisted objects are deleted,
the frames that refer to them are reset to NULL values.  Backlists are
stored in dynamically allocated linked chains.

Arrays are reference-counted if they are alloc() arrays.  The gvars
array is never deleted, so it is not reference-counted.  Parameter and
local variable arrays are deleted at a predetermined time (when the
function exits) and are backlisted.

Strings are reference-counted at two levels.  The Rstr structure
contains a dynamically-allocated string and a reference count, and is
used to keep track of the physical representations of VTC strings.  An
Istr structure contains a pointer to an Rstr and a reference count;
each Istr represents a copy of the string from the point of view of
the interpreter.  Although several Istrs can point to a single Rstr,
the interpreter and primitive functions must make sure that changes to
one Istr do not affect the other Istrs pointing to the same Rstr.
This is accomplished by passing the Istr to isolate() before making
modifications to it.  isolate() makes a separate copy of the string (a
new Rstr) if the current Rstr has more than one Istr pointing to it.
When the reference count for an Rstr drops to zero (no copies of the
string are referenced by VTC pointers), the string is freed; when the
reference count for an Istr drops to zero (that particular copy of a
string is no longer referenced by any VTC pointers) the Istr structure
is freed.

Most of the memory management in the VT program is handled through the
ref_frame() and deref_frame() functions and their companion functions
ref_frames() and deref_frames().  These examine the types of their
arguments, which are data frames or arrays of data frames, and do the
appropriate referencing or dereferencing.

One sometimes annoying constraint of the memory management system is
that the programmer must be careful to increment the reference count
of data frames before decrementing the counts of any other data frames
that might point to the same objects.  As an example, when a primitive
function returns, the interpreter must do a ref_frame() on the return
value before calling deref_frames() on the arguments that it must
remove to make room to place the return value on the data stack.  If
it called deref_frames() first, the object that the return value
pointed to might be deleted.

Another constraint is that, because backlists store the locations of
data frames that point to them, the memory manager must be informed
when data frames move.  After the interpreter calls ref_frame() on the
return value of a primitive function and deletes the arguments that
were passed to the primitive, it adds the return value to the top of
the stack.  Since it has just moved the value from one Dframe
structure to another, it must call move_frame_refs() to update
backlists that contained the location of the return value.
Fortunately, move_frame_refs() takes essentially zero time unless it
is dealing with a backlisted object, and even then in the case of the
return value from primitive functions, the reference will always be at
the front of the backlist chain since it has just been added.

Some organized memory management is done in the compiler.  All
identifiers read by the tokenizer are indexed in a resizable table and
freed as a group when the parser is finished.  Other than that, the
parser allocates and frees memory on an as-needed basis.

In general, VT's memory management makes intensive use of dynamic 
allocation, and in particular repeated allocation and freeing of 
small data structures.  For this reason, VT uses a tray malloc.  
Tray malloc simply allocates structures of 16 bytes or less from 
trays.  This saves lots of time, and probably some space as well.


Primitive functions
-------------------

Primitive functions and operator functions communicate with the
interpreter through Dframes.  They generally do not need to worry
about reference counts unless they are modifying data structures that
hold other Dframes.

A primitive function's definition begins with:

void pr_name(rf, argc, argv)
        Dframe *rf, *argv;
        int argc;

In prmt.h this is abbreviated "PDECL(pr_name)".  rf is the return
frame, and is initialized to type F_NULL before the primitive or
operator function is called.  So a primitive need do nothing to return
a value of NULL.  argc and argv are the arguments-- if the primitive
is specified as accepting a certain number of arguments (the argc
element of the primitive structure is positive) in the table in
prmtab.c, argc is guaranteed to be that number.

Primitives can access up to four arguments easily through the Dp1,
Dp2, Dp3 and Dp4 macros, which stand for argv[0], argv[1], argv[2] and
argv[3] respectively.  In addition, Dp is an abbreviation for Dp1 for
primitives which take only one argument.  Tp and Tp1..Tp4 are
abbreviations for the types of Dp1..Dp4, Int and Int1..Int4 for the
integer values for integer data frames, and Un and Un1..Un4 for the
user node values.

The first step of most primitive functions is to type-check its
arguments.  This is not done systematically because a significant
number of primitives accept a variety of different argument types.
The macro Terror("name") displays an error message in the current
window and returns a message to the interpreter to abort.

Primitive functions need not deal with adding rf to backlists or
incrementing reference counts of objects it is returning, because the
interpreter automatically calls ref_frame() on rf after the primitive
function returns.  However, if they are assigning a data frame to a
data structure such as an array element or a window/remote object,
they must call ref_frame() on the data frame they assigned to.


Interpreter
-----------

The VTC interpreter is a fairly simple stack machine that operates on
a data stack (dstack) and a call stack (cstack).  The interpreter is
reentrant, so that the data stack and call stack may have data and
call frames from several different programs at the same time.  A call
frame that is the starting frame of a program is called a "detached"
frame, and a postcondition of the interp() function is that the
detached frame closest to the top of the call stack will have been
removed, along with all the call frames above it, when interp() exits.
The call frames in the call stack contain enough information to
determine which data frames are associated with which programs on the
call stack.

The programs the interpreter reads are a sequence of one-word