TIP 414: Add (back) Tcl_InitSubsystems as Public API

Login
Author:         Brian Griffin <brian_griffin@mentor.com>
Author:         Jan Nijtmans <jan.nijtmans@gmail.com>
State:          Draft
Type:           Project
Vote:           Pending
Created:        15-Oct-2012
Post-History:   
Tcl-Version:    8.7
Tcl-Branch:     initsubsystems
Keywords:       Tcl, library initialisation

Abstract

The ability to initialize just the lower level Tcl subsystems used to be part of the public API, now it is no longer exposed. This TIP proposes that it be re-exposed through the existing function Tcl_SetPanicProc()

Rationale

Some parts of Tcl's API are useful in portable applications even without creating a Tcl interpreter; examples of this include Tcl_Alloc and (most of) the Tcl_DString-related functions. In order to use these functions correctly, the Tcl library must be initialized, yet the function for doing so - Tcl_InitSubsystems (currently TclInitSubsystems) - was removed from Tcl's API; using Tcl_FindExecutable instead feels incorrect as we're not seeking to make the name of the executable available to Tcl scripts.

Proposed Change

The functionality of the existing function Tcl_SetPanicProc is extended, such that it does the initialization of the lower level Tcl subsystem as well. It (still) has a single argument, panicProc. When NULL, the default panic function is used. The return value, which used to be void is changed to const char * and it returns the version of the Tcl library which was initialized. The full signature is:

const char * Tcl_SetPanicProc( Tcl_PanicProc *panicProc);

Use-cases

In androwish. TIP #414 is used to simplify the initialization: Since mounting the zip-file containing all Tcl library scripts needs the encodings initialized before creating the interpreter, this functions allows androwish to do so, without initializing the Tcl encodings twice (once before opening the ZIP-file, once again after the encodings inside this ZIP-file are available)

RFE 854941, an original idea from David Graveraux, can be implemented on top of TIP #414. An experimental implementation is already there, it just needs to be rebased.

An experiment for fossil (branch "initsubsystems2") is already done, showing how to improve loading the Tcl shell dynamically into an already running application.

Reference Implementation

A reference implementation is available in the initsubsystems branch.

Copyright

This document has been placed in the public domain.