diff options
Diffstat (limited to 'tcl8.6/doc/CrtInterp.3')
| -rw-r--r-- | tcl8.6/doc/CrtInterp.3 | 150 |
1 files changed, 150 insertions, 0 deletions
diff --git a/tcl8.6/doc/CrtInterp.3 b/tcl8.6/doc/CrtInterp.3 new file mode 100644 index 0000000..679795e --- /dev/null +++ b/tcl8.6/doc/CrtInterp.3 @@ -0,0 +1,150 @@ +'\" +'\" 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 |