The clt thread at [L1 ] and Bug #1334947 [L2 ] revived the discussion of how to properly manage the reference count of Tcl_Objs.
This is an attempt at clarifying the issue, and a roadmap to improving both the core's refCount management as well as the documentation related to the subject.
1. Categorization
Joe English writes: There are roughly four classes of Tcl_Obj-related library routines:
and Donal Fellows adds the category
Please note that the same funtion may belong to different categories with respect to different arguments: for example, as currently implemented (up to Tcl8.5a4), the function Tcl_ObjSetVar2(interp, part1Ptr, part2Ptr, newValuePtr, flags) is a Reader wrt part1Ptr and part2Ptr, but a Hairy-Monster wrt newValuePtr. (DKF: It should be noted that there is no guarantee that Tcl_ObjSetVar2 will remain a reader wrt part2ptr; if we ever optimize internal memory management of arrays, that will likely change. This is why knowing which function is what with respect to each argument is hard.)
As a general rule, all Tcl commands should be considered to be Hairy-Monsters wrt the objects in the objv array.
We hope to improve the documentation wrt to the categorization of the different functions, and also to reduce significantly the population of Hairy-Monsters. As of today, Constructors and Mutators should be properly documented as such.
2. Rules for dealing safely with the different categories
Note first that Constructors are not an issue: there is no Tcl_Obj to manage before you call them.
The always-safe rules are:
The optimal rules in terms of performance and code simplicity (but risky in light of incomplete documentation) are: