151 lines
6.9 KiB
Groff
151 lines
6.9 KiB
Groff
|
'\"
|
||
|
|
'\" Copyright (c) 1989-1993 The Regents of the University of California.
|
||
|
|
'\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
|
||
|
|
'\"
|
||
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
||
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
||
|
|
'\"
|
||
|
|
.TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
|
||
|
|
.so man.macros
|
||
|
|
.BS
|
||
|
|
.SH NAME
|
||
|
|
Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, Tcl_InterpDeleted \- create and delete Tcl command interpreters
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
\fB#include <tcl.h>\fR
|
||
|
|
.sp
|
||
|
|
Tcl_Interp *
|
||
|
|
\fBTcl_CreateInterp\fR()
|
||
|
|
.sp
|
||
|
|
\fBTcl_DeleteInterp\fR(\fIinterp\fR)
|
||
|
|
.sp
|
||
|
|
int
|
||
|
|
\fBTcl_InterpDeleted\fR(\fIinterp\fR)
|
||
|
|
.sp
|
||
|
|
.VS 8.6
|
||
|
|
int
|
||
|
|
\fBTcl_InterpActive\fR(\fIinterp\fR)
|
||
|
|
.VE 8.6
|
||
|
|
.SH ARGUMENTS
|
||
|
|
.AS Tcl_Interp *interp
|
||
|
|
.AP Tcl_Interp *interp in
|
||
|
|
Token for interpreter to be destroyed or queried.
|
||
|
|
.BE
|
||
|
|
.SH DESCRIPTION
|
||
|
|
.PP
|
||
|
|
\fBTcl_CreateInterp\fR creates a new interpreter structure and returns
|
||
|
|
a token for it. The token is required in calls to most other Tcl
|
||
|
|
procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and
|
||
|
|
\fBTcl_DeleteInterp\fR. The token returned by \fBTcl_CreateInterp\fR
|
||
|
|
may only be passed to Tcl routines called from the same thread as
|
||
|
|
the original \fBTcl_CreateInterp\fR 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 \fBtcl_platform\fR and \fBenv\fR. To
|
||
|
|
bind in additional commands, call \fBTcl_CreateCommand\fR, and to
|
||
|
|
create additional variables, call \fBTcl_SetVar\fR.
|
||
|
|
.PP
|
||
|
|
\fBTcl_DeleteInterp\fR marks an interpreter as deleted; the interpreter
|
||
|
|
will eventually be deleted when all calls to \fBTcl_Preserve\fR for it have
|
||
|
|
been matched by calls to \fBTcl_Release\fR. At that time, all of the
|
||
|
|
resources associated with it, including variables, procedures, and
|
||
|
|
application-specific command bindings, will be deleted. After
|
||
|
|
\fBTcl_DeleteInterp\fR returns any attempt to use \fBTcl_Eval\fR on the
|
||
|
|
interpreter will fail and return \fBTCL_ERROR\fR. After the call to
|
||
|
|
\fBTcl_DeleteInterp\fR 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 \fBINTERPRETERS AND MEMORY MANAGEMENT\fR for details.
|
||
|
|
.PP
|
||
|
|
\fBTcl_InterpDeleted\fR returns nonzero if \fBTcl_DeleteInterp\fR was
|
||
|
|
called with \fIinterp\fR as its argument; this indicates that the
|
||
|
|
interpreter will eventually be deleted, when the last call to
|
||
|
|
\fBTcl_Preserve\fR for it is matched by a call to \fBTcl_Release\fR. If
|
||
|
|
nonzero is returned, further calls to \fBTcl_Eval\fR in this interpreter
|
||
|
|
will return \fBTCL_ERROR\fR.
|
||
|
|
.PP
|
||
|
|
\fBTcl_InterpDeleted\fR 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.
|
||
|
|
.PP
|
||
|
|
.VS 8.6
|
||
|
|
\fBTcl_InterpActive\fR 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.
|
||
|
|
.VE 8.6
|
||
|
|
.SH "INTERPRETERS AND MEMORY MANAGEMENT"
|
||
|
|
.PP
|
||
|
|
\fBTcl_DeleteInterp\fR 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 \fBTcl_DeleteInterp\fR is called.
|
||
|
|
.PP
|
||
|
|
The mechanism relies on matching up calls to \fBTcl_Preserve\fR with calls
|
||
|
|
to \fBTcl_Release\fR. If \fBTcl_DeleteInterp\fR has been called, only when
|
||
|
|
the last call to \fBTcl_Preserve\fR is matched by a call to
|
||
|
|
\fBTcl_Release\fR, will the interpreter be freed. See the manual entry for
|
||
|
|
\fBTcl_Preserve\fR for a description of these functions.
|
||
|
|
.PP
|
||
|
|
The rules for when the user of an interpreter must call \fBTcl_Preserve\fR
|
||
|
|
and \fBTcl_Release\fR are simple:
|
||
|
|
.TP
|
||
|
|
\fBInterpreters Passed As Arguments\fR
|
||
|
|
.
|
||
|
|
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.
|
||
|
|
.TP
|
||
|
|
\fBInterpreter Creation And Deletion\fR
|
||
|
|
.
|
||
|
|
When a new interpreter is created and used in a call to \fBTcl_Eval\fR,
|
||
|
|
\fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or
|
||
|
|
\fBTcl_GetVar\fR, a pair of calls to \fBTcl_Preserve\fR and
|
||
|
|
\fBTcl_Release\fR should be wrapped around all uses of the interpreter.
|
||
|
|
Remember that it is unsafe to use the interpreter once \fBTcl_Release\fR
|
||
|
|
has been called. To ensure that the interpreter is properly deleted when
|
||
|
|
it is no longer needed, call \fBTcl_InterpDeleted\fR to test if some other
|
||
|
|
code already called \fBTcl_DeleteInterp\fR; if not, call
|
||
|
|
\fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fR in your own code.
|
||
|
|
.TP
|
||
|
|
\fBRetrieving An Interpreter From A Data Structure\fR
|
||
|
|
.
|
||
|
|
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
|
||
|
|
(\fBTcl_Eval\fR, \fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_EvalObjv\fR,
|
||
|
|
etc.) or variable access functions (\fBTcl_SetVar\fR, \fBTcl_GetVar\fR,
|
||
|
|
\fBTcl_SetVar2Ex\fR, etc.), a pair of
|
||
|
|
calls to \fBTcl_Preserve\fR and \fBTcl_Release\fR should be wrapped around
|
||
|
|
all uses of the interpreter; it is unsafe to reuse the interpreter once
|
||
|
|
\fBTcl_Release\fR 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.
|
||
|
|
.PP
|
||
|
|
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.
|
||
|
|
.PP
|
||
|
|
.VS 8.6
|
||
|
|
Note that the protection mechanisms do not work well with conventional garbage
|
||
|
|
collection systems. When in such a managed environment, \fBTcl_InterpActive\fR
|
||
|
|
should be used to determine when an interpreter is a candidate for deletion
|
||
|
|
due to inactivity.
|
||
|
|
.VE 8.6
|
||
|
|
.SH "SEE ALSO"
|
||
|
|
Tcl_Preserve(3), Tcl_Release(3)
|
||
|
|
.SH KEYWORDS
|
||
|
|
command, create, delete, interpreter
|