Author:		Ashok P. Nadkarni <apnmbx-public@yahoo.com>
State:		Final
Type:		Project
Vote:		Done
Created:	2024-05-14
Tcl-Version:	9.0
Vote-Summary:	Accepted 9/0/0
Votes-For:	AN, AK, BG, HO, JN, KW, MC, RA, SL
Votes-Against:	none
Votes-Present:	none

Abstract

This TIP proposes reservation of a range of Tcl return codes for Tcl's own use so as to avoid conflicts with return codes used by extensions and applications.

Rationale

Tcl return codes are 32-bit integers with values 0-4 defined as ok, error, return, break, continue. Extensions are free to use other values as they see fit. This has two repercussions:

An extension runs the risk of using a value that will be in conflict with a future major release of Tcl.
Conversely, Tcl is constrained to defining new values for its own use only in major releases. As an example, in the discussion around TIP 328, the possibility of new codes TCL_SUSPEND and TCL_RESUME was discarded as it could only be done in a major release for compatibility reasons.

The author has had similar considerations experimenting with alternative tailcall implementations as well as a coroutine based actor extension.

Specification

The range of return code values between TCL_CODE_USER_MIN and TCL_CODE_USER_MAX (inclusive) will be reserved for users (packages and applications). All values outside this range are reserved for use by Tcl.

The following public #defines will be added to tcl.h

#define TCL_CODE_USER_MIN 5
#define TCL_CODE_USER_MAX 0x3FFFFFFF /* 1073741823 */

Discussion

The above range is chosen based on discussion on the core mailing list. With no clear consensus, the following factors have been considered.

It is more convenient for user code to use small values than large ones. It does not matter as much for Tcl as the code values have string equivalents like break and TCL_BREAK.
As a bonus, the possibility of incompatibility with current usage is reduced. The magicsplat distribution shows no code above 100.
The above roughly allocates half of the positive range space for Tcl. While there have been comments that Tcl should not need that many, that is also true for applications. It also leaves the possibility of assigning semantics at the individual bit level as is done for COM.
The inclusion of negative values in the Tcl reserved range is not strictly necessary. However, some of the encoding routines use negative return codes in conjunction with TCL_OK etc. so it might be a good idea to formalize that.
It is understood that this does not solve the problem of conflicts between two extensions. That is not the goal of this TIP. However, in most cases extensions use their own codes only internally so this is rarely an issue anyway. It has also been suggested a registry be used to prevent conflicts. That is also outside the scope of this TIP.

Implementation

See branch tip-696.

Copyright