From 103d88f85a9ade51cda8d153915a204bede470a3 Mon Sep 17 00:00:00 2001 From: dkf Date: Sat, 24 Apr 2021 09:04:19 +0000 Subject: Documenting our reference count management --- doc/ByteArrObj.3 | 12 ++++++++++++ doc/Cancel.3 | 8 ++++++++ doc/CrtAlias.3 | 10 +++++++++- 3 files changed, 29 insertions(+), 1 deletion(-) diff --git a/doc/ByteArrObj.3 b/doc/ByteArrObj.3 index 09400c8..2a7d7a3 100644 --- a/doc/ByteArrObj.3 +++ b/doc/ByteArrObj.3 @@ -85,6 +85,18 @@ newly allocated bytes at the end of the array have arbitrary values. If the length of array is reduced to the new length. The return value is a pointer to the value's new array of bytes. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_NewByteArrayObj\fR always returns a zero-reference object, much +like \fBTcl_NewObj\fR. +.PP +\fBTcl_SetByteArrayObj\fR and \fBTcl_SetByteArrayLength\fR do not modify the +reference count of their \fIobjPtr\fR arguments, but do require that the +object be unshared. +.PP +\fBTcl_GetByteArrayFromObj\fR does not modify the reference count of its +\fIobjPtr\fR argument; it only reads. + .SH "SEE ALSO" Tcl_GetStringFromObj, Tcl_NewObj, Tcl_IncrRefCount, Tcl_DecrRefCount diff --git a/doc/Cancel.3 b/doc/Cancel.3 index 847707e..73edaf6 100644 --- a/doc/Cancel.3 +++ b/doc/Cancel.3 @@ -67,6 +67,14 @@ other procedures. If an error is returned and this bit is set in result, where it can be retrieved with \fBTcl_GetObjResult\fR or \fBTcl_GetStringResult\fR. If this flag bit is not set then no error message is left and the interpreter's result will not be modified. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_CancelEval\fR always decrements the reference count of its +\fIresultObjPtr\fR argument (if that is non-NULL). It is expected to +be usually called with an object with zero reference count. If the +object is shared with some other location (including the Tcl +evaluation stack) it should have its reference count incremented +before calling this function. .SH "SEE ALSO" interp(n), Tcl_Eval(3), TIP 285 diff --git a/doc/CrtAlias.3 b/doc/CrtAlias.3 index 92f9b0c..2623dcd 100644 --- a/doc/CrtAlias.3 +++ b/doc/CrtAlias.3 @@ -243,8 +243,16 @@ any script evaluation mechanism will fail. .PP For a description of the Tcl interface to multiple interpreters, see \fIinterp(n)\fR. +.SH "REFERENCE COUNT MANAGEMENT" +.PP +\fBTcl_CreateAliasObj\fR increments the reference counts of the values +in its \fIobjv\fR argument. (That reference lasts the same length of +time as the owning alias.) +.PP +\fBTcl_GetAliasObj\fR returns (via its \fIobjvPtr\fR argument) a +pointer to values that it holds a reference to. .SH "SEE ALSO" -interp +interp(n) .SH KEYWORDS alias, command, exposed commands, hidden commands, interpreter, invoke, -- cgit v0.12