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

NAME

8       Tcl_CreateInterp,  Tcl_DeleteInterp,  Tcl_InterpDeleted  -  create  and
9       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

ARGUMENTS

23       Tcl_Interp   *interp   (in)      Token for interpreter to be destroyed.
24_________________________________________________________________
25
26

DESCRIPTION

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
37       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
49       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
55       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
61

INTERPRETERS AND MEMORY MANAGEMENT

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
71       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
77       The  rules  for  when the user of an interpreter must call Tcl_Preserve
78       and Tcl_Release are simple:
79
80       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
87       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
98       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
112       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
116

SEE ALSO

118       Tcl_Preserve(3), Tcl_Release(3)
119
120

KEYWORDS

122       command, create, delete, interpreter
123
124
125
126Tcl                                   7.5                  Tcl_CreateInterp(3)
Impressum