Tcl_CreateInterp(3) Tcl Library Procedures Tcl_CreateInterp(3)_________________________________________________________________NAME
Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted -
create and delete Tcl command interpreters
SYNOPSIS
#include <tcl.h>
Tcl_Interp *
Tcl_CreateInterp()Tcl_DeleteInterp(interp)
int
Tcl_InterpDeleted(interp)ARGUMENTS
Tcl_Interp *interp (in) Token for interpreter to
be destroyed.
_________________________________________________________________DESCRIPTIONTcl_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. Clients are only allowed
to access a few of the fields of Tcl_Interp structures;
see the Tcl_Interp and Tcl_CreateCommand man 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_CreateCommand.
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
interp->result, query or set the values of variables,
define, undefine or retrieve procedures, and examine the
runtime evaluation stack. See below, in the section INTER-
PRETERS 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 7.5 1
Tcl_CreateInterp(3) Tcl Library Procedures Tcl_CreateInterp(3)
Tcl_InterpDeleted is useful in deletion callbacks to dis-
tinguish between when only the memory the callback is
responsible for is being deleted and when the whole inter-
preter 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.
INTERPRETERS AND MEMORY MANAGEMENT
Tcl_DeleteInterp can be called at any time on an inter-
preter 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 exten-
sion 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. Do not call
Tcl_DeleteInterp on an interpreter for which
Tcl_InterpDeleted returns nonzero.
Tcl 7.5 2
Tcl_CreateInterp(3) Tcl Library Procedures Tcl_CreateInterp(3)
Retrieving An Interpreter From A Data Structure
When an interpreter is retrieved from a data struc-
ture (e.g. the client data of a callback) for use
in Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_Set-
Var, 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 inside a callback data
structure, an appropriate deletion cleanup mecha-
nism 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. Other-
wise, 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.
KEYWORDS
command, create, delete, interpreter
SEE ALSOTcl_Preserve(3), Tcl_Release(3)Tcl 7.5 3
