Skip to content

Commit

Permalink
Improve in-code doc of some fields of structs in tcl.h and tclInt.h
Browse files Browse the repository at this point in the history
  • Loading branch information
@dkfellows
dkfellows committed Jul 23, 2024
1 parent 844f48a commit 44b21ce
Show file tree
Hide file tree
Showing 2 changed files with 71 additions and 39 deletions.
13 changes: 6 additions & 7 deletions generic/tcl.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -454,7 +454,7 @@ typedef void (Tcl_ThreadCreateProc) (void *clientData);
* Flags values passed to Tcl_RegExpExecObj.
*/

#define TCL_REG_NOTBOL 0001 /* Beginning of string does not match ^. */
#define TCL_REG_NOTBOL 0001 /* Beginning of string does not match ^. */
#define TCL_REG_NOTEOL 0002 /* End of string does not match $. */

/*
Expand Down Expand Up @@ -669,7 +669,7 @@ typedef struct Tcl_ObjType {
* to this type. Frees the internal rep of the
* old type. Returns TCL_ERROR on failure. */
#if TCL_MAJOR_VERSION > 8
size_t version;
size_t version; /* Version field for future-proofing. */

/* List emulation functions - ObjType Version 1 */
Tcl_ObjTypeLengthProc *lengthProc;
Expand Down Expand Up @@ -807,7 +807,7 @@ typedef struct Tcl_Namespace {
*/

typedef struct Tcl_CallFrame {
Tcl_Namespace *nsPtr;
Tcl_Namespace *nsPtr; /* Current namespace for the call frame. */
int dummy1;
Tcl_Size dummy2;
void *dummy3;
Expand Down Expand Up @@ -1292,7 +1292,7 @@ struct Tcl_Event {

typedef enum {
TCL_QUEUE_TAIL, TCL_QUEUE_HEAD, TCL_QUEUE_MARK,
TCL_QUEUE_ALERT_IF_EMPTY=4
TCL_QUEUE_ALERT_IF_EMPTY=4
} Tcl_QueuePosition;

/*
Expand Down Expand Up @@ -1688,7 +1688,7 @@ typedef struct Tcl_Filesystem {
* 'file attributes'. */
Tcl_FSFileAttrsSetProc *fileAttrsSetProc;
/* Called by 'Tcl_FSFileAttrsSet()' and by
* 'file attributes'. */
* 'file attributes'. */
Tcl_FSCreateDirectoryProc *createDirectoryProc;
/* Called by 'Tcl_FSCreateDirectory()'. May be
* NULL if the filesystem is read-only. */
Expand Down Expand Up @@ -1969,8 +1969,7 @@ typedef struct Tcl_EncodingType {
Tcl_EncodingConvertProc *fromUtfProc;
/* Function to convert from UTF-8 into
* external encoding. */
Tcl_FreeProc *freeProc;
/* If non-NULL, function to call when this
Tcl_FreeProc *freeProc; /* If non-NULL, function to call when this
* encoding is deleted. */
void *clientData; /* Arbitrary value associated with encoding
* type. Passed to conversion functions. */
Expand Down
97 changes: 65 additions & 32 deletions generic/tclInt.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -220,10 +220,11 @@ typedef struct NamespacePathEntry NamespacePathEntry;
*/

typedef struct TclVarHashTable {
Tcl_HashTable table;
struct Namespace *nsPtr;
Tcl_HashTable table; /* "Inherit" from Tcl_HashTable. */
struct Namespace *nsPtr; /* The namespace containing the variables. */
#if TCL_MAJOR_VERSION > 8
struct Var *arrayPtr;
struct Var *arrayPtr; /* The array containing the variables, if they
* are variables in an array at all. */
#endif /* TCL_MAJOR_VERSION > 8 */
} TclVarHashTable;

Expand Down Expand Up @@ -632,7 +633,7 @@ typedef struct Var {
} Var;

typedef struct VarInHash {
Var var;
Var var; /* "Inherit" from Var. */
Tcl_Size refCount; /* Counts number of active uses of this
* variable: 1 for the entry in the hash
* table, 1 for each additional variable whose
Expand Down Expand Up @@ -1123,6 +1124,7 @@ TclObjTypeLength(
Tcl_ObjTypeLengthProc *proc = TclObjTypeHasProc(objPtr, lengthProc);
return proc(objPtr);
}

static inline int
TclObjTypeIndex(
Tcl_Interp *interp,
Expand All @@ -1133,6 +1135,7 @@ TclObjTypeIndex(
Tcl_ObjTypeIndexProc *proc = TclObjTypeHasProc(objPtr, indexProc);
return proc(interp, objPtr, index, elemObjPtr);
}

static inline int
TclObjTypeSlice(
Tcl_Interp *interp,
Expand All @@ -1144,6 +1147,7 @@ TclObjTypeSlice(
Tcl_ObjTypeSliceProc *proc = TclObjTypeHasProc(objPtr, sliceProc);
return proc(interp, objPtr, fromIdx, toIdx, newObjPtr);
}

static inline int
TclObjTypeReverse(
Tcl_Interp *interp,
Expand All @@ -1153,6 +1157,7 @@ TclObjTypeReverse(
Tcl_ObjTypeReverseProc *proc = TclObjTypeHasProc(objPtr, reverseProc);
return proc(interp, objPtr, newObjPtr);
}

static inline int
TclObjTypeGetElements(
Tcl_Interp *interp,
Expand All @@ -1163,6 +1168,7 @@ TclObjTypeGetElements(
Tcl_ObjTypeGetElements *proc = TclObjTypeHasProc(objPtr, getElementsProc);
return proc(interp, objPtr, objCPtr, objVPtr);
}

static inline Tcl_Obj*
TclObjTypeSetElement(
Tcl_Interp *interp,
Expand All @@ -1174,6 +1180,7 @@ TclObjTypeSetElement(
Tcl_ObjTypeSetElement *proc = TclObjTypeHasProc(objPtr, setElementProc);
return proc(interp, objPtr, indexCount, indexArray, valueObj);
}

static inline int
TclObjTypeReplace(
Tcl_Interp *interp,
Expand All @@ -1186,6 +1193,7 @@ TclObjTypeReplace(
Tcl_ObjTypeReplaceProc *proc = TclObjTypeHasProc(objPtr, replaceProc);
return proc(interp, objPtr, first, numToDelete, numToInsert, insertObjs);
}

static inline int
TclObjTypeInOperator(
Tcl_Interp *interp,
Expand Down Expand Up @@ -1230,9 +1238,9 @@ typedef struct AssocData {
*/

typedef struct LocalCache {
Tcl_Size refCount;
Tcl_Size numVars;
Tcl_Obj *varName0;
Tcl_Size refCount; /* Reference count. */
Tcl_Size numVars; /* Number of variables. */
Tcl_Obj *varName0; /* First variable name. */
} LocalCache;

#define localName(framePtr, i) \
Expand Down Expand Up @@ -1293,12 +1301,14 @@ typedef struct CallFrame {
* have some means of discovering what the
* meaning of the value is, which we do not
* specify. */
LocalCache *localCachePtr;
LocalCache *localCachePtr; /* Pointer to the start of the cached variable
* names and initialisation data for local
* variables. */
Tcl_Obj *tailcallPtr; /* NULL if no tailcall is scheduled */
} CallFrame;

#define FRAME_IS_PROC 0x1
#define FRAME_IS_LAMBDA 0x2
#define FRAME_IS_PROC 0x1 /* Frame is a procedure body. */
#define FRAME_IS_LAMBDA 0x2 /* Frame is a lambda term body. */
#define FRAME_IS_METHOD 0x4 /* The frame is a method body, and the frame's
* clientData field contains a CallContext
* reference. Part of TIP#257. */
Expand Down Expand Up @@ -1339,7 +1349,7 @@ typedef struct CmdFrame {
int level; /* Number of frames in stack, prevent O(n)
* scan of list. */
Tcl_Size *line; /* Lines the words of the command start on. */
Tcl_Size nline;
Tcl_Size nline; /* Number of lines in CmdFrame.line. */
CallFrame *framePtr; /* Procedure activation record, may be
* NULL. */
struct CmdFrame *nextPtr; /* Link to calling frame. */
Expand Down Expand Up @@ -1569,18 +1579,34 @@ typedef int (CompileHookProc)(Tcl_Interp *interp,
struct CompileEnv *compEnvPtr, void *clientData);

/*
* The data structure for a (linked list of) execution stacks.
* The data structure for a (linked list of) execution stacks. Note that the
* first word on a particular execution stack is NULL, which is used as a
* marker to say "go to the previous stack in the list" when unwinding the
* stack.
*/

typedef struct ExecStack {
struct ExecStack *prevPtr;
struct ExecStack *nextPtr;
Tcl_Obj **markerPtr;
Tcl_Obj **endPtr;
Tcl_Obj **tosPtr;
struct ExecStack *prevPtr; /* Previous stack in list. */
struct ExecStack *nextPtr; /* Next stack in list. */
Tcl_Obj **markerPtr; /* The location of the NULL marker. */
Tcl_Obj **endPtr; /* Where the stack end is. */
Tcl_Obj **tosPtr; /* Where the stack top is. */
Tcl_Obj *stackWords[TCLFLEXARRAY];
/* The actual stack space, following this
* structure in memory. */
} ExecStack;

/*
* Saved copies of the stack frame references from the interpreter. Have to be
* restored into the interpreter to be used.
*/
typedef struct CorContext {
struct CallFrame *framePtr; /* See Interp.framePtr */
struct CallFrame *varFramePtr; /* See Interp.varFramePtr */
struct CmdFrame *cmdFramePtr; /* See Interp.cmdFramePtr */
Tcl_HashTable *lineLABCPtr; /* See Interp.lineLABCPtr */
} CorContext;

/*
* The data structure defining the execution environment for ByteCode's.
* There is one ExecEnv structure per Tcl interpreter. It holds the evaluation
Expand All @@ -1589,13 +1615,6 @@ typedef struct ExecStack {
* currently active execution stack.
*/

typedef struct CorContext {
struct CallFrame *framePtr;
struct CallFrame *varFramePtr;
struct CmdFrame *cmdFramePtr; /* See Interp.cmdFramePtr */
Tcl_HashTable *lineLABCPtr; /* See Interp.lineLABCPtr */
} CorContext;

typedef struct CoroutineData {
struct Command *cmdPtr; /* The command handle for the coroutine. */
struct ExecEnv *eePtr; /* The special execution environment (stacks,
Expand All @@ -1607,7 +1626,8 @@ typedef struct CoroutineData {
CorContext caller; /* Caller's saved execution context. */
CorContext running; /* This coroutine's saved execution context. */
Tcl_HashTable *lineLABCPtr; /* See Interp.lineLABCPtr */
void *stackLevel;
void *stackLevel; /* C stack frame reference. Used to try to
* ensure we don't overflow that stack. */
Tcl_Size auxNumLevels; /* While the coroutine is running the
* numLevels of the create/resume command is
* stored here; for suspended coroutines it
Expand All @@ -1626,11 +1646,14 @@ typedef struct ExecEnv {
ExecStack *execStackPtr; /* Points to the first item in the evaluation
* stack on the heap. */
Tcl_Obj *constants[2]; /* Pointers to constant "0" and "1" objs. */
struct Tcl_Interp *interp;
struct Tcl_Interp *interp; /* Owning interpreter. */
struct NRE_callback *callbackPtr;
/* Top callback in NRE's stack. */
struct CoroutineData *corPtr;
int rewind;
/* Current coroutine. */
int rewind; /* Set when exception trapping is disabled
* because a context is being deleted (e.g.,
* the current coroutine has been deleted). */
} ExecEnv;

#define COR_IS_SUSPENDED(corPtr) \
Expand Down Expand Up @@ -1978,6 +2001,8 @@ typedef struct Interp {
* per-interp basis. */
#if TCL_MAJOR_VERSION > 8
void (*optimizer)(void *envPtr);
/* Reference to the bytecode optimizer, if one
* is set. */
#else
union {
void (*optimizer)(void *envPtr);
Expand Down Expand Up @@ -2256,7 +2281,7 @@ typedef struct Interp {
* They are used by the macros defined below.
*/

AllocCache *allocCache;
AllocCache *allocCache; /* Allocator cache for stack frames. */
void *pendingObjDataPtr; /* Pointer to the Cache and PendingObjData
* structs for this interp's thread; see
* tclObj.c and tclThreadAlloc.c */
Expand Down Expand Up @@ -2291,9 +2316,9 @@ typedef struct Interp {
* over the default error messages returned by
* a script cancellation operation. */

/*
* TIP #348 IMPLEMENTATION - Substituted error stack
*/
/*
* TIP #348 IMPLEMENTATION - Substituted error stack
*/
Tcl_Obj *errorStack; /* [info errorstack] value (as a Tcl_Obj). */
Tcl_Obj *upLiteral; /* "UP" literal for [info errorstack] */
Tcl_Obj *callLiteral; /* "CALL" literal for [info errorstack] */
Expand Down Expand Up @@ -2986,6 +3011,7 @@ typedef struct ProcessGlobalValue {
*
*----------------------------------------------------------------------
*/

static inline Tcl_Size
TclUpsizeAlloc(
TCL_UNUSED(Tcl_Size), /* oldSize. For future experiments with
Expand All @@ -3001,6 +3027,7 @@ TclUpsizeAlloc(
return limit;
}
}

static inline Tcl_Size
TclUpsizeRetry(
Tcl_Size needed,
Expand All @@ -3014,6 +3041,7 @@ TclUpsizeRetry(
return needed;
}
}

MODULE_SCOPE void * TclAllocElemsEx(Tcl_Size elemCount, Tcl_Size elemSize,
Tcl_Size leadSize, Tcl_Size *capacityPtr);
MODULE_SCOPE void * TclReallocElemsEx(void *oldPtr, Tcl_Size elemCount,
Expand All @@ -3022,6 +3050,7 @@ MODULE_SCOPE void * TclReallocElemsEx(void *oldPtr, Tcl_Size elemCount,
MODULE_SCOPE void * TclAttemptReallocElemsEx(void *oldPtr,
Tcl_Size elemCount, Tcl_Size elemSize,
Tcl_Size leadSize, Tcl_Size *capacityPtr);

/* Alloc elemCount elements of size elemSize with leadSize header
* returning actual capacity (in elements) in *capacityPtr. */
static inline void *
Expand All @@ -3034,6 +3063,7 @@ TclAttemptAllocElemsEx(
return TclAttemptReallocElemsEx(
NULL, elemCount, elemSize, leadSize, capacityPtr);
}

/* Alloc numByte bytes, returning actual capacity in *capacityPtr. */
static inline void *
TclAllocEx(
Expand All @@ -3042,6 +3072,7 @@ TclAllocEx(
{
return TclAllocElemsEx(numBytes, 1, 0, capacityPtr);
}

/* Alloc numByte bytes, returning actual capacity in *capacityPtr. */
static inline void *
TclAttemptAllocEx(
Expand All @@ -3050,6 +3081,7 @@ TclAttemptAllocEx(
{
return TclAttemptAllocElemsEx(numBytes, 1, 0, capacityPtr);
}

/* Realloc numByte bytes, returning actual capacity in *capacityPtr. */
static inline void *
TclReallocEx(
Expand All @@ -3059,6 +3091,7 @@ TclReallocEx(
{
return TclReallocElemsEx(oldPtr, numBytes, 1, 0, capacityPtr);
}

/* Realloc numByte bytes, returning actual capacity in *capacityPtr. */
static inline void *
TclAttemptReallocEx(
Expand Down Expand Up @@ -3659,7 +3692,7 @@ MODULE_SCOPE double TclpWideClickInMicrosec(void);
((double)(clicks) * TclpWideClickInMicrosec() * 1000)
# endif
#endif
MODULE_SCOPE long long TclpGetMicroseconds(void);
MODULE_SCOPE long long TclpGetMicroseconds(void);

MODULE_SCOPE int TclZlibInit(Tcl_Interp *interp);
MODULE_SCOPE void * TclpThreadCreateKey(void);
Expand Down

0 comments on commit 44b21ce

Please sign in to comment.