Tcl_CreateInterp(3)
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.
_________________________________________________________________
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. 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 the built-in Tcl
commands and with the variables documented in tclvars(n).
To bind in additional commands, call Tcl_CreateCommand.
Tcl_DeleteInterp marks an interpreter as deleted; the inter-
preter 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, unde-
fine or retrieve procedures, and examine the runtime evalua-
tion 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.
Tcl Last change: 7.5 1
Tcl_CreateInterp(3) Tcl Library Procedures Tcl_CreateInterp(3)
If nonzero is returned, further calls to Tcl_Eval in this
interpreter will return TCL_ERROR.
Tcl_InterpDeleted is useful in deletion callbacks to distin-
guish between when only the memory the callback is responsi-
ble 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.
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 inter-
preter 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 pro-
tection. Thus, when you write an extension consisting
of new Tcl commands, no special code is needed to pro-
tect 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.
Tcl Last change: 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 structure
(e.g. the client data of a callback) for use in
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; 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. 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.
SEE ALSO
Tcl_Preserve(3), Tcl_Release(3)
KEYWORDS
command, create, delete, interpreter
Tcl Last change: 7.5 3
Man(1) output converted with
man2html