TIP #335 Version 1.5: An API for Detecting Active Interpreters

This is not necessarily the current version of this TIP.

Abstract

This TIP introduces the ability to quickly and safely obtain the value of the numLevels field of the Interp structure, allowing an external system to determine whether it is safe to delete the interpreter.

Rationale

For applications written in garbage-collected languages, such as C#, it is not always desirable to rely upon the Tcl_Preserve / Tcl_Release mechanism to protect an against deletion of an interpreter while it is in use. For details of how this is used, see [1] [2] and Joe Mistachkin's talk at Tcl 2008.

Additionally, an application may want to proactively forbid attempts to delete an interpreter while it is in use. Unfortunately, there is currently no publicly exposed method to determine if a given Tcl interpreter is in use (i.e. one or more calls to Tcl_Eval are active). This TIP proposes to correct that deficiency.

Specification

This TIP introduces a single function to Tcl's public API:

int Tcl_GetNumLevels(Tcl_Interp *interp)

The Tcl_GetNumLevels function returns the value of the numLevels field in the Interp structure.

Reference Implementation

/*
 *----------------------------------------------------------------------
 *
 * Tcl_GetNumLevels --
 *
 *	Returns the number of nested calls to Tcl_Eval that are in progress
 *	for the specified interpreter.
 *
 * Results:
 *	See above.
 *
 * Side effects:
 *	None.
 *
 *----------------------------------------------------------------------
 */

int
Tcl_GetNumLevels(Tcl_Interp *interp)
{
    Interp *iPtr = (Interp *) interp;
    return iPtr->numLevels;
}

Copyright

This document has been placed in the public domain.

This is not necessarily the current version of this TIP.