Tcl_Interp * Tcl_CreateInterp()
- Tcl_Interp *interp (in)
Token for interpreter to be destroyed.
Tcl_CreateInterp() creates a new interpreter structure and
a token for it. The token is required in calls to most other Tcl
procedures, such as Tcl_CreateCommand(),
Clients are only allowed to access a few of the fields of
Tcl_Interp structures; see the Tcl_Interp()
and Tcl_CreateCommand() reference pages for details.
The new interpreter is initialized with no defined variables and only
the built-in Tcl commands. To bind in additional commands, call
Tcl_DeleteInterp() marks an interpreter as deleted; the
will eventually be deleted when all calls to Tcl_Preserve()
for it have
been matched by calls to Tcl_Release(). At that time, all
resources associated with it, including variables, procedures, and
application-specific command bindings, will be deleted. After
Tcl_DeleteInterp() returns any attempt to use
Tcl_Eval() on the
interpreter will fail and return TCL_ERROR. After the call to
Tcl_DeleteInterp() it is safe to examine the interpreter's
query or set the values of variables, define, undefine or retrieve
procedures, and examine the runtime evaluation stack. See below, in the
section INTERPRETERS AND MEMORY MANAGEMENT for details.
Tcl_InterpDeleted() returns nonzero if
called with interp as its argument; this indicates that the
interpreter will eventually be deleted, when the last call to
Tcl_Preserve() for it is matched by a call to
nonzero is returned, further calls to Tcl_Eval() in this
will return TCL_ERROR.
Tcl_InterpDeleted() is useful in deletion callbacks to
between when only the memory the callback is responsible for is being
deleted and when the whole interpreter is being deleted. In the former case
the callback may recreate the data being deleted, but this would lead to an
infinite loop if the interpreter were being deleted.
Tcl_DeleteInterp() can be called at any time on an
interpreter that may
be used by nested evaluations and C code in various extensions. Tcl
implements a simple mechanism that allows callers to use interpreters
without worrying about the interpreter being deleted in a nested call, and
without requiring special code to protect the interpreter, in most cases.
This mechanism ensures that nested uses of an interpreter can safely
continue using it even after Tcl_DeleteInterp() is called.
The mechanism relies on matching up calls to Tcl_Preserve()
to Tcl_Release(). If Tcl_DeleteInterp()
has been called, only when
the last call to Tcl_Preserve() is matched by a call to
Tcl_Release(), will the interpreter be freed. See the
reference page for
Tcl_Preserve() for a description of these functions.
The rules for when the user of an interpreter must call
and Tcl_Release() are simple:
- Interpreters Passed As Arguments
Functions that are passed an interpreter as an argument can safely use the
interpreter without any special protection. Thus, when you write an
extension consisting of new Tcl commands, no special code is needed to
protect interpreters received as arguments. This covers the majority of all
- Interpreter Creation And Deletion
When a new interpreter is created and used in a call to
Tcl_GetVar(), a pair of calls to
Tcl_Release() should be wrapped around all uses of the
Remember that it is unsafe to use the interpreter once
has been called. To ensure that the interpreter is properly deleted when
it is no longer needed, call Tcl_InterpDeleted() to test if
code already called Tcl_DeleteInterp(); if not, call
Tcl_DeleteInterp() before calling
Tcl_Release() in your own code.
Do not call Tcl_DeleteInterp() on an interpreter for which
Tcl_InterpDeleted() returns nonzero.
- Retrieving An Interpreter From A Data Structure
When an interpreter is retrieved from a data structure (for example, the
data of a callback) for use in Tcl_Eval(),
Tcl_GlobalEval(), Tcl_SetVar(), or
Tcl_GetVar(), a pair of
calls to Tcl_Preserve() and
Tcl_Release() should be wrapped around
all uses of the interpreter; it is unsafe to reuse the interpreter once
Tcl_Release() has been called. If an interpreter is stored
callback data structure, an appropriate deletion cleanup mechanism should
be set up by the code that creates the data structure so that the
interpreter is removed from the data structure (for example, by setting the
to NULL) when the interpreter is deleted. Otherwise, you may be using an
interpreter that has been freed and whose memory may already have been
All uses of interpreters in Tcl and Tk have already been protected.
Extension writers should ensure that their code also properly protects any
additional interpreters used, as described above.
Windows Server 2012. Windows 8.1. Windows Server 2012 R2. Windows 10. Windows Server 2016. Windows Server 2019.
PTC MKS Toolkit for Professional Developers
PTC MKS Toolkit for Enterprise Developers
PTC MKS Toolkit for Enterprise Developers 64-Bit Edition
- Tcl_Preserve(), Tcl_Release()
PTC MKS Toolkit 10.3 Documentation Build 39.