1Tcl_CreateInterp(3) Tcl Library Procedures Tcl_CreateInterp(3)
2______________________________________________________________________________
6
8 Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpDeleted - create and
9 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
23 Tcl_Interp *interp (in) Token for interpreter to be destroyed.
24_________________________________________________________________
25
28 Tcl_CreateInterp creates a new interpreter structure and returns a
29 token for it. The token is required in calls to most other Tcl proce‐
30 dures, such as Tcl_CreateCommand, Tcl_Eval, and Tcl_DeleteInterp.
31 Clients are only allowed to access a few of the fields of Tcl_Interp
32 structures; see the Tcl_Interp and Tcl_CreateCommand man pages for
33 details. The new interpreter is initialized with the built-in Tcl com‐
34 mands and with the variables documented in tclvars(n). To bind in
35 additional commands, call Tcl_CreateCommand.
36 Tcl_DeleteInterp marks an interpreter as deleted; the interpreter will
38 eventually be deleted when all calls to Tcl_Preserve for it have been
39 matched by calls to Tcl_Release. At that time, all of the resources
40 associated with it, including variables, procedures, and application-
41 specific command bindings, will be deleted. After Tcl_DeleteInterp
42 returns any attempt to use Tcl_Eval on the interpreter will fail and
43 return TCL_ERROR. After the call to Tcl_DeleteInterp it is safe to
44 examine the interpreter's result, query or set the values of variables,
45 define, undefine or retrieve procedures, and examine the runtime evalu‐
46 ation stack. See below, in the section INTERPRETERS AND MEMORY MANAGE‐
47 MENT for details.
48 Tcl_InterpDeleted returns nonzero if Tcl_DeleteInterp was called with
50 interp as its argument; this indicates that the interpreter will even‐
51 tually be deleted, when the last call to Tcl_Preserve for it is matched
52 by a call to Tcl_Release. If nonzero is returned, further calls to
53 Tcl_Eval in this interpreter will return TCL_ERROR.
54 Tcl_InterpDeleted is useful in deletion callbacks to distinguish
56 between when only the memory the callback is responsible for is being
57 deleted and when the whole interpreter is being deleted. In the former
58 case the callback may recreate the data being deleted, but this would
59 lead to an infinite loop if the interpreter were being deleted.
60
63 Tcl_DeleteInterp can be called at any time on an interpreter that may
64 be used by nested evaluations and C code in various extensions. Tcl
65 implements a simple mechanism that allows callers to use interpreters
66 without worrying about the interpreter being deleted in a nested call,
67 and without requiring special code to protect the interpreter, in most
68 cases. This mechanism ensures that nested uses of an interpreter can
69 safely continue using it even after Tcl_DeleteInterp is called.
70 The mechanism relies on matching up calls to Tcl_Preserve with calls to
72 Tcl_Release. If Tcl_DeleteInterp has been called, only when the last
73 call to Tcl_Preserve is matched by a call to Tcl_Release, will the
74 interpreter be freed. See the manual entry for Tcl_Preserve for a
75 description of these functions.
76 The rules for when the user of an interpreter must call Tcl_Preserve
78 and Tcl_Release are simple:
79 Interpreters Passed As Arguments
81 Functions that are passed an interpreter as an argument can
82 safely use the interpreter without any special protection. Thus,
83 when you write an extension consisting of new Tcl commands, no
84 special code is needed to protect interpreters received as argu‐
85 ments. This covers the majority of all uses.
86 Interpreter Creation And Deletion
88 When a new interpreter is created and used in a call to
89 Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_SetVar, or Tcl_Get‐
90 Var, a pair of calls to Tcl_Preserve and Tcl_Release should be
91 wrapped around all uses of the interpreter. Remember that it is
92 unsafe to use the interpreter once Tcl_Release has been called.
93 To ensure that the interpreter is properly deleted when it is no
94 longer needed, call Tcl_InterpDeleted to test if some other code
95 already called Tcl_DeleteInterp; if not, call Tcl_DeleteInterp
96 before calling Tcl_Release in your own code.
97 Retrieving An Interpreter From A Data Structure
99 When an interpreter is retrieved from a data structure (e.g. the
100 client data of a callback) for use in Tcl_Eval, Tcl_VarEval,
101 Tcl_GlobalEval, Tcl_SetVar, or Tcl_GetVar, a pair of calls to
102 Tcl_Preserve and Tcl_Release should be wrapped around all uses
103 of the interpreter; it is unsafe to reuse the interpreter once
104 Tcl_Release has been called. If an interpreter is stored inside
105 a callback data structure, an appropriate deletion cleanup mech‐
106 anism should be set up by the code that creates the data struc‐
107 ture so that the interpreter is removed from the data structure
108 (e.g. by setting the field to NULL) when the interpreter is
109 deleted. Otherwise, you may be using an interpreter that has
110 been freed and whose memory may already have been reused.
111 All uses of interpreters in Tcl and Tk have already been protected.
113 Extension writers should ensure that their code also properly protects
114 any additional interpreters used, as described above.
115
118 Tcl_Preserve(3), Tcl_Release(3)
119
122 command, create, delete, interpreter
123Tcl 7.5 Tcl_CreateInterp(3)