Tribblix: manual page: Tcl

Tcl_CreateInterp(3) Tcl Library Procedures Tcl_CreateInterp(3)

____________________________________________________________________________

NAME

Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive,
Tcl_InterpDeleted - create and delete Tcl command interpreters

SYNOPSIS

#include <tcl.h>

Tcl_Interp *
Tcl_CreateInterp()

Tcl_DeleteInterp(interp)

int
Tcl_InterpDeleted(interp)

int |
Tcl_InterpActive(interp) |

ARGUMENTS

Tcl_Interp *interp (in) Token for interpreter to be
destroyed or queried.
____________________________________________________________________________

DESCRIPTION

Tcl_CreateInterp creates a new interpreter structure and returns a
token for it. The token is required in calls to most other Tcl
procedures, such as Tcl_CreateCommand, Tcl_Eval, and
Tcl_DeleteInterp. The token returned by Tcl_CreateInterp may only be
passed to Tcl routines called from the same thread as the original
Tcl_CreateInterp call. It is not safe for multiple threads to pass
the same token to Tcl's routines. The new interpreter is initialized
with the built-in Tcl commands and with standard variables like
tcl_platform and env. To bind in additional commands, call
Tcl_CreateCommand, and to create additional variables, call
Tcl_SetVar.

Tcl_DeleteInterp marks an interpreter as deleted; the interpreter
will eventually be deleted when all calls to Tcl_Preserve for it have
been matched by calls to Tcl_Release. At that time, all of the
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 result,
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 Tcl_DeleteInterp was 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 Tcl_Release. If nonzero is returned, further
calls to Tcl_Eval in this interpreter will return TCL_ERROR.

Tcl_InterpDeleted is useful in deletion callbacks to distinguish
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_InterpActive is useful for determining whether there is any |
execution of scripts ongoing in an interpreter, which is a useful |
piece of information when Tcl is embedded in a garbage-collected |
environment and it becomes necessary to determine whether the |
interpreter is a candidate for deletion. The function returns a true |
value if the interpreter has at least one active execution running |
inside it, and a false value otherwise.

INTERPRETERS AND MEMORY MANAGEMENT

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 with calls
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 manual entry for Tcl_Preserve for a
description of these functions.

The rules for when the user of an interpreter must call Tcl_Preserve
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 uses.

Interpreter Creation And Deletion
When a new interpreter is created and used in a call to
Tcl_Eval, Tcl_VarEval, 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.
Remember that it is unsafe to use the interpreter once
Tcl_Release has been called. To ensure that the interpreter is
properly deleted when it is no longer needed, call
Tcl_InterpDeleted to test if some other code already called
Tcl_DeleteInterp; if not, call Tcl_DeleteInterp before calling
Tcl_Release in your own code.

Retrieving An Interpreter From A Data Structure
When an interpreter is retrieved from a data structure (e.g.
the client data of a callback) for use in one of the
evaluation functions (Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval,
Tcl_EvalObjv, etc.) or variable access functions (Tcl_SetVar,
Tcl_GetVar, Tcl_SetVar2Ex, etc.), 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
inside a 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 (e.g. by setting the field 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 reused.

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.

Note that the protection mechanisms do not work well with |
conventional garbage collection systems. When in such a managed |
environment, Tcl_InterpActive should be used to determine when an |
interpreter is a candidate for deletion due to inactivity.

KEYWORDS