Attachment "alloc.patch" to
ticket [497459ffff]
added by
dgp
2002-01-05 00:47:07.
Index: ChangeLog
===================================================================
RCS file: /cvsroot/tcl/tcl/ChangeLog,v
retrieving revision 1.778
diff -u -r1.778 ChangeLog
--- ChangeLog 2002/01/04 15:43:45 1.778
+++ ChangeLog 2002/01/04 17:44:59
@@ -1,5 +1,21 @@
2002-01-04 Don Porter <[email protected]>
+ * doc/Alloc.3:
+ * doc/Concat.3:
+ * doc/CrtMathFnc.3:
+ * doc/Hash.3:
+ * doc/Interp.3:
+ * doc/LinkVar.3:
+ * doc/ObjectType.3:
+ * doc/PkgRequire.3:
+ * doc/Preserve.3:
+ * doc/SetResult.3:
+ * doc/SplitList.3:
+ * doc/SplitPath.3:
+ * doc/TCL_MEM_DEBUG.3: Updated documentation to describe the ckalloc,
+ ckfree, ckrealloc, attemptckalloc, and attemptckrealloc macros, and
+ to accurately describe when and how they are used. [Bug 497459]
+
* generic/tclThreadJoin.c (TclRememberJoinableThread,TclJoinThread):
Replaced Tcl_Alloc and Tcl_Free calls with ckalloc and ckfree so that
memory debugging is supported.
Index: doc/Alloc.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/Alloc.3,v
retrieving revision 1.5
diff -u -r1.5 Alloc.3
--- doc/Alloc.3 2001/04/06 23:14:08 1.5
+++ doc/Alloc.3 2002/01/04 17:44:59
@@ -10,7 +10,7 @@
.TH Tcl_Alloc 3 7.5 Tcl "Tcl Library Procedures"
.BS
.SH NAME
-Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc \- allocate or free heap memory
+Tcl_Alloc, Tcl_Free, Tcl_Realloc, Tcl_AttemptAlloc, Tcl_AttemptRealloc, ckalloc, ckfree, ckrealloc, attemptckalloc, attemptckrealloc \- allocate or free heap memory
.SH SYNOPSIS
.nf
\fB#include <tcl.h>\fR
@@ -18,6 +18,7 @@
char *
\fBTcl_Alloc\fR(\fIsize\fR)
.sp
+void
\fBTcl_Free\fR(\fIptr\fR)
.sp
char *
@@ -28,6 +29,21 @@
.sp
char *
\fBTcl_AttemptRealloc\fR(\fIptr, size\fR)
+.sp
+char *
+\fBckalloc\fR(\fIsize\fR)
+.sp
+void
+\fBckfree\fR(\fIptr\fR)
+.sp
+char *
+\fBckrealloc\fR(\fIptr, size\fR)
+.sp
+char *
+\fBattemptckalloc\fR(\fIsize\fR)
+.sp
+char *
+\fBattemptckrealloc\fR(\fIptr, size\fR)
.SH ARGUMENTS
.AS char *size
.AP int size in
@@ -60,5 +76,15 @@
\fBTcl_AttemptAlloc\fR and \fBTcl_AttemptRealloc\fR will not cause the Tcl
interpreter to \fBpanic\fR if the memory allocation fails. If the
allocation fails, these functions will return NULL.
+.PP
+The procedures \fBckalloc\fR, \fBckfree\fR, \fBckrealloc\fR,
+\fBattemptckalloc\fR, and \fBattemptckrealloc\fR are implemented
+as macros. Normally, they are synonyms for the correponding
+procedures documented on this page. When Tcl and all modules
+calling Tcl are compiled with \fBTCL_MEM_DEBUG\fR defined, however,
+these macros are redefined to be special debugging versions of
+of these procedures. To support Tcl's memory debugging within a
+module, use the macros rather than direct calls to \fBTcl_Alloc\fR, etc.
+
.SH KEYWORDS
-alloc, allocation, free, malloc, memory, realloc
+alloc, allocation, free, malloc, memory, realloc, TCL_MEM_DEBUG
Index: doc/Concat.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/Concat.3,v
retrieving revision 1.3
diff -u -r1.3 Concat.3
--- doc/Concat.3 2001/09/24 21:10:32 1.3
+++ doc/Concat.3 2002/01/04 17:44:59
@@ -45,8 +45,8 @@
.PP
.VS
The result string is dynamically allocated
-using \fBTcl_Alloc\fR; the caller must eventually release the space
-by calling \fBTcl_Free\fR.
+using \fBckalloc\fR; the caller must eventually release the space
+by calling \fBckfree\fR.
.VE
.VS
.SH "SEE ALSO"
Index: doc/CrtMathFnc.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/CrtMathFnc.3,v
retrieving revision 1.5
diff -u -r1.5 CrtMathFnc.3
--- doc/CrtMathFnc.3 2001/05/30 08:57:05 1.5
+++ doc/CrtMathFnc.3 2002/01/04 17:44:59
@@ -49,7 +49,7 @@
.AP Tcl_ValueType *argTypesPtr out
Points to a variable that will be set to contain a pointer to an array
giving the permissible types for each argument to the function which
-will need to be freed up using \fITcl_Free\fR.
+will need to be freed up using \fIckfree\fR.
.AP Tcl_MathProc *procPtr out
Points to a variable that will be set to contain a pointer to the
implementation code for the function (or NULL if the function is
@@ -128,7 +128,7 @@
.PP
If an error did not occur, the array reference placed in the variable
pointed to by \fIargTypesPtr\fR is newly allocated, and should be
-released by passing it to \fBTcl_Free\fR. Some functions (the
+released by passing it to \fBckfree\fR. Some functions (the
standard set implemented in the core) are implemented directly at the
bytecode level; attempting to retrieve values for them causes a NULL
to be stored in the variable pointed to by \fIprocPtr\fR and the
@@ -145,4 +145,4 @@
expression, mathematical function
.SH "SEE ALSO"
-expr(n), info(n), Tcl_Free(3), Tcl_NewListObj(3)
+expr(n), info(n), ckfree(3), Tcl_NewListObj(3)
Index: doc/Hash.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/Hash.3,v
retrieving revision 1.8
diff -u -r1.8 Hash.3
--- doc/Hash.3 2001/01/18 19:09:55 1.8
+++ doc/Hash.3 2002/01/04 17:44:59
@@ -283,7 +283,7 @@
typedef Tcl_HashEntry *(Tcl_AllocHashEntryProc) (
Tcl_HashTable *\fItablePtr\fR, VOID *\fIkeyPtr\fR);
.CE
-If this is NULL then Tcl_Alloc is used to allocate enough space for a
+If this is NULL then \fBckalloc\fR is used to allocate enough space for a
Tcl_HashEntry and the key pointer is assigned to key.oneWordValue.
String keys and array keys use this function to allocate enough
space for the entry and the key in one block, rather than doing
@@ -298,7 +298,7 @@
.CS
typedef void (Tcl_FreeHashEntryProc) (Tcl_HashEntry *\fIhPtr\fR);
.CE
-If this is NULL then Tcl_Free is used to free the space for the
+If this is NULL then \fBckfree\fR is used to free the space for the
entry. Tcl_Obj * keys use this function to decrement the
reference count on the object.
.SH KEYWORDS
Index: doc/Interp.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/Interp.3,v
retrieving revision 1.3
diff -u -r1.3 Interp.3
--- doc/Interp.3 2000/04/14 23:01:51 1.3
+++ doc/Interp.3 2002/01/04 17:44:59
@@ -60,12 +60,12 @@
.VS
In this case, the \fIfreeProc\fR field must be zero.
Alternatively, a command procedure may dynamically
-allocate its return value (e.g. using \fBTcl_Alloc\fR)
+allocate its return value (e.g. using \fBTcl_Alloc\fR or \fBckalloc\fR)
and store a pointer to it in \fIinterp->result\fR.
In this case, the command procedure must also set \fIinterp->freeProc\fR
to the address of a procedure that can free the value, or \fBTCL_DYNAMIC\fR
if the storage was allocated directly by Tcl or by a call to
-\fBTcl_Alloc\fR.
+\fBTcl_Alloc\fR or \fBckalloc\fR.
.VE
If \fIinterp->freeProc\fR is non-zero, then Tcl will call \fIfreeProc\fR
to free the space pointed to by \fIinterp->result\fR before it
Index: doc/LinkVar.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/LinkVar.3,v
retrieving revision 1.3
diff -u -r1.3 LinkVar.3
--- doc/LinkVar.3 2000/04/14 23:01:51 1.3
+++ doc/LinkVar.3 2002/01/04 17:45:00
@@ -84,7 +84,7 @@
The C variable is of type \fBchar *\fR.
.VS
If its value is not null then it must be a pointer to a string
-allocated with \fBTcl_Alloc\fR.
+allocated with \fBTcl_Alloc\fR or \fBckalloc\fR.
.VE
Whenever the Tcl variable is modified the current C string will be
freed and new memory will be allocated to hold a copy of the variable's
Index: doc/ObjectType.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/ObjectType.3,v
retrieving revision 1.4
diff -u -r1.4 ObjectType.3
--- doc/ObjectType.3 2001/10/22 17:25:14 1.4
+++ doc/ObjectType.3 2002/01/04 17:45:00
@@ -147,8 +147,8 @@
to have a null after the last byte, at offset \fIlength\fR;
this allows string representations that do not contain null bytes
to be treated as conventional null character-terminated C strings.
-Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR.
-Note that \fIupdateStringProc\fRs must allocate
+Storage for the byte array must be allocated in the heap by \fBTcl_Alloc\fR
+or \fBckalloc\fR. Note that \fIupdateStringProc\fRs must allocate
enough storage for the string's bytes and the terminating null byte.
The \fIupdateStringProc\fR for Tcl's builtin list type, for example,
builds an array of strings for each element object
Index: doc/PkgRequire.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/PkgRequire.3,v
retrieving revision 1.5
diff -u -r1.5 PkgRequire.3
--- doc/PkgRequire.3 2001/04/04 16:07:20 1.5
+++ doc/PkgRequire.3 2002/01/04 17:45:00
@@ -33,7 +33,7 @@
int
\fBTcl_PkgProvideEx\fR(\fIinterp, name, version, clientData\fR)
.SH ARGUMENTS
-.AS Tcl_FreeProc clientDataPtr
+.AS ClientData clientDataPtr
.AP Tcl_Interp *interp in
Interpreter where package is needed or available.
.AP "CONST char" *name in
Index: doc/Preserve.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/Preserve.3,v
retrieving revision 1.3
diff -u -r1.3 Preserve.3
--- doc/Preserve.3 2001/12/13 00:58:26 1.3
+++ doc/Preserve.3 2002/01/04 17:45:00
@@ -91,8 +91,8 @@
.PP
When the \fIclientData\fR argument to \fBTcl_EventuallyFree\fR
refers to storage allocated and returned by a prior call to
-\fBTcl_Alloc\fR or another function of the Tcl library, then the
-\fIfreeProc\fR argument should be given the special value of
+\fBTcl_Alloc\fR, \fBckalloc\fR, or another function of the Tcl library,
+then the \fIfreeProc\fR argument should be given the special value of
\fBTCL_DYNAMIC\fR.
.PP
This mechanism can be used to solve the problem described above
Index: doc/SetResult.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/SetResult.3,v
retrieving revision 1.6
diff -u -r1.6 SetResult.3
--- doc/SetResult.3 2000/07/24 00:03:02 1.6
+++ doc/SetResult.3 2002/01/04 17:45:00
@@ -195,9 +195,9 @@
modified until at least the next call to \fBTcl_Eval\fR.
If \fIfreeProc\fR
is \fBTCL_DYNAMIC\fR it means that \fIstring\fR was allocated with a call
-to \fBTcl_Alloc\fR and is now the property of the Tcl system.
+to \fBTcl_Alloc\fR or \fBckalloc\fR and is now the property of the Tcl system.
\fBTcl_SetResult\fR will arrange for the string's storage to be
-released by calling \fBTcl_Free\fR when it is no longer needed.
+released by calling \fBckfree\fR when it is no longer needed.
If \fIfreeProc\fR is \fBTCL_VOLATILE\fR it means that \fIstring\fR
points to an area of memory that is likely to be overwritten when
\fBTcl_SetResult\fR returns (e.g. it points to something in a stack frame).
Index: doc/SplitList.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/SplitList.3,v
retrieving revision 1.5
diff -u -r1.5 SplitList.3
--- doc/SplitList.3 2001/09/24 21:10:32 1.5
+++ doc/SplitList.3 2002/01/04 17:45:00
@@ -92,7 +92,7 @@
Then you should eventually free the storage with a call like the
following:
.CS
-Tcl_Free((char *) argv);
+ckfree((char *) argv);
.CE
.PP
\fBTcl_SplitList\fR normally returns \fBTCL_OK\fR, which means the list was
@@ -115,8 +115,8 @@
\fBTcl_Merge\fR will modify the list elements with braces and/or
backslashes in order to produce proper Tcl list structure.
The result string is dynamically allocated
-using \fBTcl_Alloc\fR; the caller must eventually release the space
-using \fBTcl_Free\fR.
+using \fBckalloc\fR; the caller must eventually release the space
+using \fBckfree\fR.
.PP
If the result of \fBTcl_Merge\fR is passed to \fBTcl_SplitList\fR,
the elements returned by \fBTcl_SplitList\fR will be identical to
@@ -172,4 +172,4 @@
argument, and the string may contain embedded nulls.
.SH KEYWORDS
-backslash, convert, element, list, merge, split, strings
+backslash, ckfree, convert, element, list, merge, split, strings
Index: doc/SplitPath.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/SplitPath.3,v
retrieving revision 1.4
diff -u -r1.4 SplitPath.3
--- doc/SplitPath.3 2001/09/27 00:19:57 1.4
+++ doc/SplitPath.3 2002/01/04 17:45:00
@@ -71,7 +71,7 @@
Then you should eventually free the storage with a call like the
following:
.CS
-Tcl_Free((char *) argv);
+ckfree((char *) argv);
.CE
.PP
\fBTcl_JoinPath\fR is the inverse of \fBTcl_SplitPath\fR: it takes a
@@ -93,4 +93,4 @@
each platform.
.SH KEYWORDS
-file, filename, join, path, split, type
+ckfree, file, filename, join, path, split, type
Index: doc/TCL_MEM_DEBUG.3
===================================================================
RCS file: /cvsroot/tcl/tcl/doc/TCL_MEM_DEBUG.3,v
retrieving revision 1.4
diff -u -r1.4 TCL_MEM_DEBUG.3
--- doc/TCL_MEM_DEBUG.3 2001/12/10 15:50:46 1.4
+++ doc/TCL_MEM_DEBUG.3 2002/01/04 17:45:00
@@ -74,7 +74,7 @@
to remove the calls after you find the problem.
.SH "SEE ALSO"
-memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
+ckalloc, memory, Tcl_ValidateAllMemory, Tcl_DumpActiveMemory
.SH KEYWORDS
memory, debug
