TIP 512: No stub for Tcl_SetExitProc()

EuroTcl/OpenACS 11 - 12 JULY 2024, VIENNA
Author:         Jan Nijtmans <[email protected]>
State:          Final
Type:           Project
Vote:           Done
Created:        25-June-2018
Keywords:       Tcl
Tcl-Version:	8.7
Tcl-Branch:     tip-512


This TIP proposes to remove the stub entries for Tcl_SetExitProc(), Tcl_SetPanicProc(), Tcl_FindExecutable() and (for Tk) Tk_MainEx(). The normal exported symbols for those functions will be kept intact.


This TIP is inspired by Tcl commit "Add custom exit procedure for tcltests executable". This commit demonstrates exactly what's the problem when using Tcl_SetExitProc() in a stub-enabled extension: On win32 this caused a crash in many unit-tests, when tclsh ended. This problematic commit was corrected in this commit: a thread exit handler is how this should have been done.


When running test-cases in Windows (using mingw-64 or MSVC, but using the win/Makefile system not the nmake system), the tclsh executable crashes after shutdown in some tests. The reason for this is that the additional test-code "tcltest" is compiled as stub-enabled extension which is dynamically loaded into tclsh. So, there is no "tcltest" executable in this environment, tclsh86.exe and tcltest86.dll are sufficient.

If a stub-enabled extension registers an Exit-handler, the following happens at exit time. During the clean-up, Tcl unloads all extensions. When the clean-up is done, the last step is calling the registered Exit-handler. But ... since the exit handler function was located inside the DLL, it's address space is gone already. This results in the mentioned crash.

A similar problem exists in Tcl_SetPanicProc(): If a stub-enabled extension registers a Panic proc which is located in its own address space, the extension might be gone when the panicproc is finally called.

Tcl_FindExecutable() and Tk_MainEx() don't register functions, but those functions - too - are meant to be used at application level, not at extension level. Therefore those don't belong in the stub table either.


The above mentioned functions are marked with nostub (in tcl.decls), and the tools/genStubs.tcl tooling is adapted to recognize this special keyword. The effect is that the function entry in the stub table is marked as deprecated, but the normal function entry is left as-is.

When Tcl is compiled with -DTCL_NO_DEPRECATED, the stub entries for the above functions will no longer be available. The stub table entries for those function will be filled with 0 instead.

Starting with Tcl 9.0, those stub entries will be removed completely. In stead, those functions will be defined in tcl.h, as normal exported symbols, just like Tcl_MainEx() (for example).


Currently, the proposed implementation is available in tip-512 branch.


This document has been placed in the public domain.