2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
5 '\" See the file "license.terms" for information on usage and redistribution
6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
8 .TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
9 .\" The -*- nroff -*- definitions below are for supplemental macros used
10 .\" in Tcl/Tk manual entries.
12 .\" .AP type name in/out ?indent?
13 .\" Start paragraph describing an argument to a library procedure.
14 .\" type is type of argument (int, etc.), in/out is either "in", "out",
15 .\" or "in/out" to describe whether procedure reads or modifies arg,
16 .\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 .\" needed; use .AS below instead)
20 .\" Give maximum sizes of arguments for setting tab stops. Type and
21 .\" name are examples of largest possible arguments that will be passed
22 .\" to .AP later. If args are omitted, default tab stops are used.
25 .\" Start box enclosure. From here until next .BE, everything will be
26 .\" enclosed in one large box.
29 .\" End of box enclosure.
32 .\" Begin code excerpt.
37 .\" .VS ?version? ?br?
38 .\" Begin vertical sidebar, for use in marking newly-changed parts
39 .\" of man pages. The first argument is ignored and used for recording
40 .\" the version when the .VS was added, so that the sidebars can be
41 .\" found and removed when they reach a certain age. If another argument
42 .\" is present, then a line break is forced before starting the sidebar.
45 .\" End of vertical sidebar.
48 .\" Begin an indented unfilled display.
51 .\" End of indented unfilled display.
54 .\" Start of list of standard options for a Tk widget. The manpage
55 .\" argument defines where to look up the standard options; if
56 .\" omitted, defaults to "options". The options follow on successive
57 .\" lines, in three columns separated by tabs.
60 .\" End of list of standard options for a Tk widget.
62 .\" .OP cmdName dbName dbClass
63 .\" Start of description of a specific option. cmdName gives the
64 .\" option's name as specified in the class command, dbName gives
65 .\" the option's name in the option database, and dbClass gives
66 .\" the option's class in the option database.
69 .\" Print arg1 underlined, then print arg2 normally.
72 .\" Print arg1 in quotes, then arg2 normally (for trailing punctuation).
75 .\" Print an open parenthesis, arg1 in quotes, then arg2 normally
76 .\" (for trailing punctuation) and then a closing parenthesis.
78 .\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
82 .\" # Start an argument description
86 . ie !"\\$2"" .TP \\n()Cu
91 \&\\$1 \\fI\\$2\\fP (\\$3)
104 .\" # define tabbing values for .AP
107 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
110 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
111 .nr )C \\n()Bu+\\w'(in/out)'u+2n
113 .AS Tcl_Interp Tcl_CreateInterp in/out
114 .\" # BS - start boxed text
115 .\" # ^y = starting y location
123 .if n \l'\\n(.lu\(ul'
126 .\" # BE - end boxed text (draw box now)
131 .ie n \l'\\n(^lu\(ul'
133 .\" Draw four-sided box normally, but don't draw top of
134 .\" box if the box started on an earlier page.
136 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
139 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
146 .\" # VS - start vertical sidebar
147 .\" # ^Y = starting y location
148 .\" # ^v = 1 (for troff; for nroff this doesn't matter)
152 .ie n 'mc \s12\(br\s0
155 .\" # VE - end of vertical sidebar
163 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
170 .\" # Special macro to handle page bottom: finish off current
171 .\" # box/sidebar if in box/sidebar mode, then invoked standard
172 .\" # page bottom macro.
179 .\" Draw three-sided box if this is the box's first page,
180 .\" draw two sides but no top otherwise.
181 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
182 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
185 .nr ^x \\n(^tu+1v-\\n(^Yu
186 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
199 .\" # DS - begin display
205 .\" # DE - end display
211 .\" # SO - start of list of standard options
213 'ie '\\$1'' .ds So \\fBoptions\\fR
214 'el .ds So \\fB\\$1\\fR
215 .SH "STANDARD OPTIONS"
221 .\" # SE - end of list of standard options
226 See the \\*(So manual entry for details on the standard options.
228 .\" # OP - start of full description for a single option
233 Command-Line Name: \\fB\\$1\\fR
234 Database Name: \\fB\\$2\\fR
235 Database Class: \\fB\\$3\\fR
239 .\" # CS - begin code excerpt
245 .\" # CE - end code excerpt
250 .\" # UL - underline word
254 .\" # QW - apply quotation marks to word
256 .ie '\\*(lq'"' ``\\$1''\\$2
257 .\"" fix emacs highlighting
258 .el \\*(lq\\$1\\*(rq\\$2
260 .\" # PQ - apply parens and quotation marks to word
262 .ie '\\*(lq'"' (``\\$1''\\$2)\\$3
263 .\"" fix emacs highlighting
264 .el (\\*(lq\\$1\\*(rq\\$2)\\$3
266 .\" # QR - quoted range
268 .ie '\\*(lq'"' ``\\$1''\\-``\\$2''\\$3
269 .\"" fix emacs highlighting
270 .el \\*(lq\\$1\\*(rq\\-\\*(lq\\$2\\*(rq\\$3
272 .\" # MT - "empty" string
278 Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, Tcl_InterpDeleted \- create and delete Tcl command interpreters
281 \fB#include <tcl.h>\fR
284 \fBTcl_CreateInterp\fR()
286 \fBTcl_DeleteInterp\fR(\fIinterp\fR)
289 \fBTcl_InterpDeleted\fR(\fIinterp\fR)
293 \fBTcl_InterpActive\fR(\fIinterp\fR)
296 .AS Tcl_Interp *interp
297 .AP Tcl_Interp *interp in
298 Token for interpreter to be destroyed or queried.
302 \fBTcl_CreateInterp\fR creates a new interpreter structure and returns
303 a token for it. The token is required in calls to most other Tcl
304 procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and
305 \fBTcl_DeleteInterp\fR. The token returned by \fBTcl_CreateInterp\fR
306 may only be passed to Tcl routines called from the same thread as
307 the original \fBTcl_CreateInterp\fR call. It is not safe for multiple
308 threads to pass the same token to Tcl's routines.
309 The new interpreter is initialized with the built-in Tcl commands
310 and with standard variables like \fBtcl_platform\fR and \fBenv\fR. To
311 bind in additional commands, call \fBTcl_CreateCommand\fR, and to
312 create additional variables, call \fBTcl_SetVar\fR.
314 \fBTcl_DeleteInterp\fR marks an interpreter as deleted; the interpreter
315 will eventually be deleted when all calls to \fBTcl_Preserve\fR for it have
316 been matched by calls to \fBTcl_Release\fR. At that time, all of the
317 resources associated with it, including variables, procedures, and
318 application-specific command bindings, will be deleted. After
319 \fBTcl_DeleteInterp\fR returns any attempt to use \fBTcl_Eval\fR on the
320 interpreter will fail and return \fBTCL_ERROR\fR. After the call to
321 \fBTcl_DeleteInterp\fR it is safe to examine the interpreter's result,
322 query or set the values of variables, define, undefine or retrieve
323 procedures, and examine the runtime evaluation stack. See below, in the
324 section \fBINTERPRETERS AND MEMORY MANAGEMENT\fR for details.
326 \fBTcl_InterpDeleted\fR returns nonzero if \fBTcl_DeleteInterp\fR was
327 called with \fIinterp\fR as its argument; this indicates that the
328 interpreter will eventually be deleted, when the last call to
329 \fBTcl_Preserve\fR for it is matched by a call to \fBTcl_Release\fR. If
330 nonzero is returned, further calls to \fBTcl_Eval\fR in this interpreter
331 will return \fBTCL_ERROR\fR.
333 \fBTcl_InterpDeleted\fR is useful in deletion callbacks to distinguish
334 between when only the memory the callback is responsible for is being
335 deleted and when the whole interpreter is being deleted. In the former case
336 the callback may recreate the data being deleted, but this would lead to an
337 infinite loop if the interpreter were being deleted.
340 \fBTcl_InterpActive\fR is useful for determining whether there is any
341 execution of scripts ongoing in an interpreter, which is a useful piece of
342 information when Tcl is embedded in a garbage-collected environment and it
343 becomes necessary to determine whether the interpreter is a candidate for
344 deletion. The function returns a true value if the interpreter has at least
345 one active execution running inside it, and a false value otherwise.
347 .SH "INTERPRETERS AND MEMORY MANAGEMENT"
349 \fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may
350 be used by nested evaluations and C code in various extensions. Tcl
351 implements a simple mechanism that allows callers to use interpreters
352 without worrying about the interpreter being deleted in a nested call, and
353 without requiring special code to protect the interpreter, in most cases.
354 This mechanism ensures that nested uses of an interpreter can safely
355 continue using it even after \fBTcl_DeleteInterp\fR is called.
357 The mechanism relies on matching up calls to \fBTcl_Preserve\fR with calls
358 to \fBTcl_Release\fR. If \fBTcl_DeleteInterp\fR has been called, only when
359 the last call to \fBTcl_Preserve\fR is matched by a call to
360 \fBTcl_Release\fR, will the interpreter be freed. See the manual entry for
361 \fBTcl_Preserve\fR for a description of these functions.
363 The rules for when the user of an interpreter must call \fBTcl_Preserve\fR
364 and \fBTcl_Release\fR are simple:
366 \fBInterpreters Passed As Arguments\fR
368 Functions that are passed an interpreter as an argument can safely use the
369 interpreter without any special protection. Thus, when you write an
370 extension consisting of new Tcl commands, no special code is needed to
371 protect interpreters received as arguments. This covers the majority of all
374 \fBInterpreter Creation And Deletion\fR
376 When a new interpreter is created and used in a call to \fBTcl_Eval\fR,
377 \fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or
378 \fBTcl_GetVar\fR, a pair of calls to \fBTcl_Preserve\fR and
379 \fBTcl_Release\fR should be wrapped around all uses of the interpreter.
380 Remember that it is unsafe to use the interpreter once \fBTcl_Release\fR
381 has been called. To ensure that the interpreter is properly deleted when
382 it is no longer needed, call \fBTcl_InterpDeleted\fR to test if some other
383 code already called \fBTcl_DeleteInterp\fR; if not, call
384 \fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fR in your own code.
386 \fBRetrieving An Interpreter From A Data Structure\fR
388 When an interpreter is retrieved from a data structure (e.g. the client
389 data of a callback) for use in one of the evaluation functions
390 (\fBTcl_Eval\fR, \fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_EvalObjv\fR,
391 etc.) or variable access functions (\fBTcl_SetVar\fR, \fBTcl_GetVar\fR,
392 \fBTcl_SetVar2Ex\fR, etc.), a pair of
393 calls to \fBTcl_Preserve\fR and \fBTcl_Release\fR should be wrapped around
394 all uses of the interpreter; it is unsafe to reuse the interpreter once
395 \fBTcl_Release\fR has been called. If an interpreter is stored inside a
396 callback data structure, an appropriate deletion cleanup mechanism should
397 be set up by the code that creates the data structure so that the
398 interpreter is removed from the data structure (e.g. by setting the field
399 to NULL) when the interpreter is deleted. Otherwise, you may be using an
400 interpreter that has been freed and whose memory may already have been
403 All uses of interpreters in Tcl and Tk have already been protected.
404 Extension writers should ensure that their code also properly protects any
405 additional interpreters used, as described above.
408 Note that the protection mechanisms do not work well with conventional garbage
409 collection systems. When in such a managed environment, \fBTcl_InterpActive\fR
410 should be used to determine when an interpreter is a candidate for deletion
414 Tcl_Preserve(3), Tcl_Release(3)
416 command, create, delete, interpreter
OSDN Git Service
