[25] | 1 | '\" |
---|
| 2 | '\" Copyright (c) 1989-1993 The Regents of the University of California. |
---|
| 3 | '\" Copyright (c) 1994-1996 Sun Microsystems, Inc. |
---|
| 4 | '\" |
---|
| 5 | '\" See the file "license.terms" for information on usage and redistribution |
---|
| 6 | '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. |
---|
| 7 | '\" |
---|
| 8 | '\" RCS: @(#) $Id: CrtInterp.3,v 1.7 2002/06/26 11:50:52 msofer Exp $ |
---|
| 9 | '\" |
---|
| 10 | .so man.macros |
---|
| 11 | .TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures" |
---|
| 12 | .BS |
---|
| 13 | .SH NAME |
---|
| 14 | Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted \- create and delete Tcl command interpreters |
---|
| 15 | .SH SYNOPSIS |
---|
| 16 | .nf |
---|
| 17 | \fB#include <tcl.h>\fR |
---|
| 18 | .sp |
---|
| 19 | Tcl_Interp * |
---|
| 20 | \fBTcl_CreateInterp\fR() |
---|
| 21 | .sp |
---|
| 22 | \fBTcl_DeleteInterp\fR(\fIinterp\fR) |
---|
| 23 | .sp |
---|
| 24 | int |
---|
| 25 | \fBTcl_InterpDeleted\fR(\fIinterp\fR) |
---|
| 26 | .SH ARGUMENTS |
---|
| 27 | .AS Tcl_Interp *interp |
---|
| 28 | .AP Tcl_Interp *interp in |
---|
| 29 | Token for interpreter to be destroyed. |
---|
| 30 | .BE |
---|
| 31 | |
---|
| 32 | .SH DESCRIPTION |
---|
| 33 | .PP |
---|
| 34 | \fBTcl_CreateInterp\fR creates a new interpreter structure and returns |
---|
| 35 | a token for it. The token is required in calls to most other Tcl |
---|
| 36 | procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and |
---|
| 37 | \fBTcl_DeleteInterp\fR. |
---|
| 38 | Clients are only allowed to access a few of the fields of |
---|
| 39 | Tcl_Interp structures; see the \fBTcl_Interp\fR |
---|
| 40 | and \fBTcl_CreateCommand\fR man pages for details. |
---|
| 41 | The new interpreter is initialized with the built-in Tcl commands |
---|
| 42 | and with the variables documented in tclvars(n). To bind in |
---|
| 43 | additional commands, call \fBTcl_CreateCommand\fR. |
---|
| 44 | .PP |
---|
| 45 | \fBTcl_DeleteInterp\fR marks an interpreter as deleted; the interpreter |
---|
| 46 | will eventually be deleted when all calls to \fBTcl_Preserve\fR for it have |
---|
| 47 | been matched by calls to \fBTcl_Release\fR. At that time, all of the |
---|
| 48 | resources associated with it, including variables, procedures, and |
---|
| 49 | application-specific command bindings, will be deleted. After |
---|
| 50 | \fBTcl_DeleteInterp\fR returns any attempt to use \fBTcl_Eval\fR on the |
---|
| 51 | interpreter will fail and return \fBTCL_ERROR\fR. After the call to |
---|
| 52 | \fBTcl_DeleteInterp\fR it is safe to examine the interpreter's result, |
---|
| 53 | query or set the values of variables, define, undefine or retrieve |
---|
| 54 | procedures, and examine the runtime evaluation stack. See below, in the |
---|
| 55 | section \fBINTERPRETERS AND MEMORY MANAGEMENT\fR for details. |
---|
| 56 | .PP |
---|
| 57 | \fBTcl_InterpDeleted\fR returns nonzero if \fBTcl_DeleteInterp\fR was |
---|
| 58 | called with \fIinterp\fR as its argument; this indicates that the |
---|
| 59 | interpreter will eventually be deleted, when the last call to |
---|
| 60 | \fBTcl_Preserve\fR for it is matched by a call to \fBTcl_Release\fR. If |
---|
| 61 | nonzero is returned, further calls to \fBTcl_Eval\fR in this interpreter |
---|
| 62 | will return \fBTCL_ERROR\fR. |
---|
| 63 | .PP |
---|
| 64 | \fBTcl_InterpDeleted\fR is useful in deletion callbacks to distinguish |
---|
| 65 | between when only the memory the callback is responsible for is being |
---|
| 66 | deleted and when the whole interpreter is being deleted. In the former case |
---|
| 67 | the callback may recreate the data being deleted, but this would lead to an |
---|
| 68 | infinite loop if the interpreter were being deleted. |
---|
| 69 | |
---|
| 70 | .SH "INTERPRETERS AND MEMORY MANAGEMENT" |
---|
| 71 | .PP |
---|
| 72 | \fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may |
---|
| 73 | be used by nested evaluations and C code in various extensions. Tcl |
---|
| 74 | implements a simple mechanism that allows callers to use interpreters |
---|
| 75 | without worrying about the interpreter being deleted in a nested call, and |
---|
| 76 | without requiring special code to protect the interpreter, in most cases. |
---|
| 77 | This mechanism ensures that nested uses of an interpreter can safely |
---|
| 78 | continue using it even after \fBTcl_DeleteInterp\fR is called. |
---|
| 79 | .PP |
---|
| 80 | The mechanism relies on matching up calls to \fBTcl_Preserve\fR with calls |
---|
| 81 | to \fBTcl_Release\fR. If \fBTcl_DeleteInterp\fR has been called, only when |
---|
| 82 | the last call to \fBTcl_Preserve\fR is matched by a call to |
---|
| 83 | \fBTcl_Release\fR, will the interpreter be freed. See the manual entry for |
---|
| 84 | \fBTcl_Preserve\fR for a description of these functions. |
---|
| 85 | .PP |
---|
| 86 | The rules for when the user of an interpreter must call \fBTcl_Preserve\fR |
---|
| 87 | and \fBTcl_Release\fR are simple: |
---|
| 88 | .TP |
---|
| 89 | Interpreters Passed As Arguments |
---|
| 90 | Functions that are passed an interpreter as an argument can safely use the |
---|
| 91 | interpreter without any special protection. Thus, when you write an |
---|
| 92 | extension consisting of new Tcl commands, no special code is needed to |
---|
| 93 | protect interpreters received as arguments. This covers the majority of all |
---|
| 94 | uses. |
---|
| 95 | .TP |
---|
| 96 | Interpreter Creation And Deletion |
---|
| 97 | When a new interpreter is created and used in a call to \fBTcl_Eval\fR, |
---|
| 98 | \fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or |
---|
| 99 | \fBTcl_GetVar\fR, a pair of calls to \fBTcl_Preserve\fR and |
---|
| 100 | \fBTcl_Release\fR should be wrapped around all uses of the interpreter. |
---|
| 101 | Remember that it is unsafe to use the interpreter once \fBTcl_Release\fR |
---|
| 102 | has been called. To ensure that the interpreter is properly deleted when |
---|
| 103 | it is no longer needed, call \fBTcl_InterpDeleted\fR to test if some other |
---|
| 104 | code already called \fBTcl_DeleteInterp\fR; if not, call |
---|
| 105 | \fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fR in your own code. |
---|
| 106 | .TP |
---|
| 107 | Retrieving An Interpreter From A Data Structure |
---|
| 108 | When an interpreter is retrieved from a data structure (e.g. the client |
---|
| 109 | data of a callback) for use in \fBTcl_Eval\fR, \fBTcl_VarEval\fR, |
---|
| 110 | \fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or \fBTcl_GetVar\fR, a pair of |
---|
| 111 | calls to \fBTcl_Preserve\fR and \fBTcl_Release\fR should be wrapped around |
---|
| 112 | all uses of the interpreter; it is unsafe to reuse the interpreter once |
---|
| 113 | \fBTcl_Release\fR has been called. If an interpreter is stored inside a |
---|
| 114 | callback data structure, an appropriate deletion cleanup mechanism should |
---|
| 115 | be set up by the code that creates the data structure so that the |
---|
| 116 | interpreter is removed from the data structure (e.g. by setting the field |
---|
| 117 | to NULL) when the interpreter is deleted. Otherwise, you may be using an |
---|
| 118 | interpreter that has been freed and whose memory may already have been |
---|
| 119 | reused. |
---|
| 120 | .PP |
---|
| 121 | All uses of interpreters in Tcl and Tk have already been protected. |
---|
| 122 | Extension writers should ensure that their code also properly protects any |
---|
| 123 | additional interpreters used, as described above. |
---|
| 124 | |
---|
| 125 | .SH "SEE ALSO" |
---|
| 126 | Tcl_Preserve(3), Tcl_Release(3) |
---|
| 127 | |
---|
| 128 | .SH KEYWORDS |
---|
| 129 | command, create, delete, interpreter |
---|