Author:         Don Porter <[email protected]>
State:          Final
Type:           Project
Tcl-Version:    9.0
Vote:           Done
Created:        13-Jan-2020
Keywords:       Tcl, result 
Post-History:
Tcl-Branch:	tip-599
Vote-Summary:	Accepted 8/0/0
Votes-For:	DP, JD, MC, KW, SL, FV, DF, JN
Votes-Against:	none
Votes-Present:	none

Abstract

This TIP proposes the fully official deprecation and elimination of the public routine Tcl_FreeResult.

History and Rationale

Tcl_FreeResult first appeared in release Tcl 6, as a companion to the new routine Tcl_SetResult. The purpose of Tcl_FreeResult was to be a utility routine for managing the memory associated with the interp->result field of an interpreter, consistent with the state of the interpreter left by the most recent call to Tcl_SetResult. The utility spared the caller the burden of examining interp->freeProc for itself. Placing critical housekeeping in a utility routine to be shared was a useful idea compared with demanding every client of the Tcl API to do the same for itself.

In Tcl 9, the field interp->result is no longer available in the public interface, so the original purpose of this utility routine no longer has any value.

From the beginning Tcl_FreeResult has been documented

...It frees up the memory associated with interp's result and sets interp->freeProc to zero, but it doesn't change interp->result...

That is, the routine has explicitly been designed to leave an invalid pointer in interp->result, a hazardous design. A subsequent call to Tcl_AppendResult or Tcl_AppendElement would be expected to crash. Over time as Tcl maintenance passed to coders other than the originators of the hazard, even more crash scenarios arose in Tcl_GetObjResult and Tcl_GetStringResult. To avoid such issues, a caller must followup the Tcl_FreeResult call with either calls to Tcl_ResetResult, Tcl_SetResult, or their own direct write to interp->result. The last of these is no longer permitted, and the other two already have the same housekeeping included in them that Tcl_FreeResult provides. There is no longer a scenario where the Tcl_FreeResult provides value.

Starting in release Tcl 8.0, the documentation described Tcl_FreeResult as deprecated. Arguably that documented pre-TCT record could be enough direction, but this TIP is offered anyway to be completely clear, and in recognition of the fact that other deprecation steps such as marking in the stub tables have not yet been taken.

Specification

In Tcl 9, remove the routine Tcl_FreeResult from code and documentation.

In Tcl 8.7, mark the routine as deprecated in code and documentation.

Compatibility

It is likely that any existing caller of Tcl_FreeResult is also still making direct access to interp->result and the same revision work will address both issues. Any callers of Tcl_FreeResult that are not in that scenario should be able to replace their Tcl_FreeResult calls with Tcl_ResetResult calls.

Reference Implementation

See branches tip-559. and tip-559-dep.

Copyright