TIP 585: Promote the INDEX_TEMP_TABLE flag of Tcl_GetIndexFromObj*() to the public interface

Login
Bounty program for improvements to Tcl and certain Tcl packages.
Author:         Francois Vogel <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Vote-Summary:   Accepted 6/0/0
Votes-For:      DGP, FV, JN, KW, MC, SL
Votes-Against:  none
Votes-Present:  none
Created:        30-Aug-2020
Post-History:   
Keywords:       Tcl Tcl_GetIndexFromObj() Tcl_GetIndexFromObjStruct()
Tcl-Version:    8.7
Tcl-Branch:     tip-585

Abstract

This TIP proposes to promote the INDEX_TEMP_TABLE flag of Tcl_GetIndexFromObj*() to the public interface as TCL_INDEX_TEMP_TABLE, so that the tables used may not be always static.

Rationale

Tcl_GetIndexFromObjStruct() is largely used in the Tcl/Tk codebase. It expects an array of static entries structTablePtr as input, that must not change between invocations. This is well documented, and is almost always the case since in the current codebase this function is mainly used to retrieve indices from options lists. Because these options lists are static, caching of indices can be done, which increases efficiency when looking several times for the same index in the same table.

However, in some cases it would be useful to be able to instruct Tcl_GetIndexFromObjStruct() that the table passed to it is not static, meaning caching of indices shall not be used. There is such a use case in the revised_text branch of Tk, specifically in function GetDumpFlags() here. Based on some input parameters, this function builds a list of options that depends on those input parameters, and is therefore not static when Tcl_GetIndexFromObjStruct() is called repeatedly. This is the root cause for bug [8980ba1d0b] according to my analysis dated 2020-08-25 20:34:47. in that ticket. In this use case it is needed to be able to disable indices caching in Tcl_GetIndexFromObjStruct().

As it turns out, Tcl_GetIndexFromObjStruct() already has this capability through its INDEX_TEMP_TABLE flag. This flag is already used internally by Tcl.

The proposal of the present TIP is therefore to promote this flag to the public interface as TCL_INDEX_TEMP_TABLE, so that Tk can make use of it in the above use case and more.

Implementation

Available in the tip-585 branch.

This branch targets 8.7.

Rejected alternatives

It has been proposed that instead of exposing INDEX_TEMP_TABLE a new public routine be provided featuring a non-caching version of Tcl_GetIndexFromObj*(), which would be needed for shared Tcl_Objs only. While this could of course be done, I think exposing the existing INDEX_TEMP_TABLE flag is simpler.

Copyright

This document has been placed in the public domain.