1Tcl_CreateInterp(3) Tcl Library Procedures Tcl_CreateInterp(3)
2______________________________________________________________________________
6
8 Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, Tcl_InterpDeleted
9 - create and delete Tcl command interpreters
10
12 #include <tcl.h>
13 Tcl_Interp *
15 Tcl_CreateInterp()
16 Tcl_DeleteInterp(interp)
18 int
20 Tcl_InterpDeleted(interp)
21 int │
23 Tcl_InterpActive(interp) │
24
26 Tcl_Interp *interp (in) Token for interpreter to be destroyed
27 or queried.
28______________________________________________________________________________
29
31 Tcl_CreateInterp creates a new interpreter structure and returns a to‐
32 ken for it. The token is required in calls to most other Tcl proce‐
33 dures, such as Tcl_CreateCommand, Tcl_Eval, and Tcl_DeleteInterp. The
34 token returned by Tcl_CreateInterp may only be passed to Tcl routines
35 called from the same thread as the original Tcl_CreateInterp call. It
36 is not safe for multiple threads to pass the same token to Tcl's rou‐
37 tines. The new interpreter is initialized with the built-in Tcl com‐
38 mands and with standard variables like tcl_platform and env. To bind in
39 additional commands, call Tcl_CreateCommand, and to create additional
40 variables, call Tcl_SetVar.
41 Tcl_DeleteInterp marks an interpreter as deleted; the interpreter will
43 eventually be deleted when all calls to Tcl_Preserve for it have been
44 matched by calls to Tcl_Release. At that time, all of the resources as‐
45 sociated with it, including variables, procedures, and application-spe‐
46 cific command bindings, will be deleted. After Tcl_DeleteInterp returns
47 any attempt to use Tcl_Eval on the interpreter will fail and return
48 TCL_ERROR. After the call to Tcl_DeleteInterp it is safe to examine the
49 interpreter's result, query or set the values of variables, define, un‐
50 define or retrieve procedures, and examine the runtime evaluation
51 stack. See below, in the section INTERPRETERS AND MEMORY MANAGEMENT for
52 details.
53 Tcl_InterpDeleted returns nonzero if Tcl_DeleteInterp was called with
55 interp as its argument; this indicates that the interpreter will even‐
56 tually be deleted, when the last call to Tcl_Preserve for it is matched
57 by a call to Tcl_Release. If nonzero is returned, further calls to
58 Tcl_Eval in this interpreter will return TCL_ERROR.
59 Tcl_InterpDeleted is useful in deletion callbacks to distinguish be‐
61 tween when only the memory the callback is responsible for is being
62 deleted and when the whole interpreter is being deleted. In the former
63 case the callback may recreate the data being deleted, but this would
64 lead to an infinite loop if the interpreter were being deleted.
65 Tcl_InterpActive is useful for determining whether there is any execu‐ │
67 tion of scripts ongoing in an interpreter, which is a useful piece of │
68 information when Tcl is embedded in a garbage-collected environment and │
69 it becomes necessary to determine whether the interpreter is a candi‐ │
70 date for deletion. The function returns a true value if the interpreter │
71 has at least one active execution running inside it, and a false value │
72 otherwise.
73
75 Tcl_DeleteInterp can be called at any time on an interpreter that may
76 be used by nested evaluations and C code in various extensions. Tcl im‐
77 plements a simple mechanism that allows callers to use interpreters
78 without worrying about the interpreter being deleted in a nested call,
79 and without requiring special code to protect the interpreter, in most
80 cases. This mechanism ensures that nested uses of an interpreter can
81 safely continue using it even after Tcl_DeleteInterp is called.
82 The mechanism relies on matching up calls to Tcl_Preserve with calls to
84 Tcl_Release. If Tcl_DeleteInterp has been called, only when the last
85 call to Tcl_Preserve is matched by a call to Tcl_Release, will the in‐
86 terpreter be freed. See the manual entry for Tcl_Preserve for a de‐
87 scription of these functions.
88 The rules for when the user of an interpreter must call Tcl_Preserve
90 and Tcl_Release are simple:
91 Interpreters Passed As Arguments
93 Functions that are passed an interpreter as an argument can
94 safely use the interpreter without any special protection. Thus,
95 when you write an extension consisting of new Tcl commands, no
96 special code is needed to protect interpreters received as argu‐
97 ments. This covers the majority of all uses.
98 Interpreter Creation And Deletion
100 When a new interpreter is created and used in a call to
101 Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_SetVar, or Tcl_Get‐
102 Var, a pair of calls to Tcl_Preserve and Tcl_Release should be
103 wrapped around all uses of the interpreter. Remember that it is
104 unsafe to use the interpreter once Tcl_Release has been called.
105 To ensure that the interpreter is properly deleted when it is no
106 longer needed, call Tcl_InterpDeleted to test if some other code
107 already called Tcl_DeleteInterp; if not, call Tcl_DeleteInterp
108 before calling Tcl_Release in your own code.
109 Retrieving An Interpreter From A Data Structure
111 When an interpreter is retrieved from a data structure (e.g. the
112 client data of a callback) for use in one of the evaluation
113 functions (Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_EvalObjv,
114 etc.) or variable access functions (Tcl_SetVar, Tcl_GetVar,
115 Tcl_SetVar2Ex, etc.), a pair of calls to Tcl_Preserve and
116 Tcl_Release should be wrapped around all uses of the inter‐
117 preter; it is unsafe to reuse the interpreter once Tcl_Release
118 has been called. If an interpreter is stored inside a callback
119 data structure, an appropriate deletion cleanup mechanism should
120 be set up by the code that creates the data structure so that
121 the interpreter is removed from the data structure (e.g. by set‐
122 ting the field to NULL) when the interpreter is deleted. Other‐
123 wise, you may be using an interpreter that has been freed and
124 whose memory may already have been reused.
125 All uses of interpreters in Tcl and Tk have already been protected.
127 Extension writers should ensure that their code also properly protects
128 any additional interpreters used, as described above.
129 Note that the protection mechanisms do not work well with conventional │
131 garbage collection systems. When in such a managed environment, Tcl_In‐ │
132 terpActive should be used to determine when an interpreter is a candi‐ │
133 date for deletion due to inactivity.
134
136 Tcl_Preserve(3), Tcl_Release(3)
137
139 command, create, delete, interpreter
140Tcl 7.5 Tcl_CreateInterp(3)