diff options
Diffstat (limited to 'generic/tclInt.h')
| -rw-r--r-- | generic/tclInt.h | 215 |
1 files changed, 113 insertions, 102 deletions
diff --git a/generic/tclInt.h b/generic/tclInt.h index 7551956..67ba634 100644 --- a/generic/tclInt.h +++ b/generic/tclInt.h @@ -15,14 +15,14 @@ * See the file "license.terms" for information on usage and redistribution of * this file, and for a DISCLAIMER OF ALL WARRANTIES. * - * RCS: @(#) $Id: tclInt.h,v 1.411 2009/01/05 09:48:11 dkf Exp $ + * RCS: @(#) $Id: tclInt.h,v 1.412 2009/01/06 09:49:39 dkf Exp $ */ #ifndef _TCLINT #define _TCLINT /* - * Some numerics configuration options + * Some numerics configuration options. */ #undef NO_WIDE_TYPE @@ -274,9 +274,9 @@ typedef struct Namespace { * is currently allocated. */ int cmdRefEpoch; /* Incremented if a newly added command * shadows a command for which this namespace - * has already cached a Command * pointer; - * this causes all its cached Command* - * pointers to be invalidated. */ + * has already cached a Command* pointer; this + * causes all its cached Command* pointers to + * be invalidated. */ int resolverEpoch; /* Incremented whenever (a) the name * resolution rules change for this namespace * or (b) a newly added command shadows a @@ -654,7 +654,7 @@ typedef struct VarInHash { #define VAR_ALL_HASH \ (VAR_IN_HASHTABLE|VAR_DEAD_HASH|VAR_NAMESPACE_VAR|VAR_ARRAY_ELEMENT) -/* Trace and search state */ +/* Trace and search state. */ #define VAR_TRACED_READ 0x10 /* TCL_TRACE_READS */ #define VAR_TRACED_WRITE 0x20 /* TCL_TRACE_WRITES */ @@ -665,7 +665,7 @@ typedef struct VarInHash { #define VAR_ALL_TRACES \ (VAR_TRACED_READ|VAR_TRACED_WRITE|VAR_TRACED_ARRAY|VAR_TRACED_UNSET) -/* Special handling on initialisation (only CompiledLocal) */ +/* Special handling on initialisation (only CompiledLocal). */ #define VAR_ARGUMENT 0x100 /* KEEP OLD VALUE! See tclProc.c */ #define VAR_TEMPORARY 0x200 /* KEEP OLD VALUE! See tclProc.c */ #define VAR_IS_ARGS 0x400 @@ -781,7 +781,7 @@ typedef struct VarInHash { ((VarInHash *) (varPtr))->refCount /* - * Macros for direct variable access by TEBC + * Macros for direct variable access by TEBC. */ #define TclIsVarDirectReadable(varPtr) \ @@ -919,9 +919,9 @@ typedef struct Trace { ClientData clientData; /* Arbitrary value to pass to proc. */ struct Trace *nextPtr; /* Next in list of traces for this interp. */ int flags; /* Flags governing the trace - see - * Tcl_CreateObjTrace for details */ + * Tcl_CreateObjTrace for details. */ Tcl_CmdObjTraceDeleteProc *delProc; - /* Procedure to call when trace is deleted */ + /* Procedure to call when trace is deleted. */ } Trace; /* @@ -1093,15 +1093,15 @@ typedef struct CmdFrame { */ int type; /* Values see below. */ - int level; /* #Frames in stack, prevent O(n) scan of - * list. */ - int numLevels; /* value of interp's numLevels when the frame - * was pushed */ + int level; /* Number of frames in stack, prevent O(n) + * scan of list. */ + int numLevels; /* Value of interp's numLevels when the frame + * was pushed. */ int *line; /* Lines the words of the command start on. */ int nline; CallFrame *framePtr; /* Procedure activation record, may be * NULL. */ - struct CmdFrame *nextPtr; /* Link to calling frame */ + struct CmdFrame *nextPtr; /* Link to calling frame. */ /* * Data needed for Eval vs TEBC @@ -1139,27 +1139,28 @@ typedef struct CmdFrame { * in. */ } eval; struct { - const void *codePtr;/* Byte code currently executed */ - const char *pc; /* and instruction pointer. */ + const void *codePtr;/* Byte code currently executed... */ + const char *pc; /* ... and instruction pointer. */ } tebc; } data; union { struct { - const char *cmd; /* The executed command, if possible */ - int len; /* And its length */ + const char *cmd; /* The executed command, if possible... */ + int len; /* ... and its length. */ } str; - Tcl_Obj *listPtr; /* Tcl_EvalObjEx, cmd list */ + Tcl_Obj *listPtr; /* Tcl_EvalObjEx, cmd list. */ } cmd; } CmdFrame; typedef struct CFWord { - CmdFrame *framePtr; /* CmdFrame to acess */ - int word; /* Index of the word in the command */ - int refCount; /* #times the word is on the stack */ + CmdFrame *framePtr; /* CmdFrame to access. */ + int word; /* Index of the word in the command. */ + int refCount; /* Number of times the word is on the + * stack. */ } CFWord; typedef struct ExtIndex { - Tcl_Obj *obj; /* Reference to the word */ + Tcl_Obj *obj; /* Reference to the word. */ int pc; /* Instruction pointer of a command in * ExtCmdLoc.loc[.] */ int word; /* Index of word in @@ -1167,9 +1168,10 @@ typedef struct ExtIndex { } ExtIndex; typedef struct CFWordBC { - CmdFrame *framePtr; /* CmdFrame to acess */ - ExtIndex *eiPtr; /* Word info: PC and index */ - int refCount; /* #times the word is on the stack */ + CmdFrame *framePtr; /* CmdFrame to access. */ + ExtIndex *eiPtr; /* Word info: PC and index. */ + int refCount; /* Number of times the word is on the + * stack. */ } CFWordBC; /* @@ -1190,15 +1192,15 @@ typedef struct CFWordBC { * types, per the context of the byte code in execution. */ -#define TCL_LOCATION_EVAL (0) /* Location in a dynamic eval script */ +#define TCL_LOCATION_EVAL (0) /* Location in a dynamic eval script. */ #define TCL_LOCATION_EVAL_LIST (1) /* Location in a dynamic eval script, - * list-path */ -#define TCL_LOCATION_BC (2) /* Location in byte code */ + * list-path. */ +#define TCL_LOCATION_BC (2) /* Location in byte code. */ #define TCL_LOCATION_PREBC (3) /* Location in precompiled byte code, no - * location */ -#define TCL_LOCATION_SOURCE (4) /* Location in a file */ -#define TCL_LOCATION_PROC (5) /* Location in a dynamic proc */ -#define TCL_LOCATION_LAST (6) /* Number of values in the enum */ + * location. */ +#define TCL_LOCATION_SOURCE (4) /* Location in a file. */ +#define TCL_LOCATION_PROC (5) /* Location in a dynamic proc. */ +#define TCL_LOCATION_LAST (6) /* Number of values in the enum. */ /* * Structure passed to describe procedure-like "procedures" that are not @@ -1335,16 +1337,21 @@ typedef struct CorContext { } CorContext; typedef struct CoroutineData { - struct Command *cmdPtr; - struct ExecEnv *eePtr; - struct ExecEnv *callerEEPtr; + struct Command *cmdPtr; /* The command handle for the coroutine. */ + struct ExecEnv *eePtr; /* The special execution environment (stacks, + * etc.) for the coroutine. */ + struct ExecEnv *callerEEPtr;/* The execution environment for the caller of + * the coroutine, which might be the + * interpreter global environment or another + * coroutine. */ CorContext caller; CorContext running; CorContext base; int *stackLevel; - int auxNumLevels; /* While the coroutine is running the numLevels of the - * create/resume command is stored here; for suspended - * coroutines it holds the nesting numLevels at yield*/ + int auxNumLevels; /* While the coroutine is running the + * numLevels of the create/resume command is + * stored here; for suspended coroutines it + * holds the nesting numLevels at yield. */ } CoroutineData; typedef struct ExecEnv { @@ -1353,7 +1360,7 @@ typedef struct ExecEnv { Tcl_Obj *constants[2]; /* Pointers to constant "0" and "1" objs. */ struct Tcl_Interp *interp; struct TEOV_callback *callbackPtr; - /* Top callback in TEOV's stack */ + /* Top callback in TEOV's stack. */ struct CoroutineData *corPtr; struct BottomData *bottomPtr; int rewind; @@ -1451,15 +1458,16 @@ typedef struct ByteCodeStats { /* * Structure used in implementation of those core ensembles which are - * partially compiled. + * partially compiled. Used as an array of these, with a terminating field + * whose 'name' is NULL. */ typedef struct { - const char *name; /* The name of the subcommand */ - Tcl_ObjCmdProc *proc; /* The implementation of the subcommand */ - CompileProc *compileProc; /* The compiler for the subcommand */ - Tcl_ObjCmdProc *nreProc; /* NRE implementation of this command */ - ClientData clientData; /* Any clientData to give the command */ + const char *name; /* The name of the subcommand. */ + Tcl_ObjCmdProc *proc; /* The implementation of the subcommand. */ + CompileProc *compileProc; /* The compiler for the subcommand. */ + Tcl_ObjCmdProc *nreProc; /* NRE implementation of this command. */ + ClientData clientData; /* Any clientData to give the command. */ } EnsembleImplMap; /* @@ -1552,7 +1560,7 @@ typedef struct Command { * command. */ CommandTrace *tracePtr; /* First in list of all traces set for this * command. */ - Tcl_ObjCmdProc *nreProc; /* NRE implementation of this command */ + Tcl_ObjCmdProc *nreProc; /* NRE implementation of this command. */ } Command; /* @@ -1638,10 +1646,10 @@ enum PkgPreferOptions { */ typedef struct AllocCache { - struct Cache *nextPtr; /* Linked list of cache entries */ + struct Cache *nextPtr; /* Linked list of cache entries. */ Tcl_ThreadId owner; /* Which thread's cache is this? */ - Tcl_Obj *firstObjPtr; /* List of free objects for thread */ - int numObjects; /* Number of objects for thread */ + Tcl_Obj *firstObjPtr; /* List of free objects for thread. */ + int numObjects; /* Number of objects for thread. */ } AllocCache; /* @@ -1726,10 +1734,11 @@ typedef struct Interp { ActiveVarTrace *activeVarTracePtr; /* First in list of active traces for interp, * or NULL if no active traces. */ - int returnCode; /* [return -code] parameter */ - CallFrame *rootFramePtr; /* Global frame pointer for this interpreter */ + int returnCode; /* [return -code] parameter. */ + CallFrame *rootFramePtr; /* Global frame pointer for this + * interpreter. */ Namespace *lookupNsPtr; /* Namespace to use ONLY on the next - * TCL_EVAL_INVOKE call to Tcl_EvalObjv */ + * TCL_EVAL_INVOKE call to Tcl_EvalObjv. */ /* * Information used by Tcl_AppendResult to keep track of partial results. @@ -1809,7 +1818,7 @@ typedef struct Interp { Tcl_Obj *objResultPtr; /* If the last command returned an object * result, this points to it. Should not be * accessed directly; see comment above. */ - Tcl_ThreadId threadId; /* ID of thread that owns the interpreter */ + Tcl_ThreadId threadId; /* ID of thread that owns the interpreter. */ ActiveCommandTrace *activeCmdTracePtr; /* First in list of active command traces for @@ -1818,19 +1827,22 @@ typedef struct Interp { /* First in list of active traces for interp, * or NULL if no active traces. */ - int tracesForbiddingInline; /* Count of traces (in the list headed by + int tracesForbiddingInline; /* Count of traces (in the list headed by * tracePtr) that forbid inline bytecode - * compilation */ + * compilation. */ + + /* + * Fields used to manage extensible return options (TIP 90). + */ - /* Fields used to manage extensible return options (TIP 90) */ Tcl_Obj *returnOpts; /* A dictionary holding the options to the - * last [return] command */ + * last [return] command. */ - Tcl_Obj *errorInfo; /* errorInfo value (now as a Tcl_Obj) */ - Tcl_Obj *eiVar; /* cached ref to ::errorInfo variable */ - Tcl_Obj *errorCode; /* errorCode value (now as a Tcl_Obj) */ - Tcl_Obj *ecVar; /* cached ref to ::errorInfo variable */ - int returnLevel; /* [return -level] parameter */ + Tcl_Obj *errorInfo; /* errorInfo value (now as a Tcl_Obj). */ + Tcl_Obj *eiVar; /* cached ref to ::errorInfo variable. */ + Tcl_Obj *errorCode; /* errorCode value (now as a Tcl_Obj). */ + Tcl_Obj *ecVar; /* cached ref to ::errorInfo variable. */ + int returnLevel; /* [return -level] parameter. */ /* * Resource limiting framework support (TIP#143). @@ -1888,7 +1900,7 @@ typedef struct Interp { } ensembleRewrite; /* - * TIP #219 ... Global info for the I/O system ... + * TIP #219: Global info for the I/O system. */ Tcl_Obj *chanMsg; /* Error message set by channel drivers, for @@ -1910,7 +1922,10 @@ typedef struct Interp { * over the default error messages returned by * a script cancellation operation. */ - /* TIP #280 */ + /* + * Source code origin information (TIP #280). + */ + CmdFrame *cmdFramePtr; /* Points to the command frame containing the * location information for the current * command. */ @@ -1954,13 +1969,13 @@ typedef struct Interp { int packagePrefer; /* Current package selection mode. */ /* - * Hashtables for variable traces and searches + * Hashtables for variable traces and searches. */ Tcl_HashTable varTraces; /* Hashtable holding the start of a variable's * active trace list; varPtr is the key. */ Tcl_HashTable varSearches; /* Hashtable holding the start of a variable's - * active searches list; varPtr is the key */ + * active searches list; varPtr is the key. */ /* * The thread-specific data ekeko: cache pointers or values that * (a) do not change during the thread's lifetime @@ -2135,9 +2150,10 @@ struct LimitHandler { /* The handler callback. */ ClientData clientData; /* Opaque argument to the handler callback. */ Tcl_LimitHandlerDeleteProc *deleteProc; - /* How to delete the clientData */ - LimitHandler *prevPtr; /* Previous item in linked list of handlers */ - LimitHandler *nextPtr; /* Next item in linked list of handlers */ + /* How to delete the clientData. */ + LimitHandler *prevPtr; /* Previous item in linked list of + * handlers. */ + LimitHandler *nextPtr; /* Next item in linked list of handlers. */ }; /* @@ -2163,7 +2179,7 @@ struct LimitHandler { /* * This macro is used to properly align the memory allocated by Tcl, giving - * the same alignment as the native malloc + * the same alignment as the native malloc. */ #if defined(__APPLE__) @@ -2203,7 +2219,7 @@ typedef enum { /* * The following enum values are used to indicate the translation of a Tcl * channel. Declared here so that each platform can define - * TCL_PLATFORM_TRANSLATION to the native translation on that platform + * TCL_PLATFORM_TRANSLATION to the native translation on that platform. */ typedef enum TclEolTranslation { @@ -2450,19 +2466,21 @@ typedef struct ProcessGlobalValue { */ #define TCL_PARSE_DECIMAL_ONLY 1 - /* Leading zero doesn't denote octal or hex */ + /* Leading zero doesn't denote octal or + * hex. */ #define TCL_PARSE_OCTAL_ONLY 2 - /* Parse octal even without prefix */ + /* Parse octal even without prefix. */ #define TCL_PARSE_HEXADECIMAL_ONLY 4 - /* Parse hexadecimal even without prefix */ + /* Parse hexadecimal even without prefix. */ #define TCL_PARSE_INTEGER_ONLY 8 - /* Disable floating point parsing */ + /* Disable floating point parsing. */ #define TCL_PARSE_SCAN_PREFIXES 16 - /* Use [scan] rules dealing with 0? prefixes */ + /* Use [scan] rules dealing with 0? + * prefixes. */ #define TCL_PARSE_NO_WHITESPACE 32 - /* Reject leading/trailing whitespace */ + /* Reject leading/trailing whitespace. */ #define TCL_PARSE_BINARY_ONLY 64 - /* Parse binary even without prefix */ + /* Parse binary even without prefix. */ /* *---------------------------------------------------------------------- @@ -2609,7 +2627,7 @@ MODULE_SCOPE void TclCleanupLiteralTable(Tcl_Interp *interp, LiteralTable *tablePtr); MODULE_SCOPE int TclDoubleDigits(char *buf, double value, int *signum); MODULE_SCOPE void TclDeleteNamespaceVars(Namespace *nsPtr); -/* TIP #280 - Modified token based evulation, with line information */ +/* TIP #280 - Modified token based evulation, with line information. */ MODULE_SCOPE int TclEvalEx(Tcl_Interp *interp, const char *script, int numBytes, int flags, int line); MODULE_SCOPE int TclFileAttrsCmd(Tcl_Interp *interp, @@ -3502,7 +3520,7 @@ typedef const char* TclDTraceStr; * Invalidate the string rep first so we can use the bytes value for our * pointer chain, and signal an obj deletion (as opposed to shimmering) with * 'length == -1'. - * Use empty 'if ; else' to handle use in unbraced outer if/else conditions + * Use empty 'if ; else' to handle use in unbraced outer if/else conditions. */ # define TclDecrRefCount(objPtr) \ @@ -3527,7 +3545,7 @@ typedef const char* TclDTraceStr; * The PURIFY mode is like the regular mode, but instead of doing block * Tcl_Obj allocation and keeping a freed list for efficiency, it always * allocates and frees a single Tcl_Obj so that tools like Purify can better - * track memory leaks + * track memory leaks. */ # define TclAllocObjStorageEx(interp, objPtr) \ @@ -4008,7 +4026,7 @@ MODULE_SCOPE void TclBNInitBignumFromWideUInt(mp_int *bignum, /* *---------------------------------------------------------------- - * Inline version of Tcl_GetCurrentNamespace and Tcl_GetGlobalNamespace + * Inline version of Tcl_GetCurrentNamespace and Tcl_GetGlobalNamespace. */ #define TclGetCurrentNamespace(interp) \ @@ -4052,11 +4070,11 @@ MODULE_SCOPE void TclBNInitBignumFromWideUInt(mp_int *bignum, ? 1 : 0))) /* - * Compile-time assertions: these produce a compile time error if - * the expression is not known to be true at compile time. - * If the assertion is known to be false, the compiler (or optimizer?) will - * error out with "division by zero". If the assertion cannot be evaluated at - * compile time, the compiler will error out with "non-static initializer". + * Compile-time assertions: these produce a compile time error if the + * expression is not known to be true at compile time. If the assertion is + * known to be false, the compiler (or optimizer?) will error out with + * "division by zero". If the assertion cannot be evaluated at compile time, + * the compiler will error out with "non-static initializer". * * Adapted with permission from * http://www.pixelbeat.org/programming/gcc/static_assert.html @@ -4139,24 +4157,17 @@ typedef struct TEOV_callback { #define TOP_CB(iPtr) (((Interp *)(iPtr))->execEnvPtr->callbackPtr) /* - * Inline version of Tcl_NRAddCallback + * Inline version of Tcl_NRAddCallback. */ -#define TclNRAddCallback( \ - interp, \ - postProcPtr, \ - data0, \ - data1, \ - data2, \ - data3) \ - { \ +#define TclNRAddCallback(interp,postProcPtr,data0,data1,data2,data3) { \ TEOV_callback *callbackPtr; \ TCLNR_ALLOC((interp), (callbackPtr)); \ callbackPtr->procPtr = (postProcPtr); \ - callbackPtr->data[0] = (ClientData)(data0);\ - callbackPtr->data[1] = (ClientData)(data1);\ - callbackPtr->data[2] = (ClientData)(data2);\ - callbackPtr->data[3] = (ClientData)(data3);\ + callbackPtr->data[0] = (ClientData)(data0); \ + callbackPtr->data[1] = (ClientData)(data1); \ + callbackPtr->data[2] = (ClientData)(data2); \ + callbackPtr->data[3] = (ClientData)(data3); \ callbackPtr->nextPtr = TOP_CB(interp); \ TOP_CB(interp) = callbackPtr; \ } |