1Tcl_CreateInterp(3)         Tcl Library Procedures         Tcl_CreateInterp(3)
2
3
4
5______________________________________________________________________________
6

NAME

8       Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, Tcl_InterpDeleted
9       - create and delete Tcl command interpreters
10

SYNOPSIS

12       #include <tcl.h>
13
14       Tcl_Interp *
15       Tcl_CreateInterp()
16
17       Tcl_DeleteInterp(interp)
18
19       int
20       Tcl_InterpDeleted(interp)
21
22       int                                                                     │
23       Tcl_InterpActive(interp)                                                │
24

ARGUMENTS

26       Tcl_Interp *interp (in)          Token for interpreter to be  destroyed
27                                        or queried.
28______________________________________________________________________________
29

DESCRIPTION

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
42       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
54       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
60       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
66       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

INTERPRETERS AND MEMORY MANAGEMENT

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
83       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
89       The rules for when the user of an interpreter  must  call  Tcl_Preserve
90       and Tcl_Release are simple:
91
92       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
99       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
110       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
126       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
130       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

SEE ALSO

136       Tcl_Preserve(3), Tcl_Release(3)
137

KEYWORDS

139       command, create, delete, interpreter
140
141
142
143Tcl                                   7.5                  Tcl_CreateInterp(3)
Impressum