Check-in [c80f0474ca]

<th>#</th>
<th>Type</th>
<th>Tcl Version</th>
<th>Status</th>
<th>Title</th>
</tr></thead><tbody>

<tr class='project projectdraft projectdraft90 project90'>
<td valign='top'><a href='./tip/506.md'>506</a></td>
<td valign='top'>Project</td>
<td valign='top'>9.0</td>
<td valign='top'>Draft</td>
<td valign='top'># TIP 506: Purge RefCount Macros</td>
</tr>
<tr class='project projectdraft projectdraft86 project86'>
<td valign='top'><a href='./tip/505.md'>505</a></td>
<td valign='top'>Project</td>
<td valign='top'>8.6.9</td>
<td valign='top'>Draft</td>
<td valign='top'># TIP 505: Make [lreplace] Accept All Out-of-Range Index Values</td>
</tr>

# TIP 506: Purge RefCount Macros
	Author:         Don Porter <[email protected]>
	State:          Draft
	Type:           Project
	Vote:           Pending
	Created:        30-Mar-2018
	Post-History:   
	Tcl-Version:	9.0
-----

# Abstract

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

# Background

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.

# Proposal

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.

# Compatibility

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.

# Implementation

On the tip-506 branch.

# Copyright

This document has been placed in the public domain.