TIP 696: Reserve range of return codes for Tcl's own use

Login
Author:		Ashok P. Nadkarni <[email protected]>
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:

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.

Implementation

See branch tip-696.

Copyright

This document has been placed in the public domain.