util/src/TclTk/blt2.5/generic/bltInterp.h

   1 /*
   2  * bltInterp.h --
   3  *
   4  *      Excerpts from tclInt.h.  Used to examine interpreter internals.
   5  *      Needed by the former (now obsoleted) TclParse* functions.
   6  *
   7  * Copyright (c) 1987-1993 The Regents of the University of California.
   8  * Copyright (c) 1993-1997 Lucent Technologies.
   9  * Copyright (c) 1994-1998 Sun Microsystems, Inc.
  10  *
  11  */
  12
  13 /*
  14  *----------------------------------------------------------------
  15  * Data structures related to command parsing. These are used in
  16  * tclParse.c and its clients.
  17  *----------------------------------------------------------------
  18  */
  19
  20 /*
  21  * The following data structure is used by various parsing procedures
  22  * to hold information about where to store the results of parsing
  23  * (e.g. the substituted contents of a quoted argument, or the result
  24  * of a nested command).  At any given time, the space available
  25  * for output is fixed, but a procedure may be called to expand the
  26  * space available if the current space runs out.
  27  */
  28 typedef struct ParseValueStruct ParseValue;
  29
  30 struct ParseValueStruct {
  31     char *buffer;               /* Address of first character in
  32                                  * output buffer. */
  33     char *next;                 /* Place to store next character in
  34                                  * output buffer. */
  35     char *end;                  /* Address of the last usable character
  36                                  * in the buffer. */
  37     void (*expandProc) _ANSI_ARGS_((ParseValue *pvPtr, int needed));
  38                                 /* Procedure to call when space runs out;
  39                                  * it will make more space. */
  40     ClientData clientData;      /* Arbitrary information for use of
  41                                  * expandProc. */
  42 };
  43
  44
  45 /*
  46  * The definitions for the LiteralTable and LiteralEntry structures. Each
  47  * interpreter contains a LiteralTable. It is used to reduce the storage
  48  * needed for all the Tcl objects that hold the literals of scripts compiled
  49  * by the interpreter. A literal's object is shared by all the ByteCodes
  50  * that refer to the literal. Each distinct literal has one LiteralEntry
  51  * entry in the LiteralTable. A literal table is a specialized hash table
  52  * that is indexed by the literal's string representation, which may contain
  53  * null characters.
  54  *
  55  * Note that we reduce the space needed for literals by sharing literal
  56  * objects both within a ByteCode (each ByteCode contains a local
  57  * LiteralTable) and across all an interpreter's ByteCodes (with the
  58  * interpreter's global LiteralTable).
  59  */
  60
  61 typedef struct LiteralEntryStruct LiteralEntry;
  62
  63 struct LiteralEntryStruct {
  64     LiteralEntry *nextPtr;      /* Points to next entry in this
  65                                  * hash bucket or NULL if end of
  66                                  * chain. */
  67     Tcl_Obj *objPtr;            /* Points to Tcl object that
  68                                  * holds the literal's bytes and
  69                                  * length. */
  70     int refCount;               /* If in an interpreter's global
  71                                  * literal table, the number of
  72                                  * ByteCode structures that share
  73                                  * the literal object; the literal
  74                                  * entry can be freed when refCount
  75                                  * drops to 0. If in a local literal
  76                                  * table, -1. */
  77 };
  78
  79 typedef struct {
  80     LiteralEntry **buckets;     /* Pointer to bucket array. Each
  81                                          * element points to first entry in
  82                                          * bucket's hash chain, or NULL. */
  83     LiteralEntry *staticBuckets[TCL_SMALL_HASH_TABLE];
  84     /* Bucket array used for small
  85                                          * tables to avoid mallocs and
  86                                          * frees. */
  87     int numBuckets;             /* Total number of buckets allocated
  88                                          * at **buckets. */
  89     int numEntries;             /* Total number of entries present
  90                                          * in table. */
  91     int rebuildSize;            /* Enlarge table when numEntries
  92                                          * gets to be this large. */
  93     int mask;                   /* Mask value used in hashing
  94                                          * function. */
  95 } LiteralTable;
  96
  97 /*
  98  * The following structure defines for each Tcl interpreter various
  99  * statistics-related information about the bytecode compiler and
 100  * interpreter's operation in that interpreter.
 101  */
 102
 103 #ifdef TCL_COMPILE_STATS
 104 typedef struct {
 105     long numExecutions;         /* Number of ByteCodes executed. */
 106     long numCompilations;       /* Number of ByteCodes created. */
 107     long numByteCodesFreed;     /* Number of ByteCodes destroyed. */
 108     long instructionCount[256]; /* Number of times each instruction was
 109                                    * executed. */
 110
 111     double totalSrcBytes;       /* Total source bytes ever compiled. */
 112     double totalByteCodeBytes;  /* Total bytes for all ByteCodes. */
 113     double currentSrcBytes;     /* Src bytes for all current ByteCodes. */
 114     double currentByteCodeBytes;/* Code bytes in all current ByteCodes. */
 115
 116     long srcCount[32];          /* Source size distribution: # of srcs of
 117                                    * size [2**(n-1)..2**n), n in [0..32). */
 118     long byteCodeCount[32];     /* ByteCode size distribution. */
 119     long lifetimeCount[32];     /* ByteCode lifetime distribution (ms). */
 120
 121     double currentInstBytes;    /* Instruction bytes-current ByteCodes. */
 122     double currentLitBytes;     /* Current literal bytes. */
 123     double currentExceptBytes;  /* Current exception table bytes. */
 124     double currentAuxBytes;     /* Current auxiliary information bytes. */
 125     double currentCmdMapBytes;  /* Current src<->code map bytes. */
 126
 127     long numLiteralsCreated;    /* Total literal objects ever compiled. */
 128     double totalLitStringBytes; /* Total string bytes in all literals. */
 129     double currentLitStringBytes;       /* String bytes in current literals. */
 130     long literalCount[32];      /* Distribution of literal string sizes. */
 131 } ByteCodeStats;
 132
 133 #endif /* TCL_COMPILE_STATS */
 134
 135
 136 /*
 137  *----------------------------------------------------------------
 138  * Data structures and procedures related to TclHandles, which
 139  * are a very lightweight method of preserving enough information
 140  * to determine if an arbitrary malloc'd block has been deleted.
 141  *----------------------------------------------------------------
 142  */
 143
 144 typedef VOID **TclHandle;
 145
 146
 147 /*
 148  *   The following fills in dummy types for structure refered to
 149  *   internally by the Tcl interpreter.  Since we don't need the actual
 150  *   size of the structures (they are only pointer references), we'll
 151  *   simply provide empty opaque types.
 152  *
 153  */
 154 typedef struct CallFrameStruct CallFrame;
 155 typedef struct NamespaceStruct Namespace;
 156 typedef struct ActiveVarTraceStruct ActiveVarTrace;
 157 typedef struct ProcStruct Proc;
 158 typedef struct TraceStruct Trace;
 159
 160 typedef struct TclRegexpStruct TclRegexp;
 161 typedef struct ExecEnvStruct ExecEnv;
 162
 163
 164 /*
 165  *----------------------------------------------------------------
 166  * This structure defines an interpreter, which is a collection of
 167  * commands plus other state information related to interpreting
 168  * commands, such as variable storage. Primary responsibility for
 169  * this data structure is in tclBasic.c, but almost every Tcl
 170  * source file uses something in here.
 171  *----------------------------------------------------------------
 172  */
 173
 174 typedef struct {
 175
 176     /*
 177      * Note:  the first three fields must match exactly the fields in
 178      * a Tcl_Interp struct (see tcl.h).  If you change one, be sure to
 179      * change the other.
 180      *
 181      * The interpreter's result is held in both the string and the
 182      * objResultPtr fields. These fields hold, respectively, the result's
 183      * string or object value. The interpreter's result is always in the
 184      * result field if that is non-empty, otherwise it is in objResultPtr.
 185      * The two fields are kept consistent unless some C code sets
 186      * interp->result directly. Programs should not access result and
 187      * objResultPtr directly; instead, they should always get and set the
 188      * result using procedures such as Tcl_SetObjResult, Tcl_GetObjResult,
 189      * and Tcl_GetStringResult. See the SetResult man page for details.
 190      */
 191
 192     char *result;               /* If the last command returned a string
 193                                  * result, this points to it. Should not be
 194                                  * accessed directly; see comment above. */
 195     Tcl_FreeProc *freeProc;     /* Zero means a string result is statically
 196                                  * allocated. TCL_DYNAMIC means string
 197                                  * result was allocated with ckalloc and
 198                                  * should be freed with ckfree. Other values
 199                                  * give address of procedure to invoke to
 200                                  * free the string result. Tcl_Eval must
 201                                  * free it before executing next command. */
 202     int errorLine;              /* When TCL_ERROR is returned, this gives
 203                                  * the line number in the command where the
 204                                  * error occurred (1 means first line). */
 205     Tcl_Obj *objResultPtr;      /* If the last command returned an object
 206                                  * result, this points to it. Should not be
 207                                  * accessed directly; see comment above. */
 208
 209     TclHandle handle;           /* Handle used to keep track of when this
 210                                  * interp is deleted. */
 211
 212     Namespace *globalNsPtr;     /* The interpreter's global namespace. */
 213     Tcl_HashTable *hiddenCmdTablePtr;
 214     /* Hash table used by tclBasic.c to keep
 215                                  * track of hidden commands on a per-interp
 216                                  * basis. */
 217     ClientData interpInfo;      /* Information used by tclInterp.c to keep
 218                                  * track of master/slave interps on
 219                                  * a per-interp basis. */
 220     Tcl_HashTable mathFuncTable;/* Contains all the math functions currently
 221                                  * defined for the interpreter.  Indexed by
 222                                  * strings (function names); values have
 223                                  * type (MathFunc *). */
 224
 225
 226
 227     /*
 228      * Information related to procedures and variables. See tclProc.c
 229      * and tclvar.c for usage.
 230      */
 231
 232     int numLevels;              /* Keeps track of how many nested calls to
 233                                  * Tcl_Eval are in progress for this
 234                                  * interpreter.  It's used to delay deletion
 235                                  * of the table until all Tcl_Eval
 236                                  * invocations are completed. */
 237     int maxNestingDepth;        /* If numLevels exceeds this value then Tcl
 238                                  * assumes that infinite recursion has
 239                                  * occurred and it generates an error. */
 240     CallFrame *framePtr;        /* Points to top-most in stack of all nested
 241                                  * procedure invocations.  NULL means there
 242                                  * are no active procedures. */
 243     CallFrame *varFramePtr;     /* Points to the call frame whose variables
 244                                  * are currently in use (same as framePtr
 245                                  * unless an "uplevel" command is
 246                                  * executing). NULL means no procedure is
 247                                  * active or "uplevel 0" is executing. */
 248     ActiveVarTrace *activeTracePtr;
 249     /* First in list of active traces for
 250                                  * interp, or NULL if no active traces. */
 251     int returnCode;             /* Completion code to return if current
 252                                  * procedure exits with TCL_RETURN code. */
 253     char *errorInfo;            /* Value to store in errorInfo if returnCode
 254                                  * is TCL_ERROR.  Malloc'ed, may be NULL */
 255     char *errorCode;            /* Value to store in errorCode if returnCode
 256                                  * is TCL_ERROR.  Malloc'ed, may be NULL */
 257
 258     /*
 259      * Information used by Tcl_AppendResult to keep track of partial
 260      * results.  See Tcl_AppendResult code for details.
 261      */
 262
 263     char *appendResult;         /* Storage space for results generated
 264                                  * by Tcl_AppendResult.  Malloc-ed.  NULL
 265                                  * means not yet allocated. */
 266     int appendAvl;              /* Total amount of space available at
 267                                  * partialResult. */
 268     int appendUsed;             /* Number of non-null bytes currently
 269                                  * stored at partialResult. */
 270
 271     /*
 272      * A cache of compiled regular expressions.  See Tcl_RegExpCompile
 273      * in tclUtil.c for details.  THIS CACHE IS OBSOLETE and is only
 274      * retained for backward compatibility with Tcl_RegExpCompile.
 275      * New code should use the object interface so the Tcl_Obj caches
 276      * the compiled expression.
 277      */
 278
 279 #define NUM_REGEXPS 5
 280     char *patterns[NUM_REGEXPS];/* Strings corresponding to compiled
 281                                  * regular expression patterns.  NULL
 282                                  * means that this slot isn't used.
 283                                  * Malloc-ed. */
 284     int patLengths[NUM_REGEXPS];/* Number of non-null characters in
 285                                  * corresponding entry in patterns.
 286                                  * -1 means entry isn't used. */
 287     TclRegexp *regexps[NUM_REGEXPS];
 288     /* Compiled forms of above strings.  Also
 289                                  * malloc-ed, or NULL if not in use yet. */
 290
 291     /*
 292      * Information about packages.  Used only in tclPkg.c.
 293      */
 294
 295     Tcl_HashTable packageTable; /* Describes all of the packages loaded
 296                                  * in or available to this interpreter.
 297                                  * Keys are package names, values are
 298                                  * (Package *) pointers. */
 299     char *packageUnknown;       /* Command to invoke during "package
 300                                  * require" commands for packages that
 301                                  * aren't described in packageTable.
 302                                  * Malloc'ed, may be NULL. */
 303
 304     /*
 305      * Miscellaneous information:
 306      */
 307
 308     int cmdCount;               /* Total number of times a command procedure
 309                                  * has been called for this interpreter. */
 310     int evalFlags;              /* Flags to control next call to Tcl_Eval.
 311                                  * Normally zero, but may be set before
 312                                  * calling Tcl_Eval.  See below for valid
 313                                  * values. */
 314     int termOffset;             /* Offset of character just after last one
 315                                  * compiled or executed by Tcl_EvalObj. */
 316     LiteralTable literalTable;  /* Contains LiteralEntry's describing all
 317                                  * Tcl objects holding literals of scripts
 318                                  * compiled by the interpreter. Indexed by
 319                                  * the string representations of literals.
 320                                  * Used to avoid creating duplicate
 321                                  * objects. */
 322     int compileEpoch;           /* Holds the current "compilation epoch"
 323                                  * for this interpreter. This is
 324                                  * incremented to invalidate existing
 325                                  * ByteCodes when, e.g., a command with a
 326                                  * compile procedure is redefined. */
 327     Proc *compiledProcPtr;      /* If a procedure is being compiled, a
 328                                  * pointer to its Proc structure; otherwise,
 329                                  * this is NULL. Set by ObjInterpProc in
 330                                  * tclProc.c and used by tclCompile.c to
 331                                  * process local variables appropriately. */
 332     char *scriptFile;           /* NULL means there is no nested source
 333                                  * command active;  otherwise this points to
 334                                  * the name of the file being sourced (it's
 335                                  * not malloc-ed:  it points to an argument
 336                                  * to Tcl_EvalFile. */
 337     int flags;                  /* Various flag bits.  See below. */
 338     long randSeed;              /* Seed used for rand() function. */
 339     Trace *tracePtr;            /* List of traces for this interpreter. */
 340     Tcl_HashTable *assocData;   /* Hash table for associating data with
 341                                  * this interpreter. Cleaned up when
 342                                  * this interpreter is deleted. */
 343     ExecEnv *execEnvPtr;        /* Execution environment for Tcl bytecode
 344                                  * execution. Contains a pointer to the
 345                                  * Tcl evaluation stack. */
 346     Tcl_Obj *emptyObjPtr;       /* Points to an object holding an empty
 347                                  * string. Returned by Tcl_ObjSetVar2 when
 348                                  * variable traces change a variable in a
 349                                  * gross way. */
 350     char resultSpace[TCL_RESULT_SIZE + 1];
 351     /* Static space holding small results. */
 352     Tcl_ThreadId threadId;      /* ID of thread that owns the interpreter */
 353
 354     /*
 355      * Statistical information about the bytecode compiler and interpreter's
 356      * operation.
 357      */
 358
 359 #ifdef TCL_COMPILE_STATS
 360     ByteCodeStats stats;        /* Holds compilation and execution
 361                                  * statistics for this interpreter. */
 362 #endif /* TCL_COMPILE_STATS */
 363 } Interp;
 364
 365 /*
 366  * EvalFlag bits for Interp structures:
 367  *
 368  * TCL_BRACKET_TERM     1 means that the current script is terminated by
 369  *                      a close bracket rather than the end of the string.
 370  * TCL_ALLOW_EXCEPTIONS 1 means it's OK for the script to terminate with
 371  *                      a code other than TCL_OK or TCL_ERROR;  0 means
 372  *                      codes other than these should be turned into errors.
 373  */
 374
 375 #define TCL_BRACKET_TERM          1
 376 #define TCL_ALLOW_EXCEPTIONS      4