From da0494846240aecf116ebb8ebd14a3475603a7f7 Mon Sep 17 00:00:00 2001 From: griffin Date: Thu, 28 Nov 2024 19:48:32 +0000 Subject: Document incompatible change in treatment of reference counts wrt Tcl_ListObjIndex. (bug-b343fe8656) --- doc/ListObj.3 | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/doc/ListObj.3 b/doc/ListObj.3 index deae5a5..0c176fa 100644 --- a/doc/ListObj.3 +++ b/doc/ListObj.3 @@ -199,7 +199,15 @@ and returns \fBTCL_OK\fR. Otherwise it returns \fBTCL_OK\fR after storing the element's value pointer. The reference count for the list element is not incremented; -the caller must do that if it needs to retain a pointer to the element. +the caller must do that if it needs to retain a pointer to the +element, or "bounce" the reference count when the element is no longer +needed. This is because a returned element may have a reference count +of 0 for an Abstract List. Therefore, the caller is responsible for +freeing the element when it is no longer needed. Note that this is a +change from Tcl 8 where all list elements always have a reference +count of at least 1. See \fBABSTRACT LIST TYPES\fR, +Tcl_BounceRefCount(3), and lseq(n) for more information. + .PP \fBTcl_ListObjReplace\fR replaces zero or more elements of the list referenced by \fIlistPtr\fR -- cgit v0.12 From 911b8a64bc635c94718d6e97ff53895b5e900c77 Mon Sep 17 00:00:00 2001 From: griffin Date: Sat, 30 Nov 2024 00:47:46 +0000 Subject: Add more detail about Abstract Lists --- doc/ListObj.3 | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/ListObj.3 b/doc/ListObj.3 index 0c176fa..6e4d0d5 100644 --- a/doc/ListObj.3 +++ b/doc/ListObj.3 @@ -202,11 +202,13 @@ The reference count for the list element is not incremented; the caller must do that if it needs to retain a pointer to the element, or "bounce" the reference count when the element is no longer needed. This is because a returned element may have a reference count -of 0 for an Abstract List. Therefore, the caller is responsible for +of 0. Abstract Lists create a new element Obj on demand, and do not +retain any element Obj values. Therefore, the caller is responsible for freeing the element when it is no longer needed. Note that this is a change from Tcl 8 where all list elements always have a reference -count of at least 1. See \fBABSTRACT LIST TYPES\fR, -Tcl_BounceRefCount(3), and lseq(n) for more information. +count of at least 1. (See \fBABSTRACT LIST TYPES\fR, \fBSTORAGE +MANAGEMENT OF VALUES\fR, Tcl_BounceRefCount(3), and lseq(n) for more +information.) .PP \fBTcl_ListObjReplace\fR replaces zero or more elements -- cgit v0.12