TIP 506: Purge RefCount Macros

FlightAware bounty program for improvements to Tcl and certain Tcl packages.
Author:         Don Porter <dgp@users.sourceforge.net>
State:          Draft
Type:           Project
Vote:           Pending
Created:        30-Mar-2018
Tcl-Version:	9.0


Stop having all extensions and applications use macros to access the refCount field of the Tcl_Obj struct.


In all of recorded Tcl development history (since version 8.0p2 in 1998), the "routines" Tcl_IncrRefCount, Tcl_DecrRefCount, and Tcl_IsShared have been defined as macros, built on top of the premise that the caller has direct access to the objPtr->refCount field and the TclFreeProc routine, which is in public stubs even though it has a name suggesting a private routine and users of the Tcl C interface are instructed not to call it other than through the Tcl_DecrRefCount macro.

Like all encapsulation-breaking, the effect is to more strongly couple together modules of code so that they are inhibited from freely evolving as independently as they otherwise could. Simply defining these routines as actual routines would take away that brittle coupling, and the Tcl 8 -> Tcl 9 transition is the opportunity to do it.

The disadvantages of the existing implementation are clear, so why do we have it? I must presume there is at least a strong myth in place that the macros are necessary to achieve acceptable performance. Perhaps that is true. It is a concern to take seriously, but we should demand evidence. This proposal and its draft implementation are a chance to consider the actual merit of those claims beyond keeping up a cargo cult habit.


Remove the macros Tcl_IncrRefCount, Tcl_DecrRefCount, and Tcl_IsShared from the tcl.h file. Create routines in the public stub table to replace them. Remove TclFreeObj from the public stub table.


This is a hard binary incompatibility. It is properly proposed as a change for Tcl 9, where all extensions and applications will require a re-compile anyway.


On the tip-506 branch.


This document has been placed in the public domain.