util/src/TclTk/tcl8.6.12/doc/CrtInterp.3

   1 '\"
   2 '\" Copyright (c) 1989-1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 .TH Tcl_CreateInterp 3 7.5 Tcl "Tcl Library Procedures"
   9 .so man.macros
  10 .BS
  11 .SH NAME
  12 Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, Tcl_InterpDeleted \- create and delete Tcl command interpreters
  13 .SH SYNOPSIS
  14 .nf
  15 \fB#include <tcl.h>\fR
  16 .sp
  17 Tcl_Interp *
  18 \fBTcl_CreateInterp\fR()
  19 .sp
  20 \fBTcl_DeleteInterp\fR(\fIinterp\fR)
  21 .sp
  22 int
  23 \fBTcl_InterpDeleted\fR(\fIinterp\fR)
  24 .sp
  25 .VS 8.6
  26 int
  27 \fBTcl_InterpActive\fR(\fIinterp\fR)
  28 .VE 8.6
  29 .SH ARGUMENTS
  30 .AS Tcl_Interp *interp
  31 .AP Tcl_Interp *interp in
  32 Token for interpreter to be destroyed or queried.
  33 .BE
  34 .SH DESCRIPTION
  35 .PP
  36 \fBTcl_CreateInterp\fR creates a new interpreter structure and returns
  37 a token for it. The token is required in calls to most other Tcl
  38 procedures, such as \fBTcl_CreateCommand\fR, \fBTcl_Eval\fR, and
  39 \fBTcl_DeleteInterp\fR.  The token returned by \fBTcl_CreateInterp\fR
  40 may only be passed to Tcl routines called from the same thread as
  41 the original \fBTcl_CreateInterp\fR call.  It is not safe for multiple
  42 threads to pass the same token to Tcl's routines.
  43 The new interpreter is initialized with the built-in Tcl commands
  44 and with standard variables like \fBtcl_platform\fR and \fBenv\fR. To
  45 bind in additional commands, call \fBTcl_CreateCommand\fR, and to
  46 create additional variables, call \fBTcl_SetVar\fR.
  47 .PP
  48 \fBTcl_DeleteInterp\fR marks an interpreter as deleted; the interpreter
  49 will eventually be deleted when all calls to \fBTcl_Preserve\fR for it have
  50 been matched by calls to \fBTcl_Release\fR. At that time, all of the
  51 resources associated with it, including variables, procedures, and
  52 application-specific command bindings, will be deleted. After
  53 \fBTcl_DeleteInterp\fR returns any attempt to use \fBTcl_Eval\fR on the
  54 interpreter will fail and return \fBTCL_ERROR\fR. After the call to
  55 \fBTcl_DeleteInterp\fR it is safe to examine the interpreter's result,
  56 query or set the values of variables, define, undefine or retrieve
  57 procedures, and examine the runtime evaluation stack. See below, in the
  58 section \fBINTERPRETERS AND MEMORY MANAGEMENT\fR for details.
  59 .PP
  60 \fBTcl_InterpDeleted\fR returns nonzero if \fBTcl_DeleteInterp\fR was
  61 called with \fIinterp\fR as its argument; this indicates that the
  62 interpreter will eventually be deleted, when the last call to
  63 \fBTcl_Preserve\fR for it is matched by a call to \fBTcl_Release\fR. If
  64 nonzero is returned, further calls to \fBTcl_Eval\fR in this interpreter
  65 will return \fBTCL_ERROR\fR.
  66 .PP
  67 \fBTcl_InterpDeleted\fR is useful in deletion callbacks to distinguish
  68 between when only the memory the callback is responsible for is being
  69 deleted and when the whole interpreter is being deleted. In the former case
  70 the callback may recreate the data being deleted, but this would lead to an
  71 infinite loop if the interpreter were being deleted.
  72 .PP
  73 .VS 8.6
  74 \fBTcl_InterpActive\fR is useful for determining whether there is any
  75 execution of scripts ongoing in an interpreter, which is a useful piece of
  76 information when Tcl is embedded in a garbage-collected environment and it
  77 becomes necessary to determine whether the interpreter is a candidate for
  78 deletion. The function returns a true value if the interpreter has at least
  79 one active execution running inside it, and a false value otherwise.
  80 .VE 8.6
  81 .SH "INTERPRETERS AND MEMORY MANAGEMENT"
  82 .PP
  83 \fBTcl_DeleteInterp\fR can be called at any time on an interpreter that may
  84 be used by nested evaluations and C code in various extensions. Tcl
  85 implements a simple mechanism that allows callers to use interpreters
  86 without worrying about the interpreter being deleted in a nested call, and
  87 without requiring special code to protect the interpreter, in most cases.
  88 This mechanism ensures that nested uses of an interpreter can safely
  89 continue using it even after \fBTcl_DeleteInterp\fR is called.
  90 .PP
  91 The mechanism relies on matching up calls to \fBTcl_Preserve\fR with calls
  92 to \fBTcl_Release\fR. If \fBTcl_DeleteInterp\fR has been called, only when
  93 the last call to \fBTcl_Preserve\fR is matched by a call to
  94 \fBTcl_Release\fR, will the interpreter be freed. See the manual entry for
  95 \fBTcl_Preserve\fR for a description of these functions.
  96 .PP
  97 The rules for when the user of an interpreter must call \fBTcl_Preserve\fR
  98 and \fBTcl_Release\fR are simple:
  99 .TP
 100 \fBInterpreters Passed As Arguments\fR
 101 .
 102 Functions that are passed an interpreter as an argument can safely use the
 103 interpreter without any special protection. Thus, when you write an
 104 extension consisting of new Tcl commands, no special code is needed to
 105 protect interpreters received as arguments. This covers the majority of all
 106 uses.
 107 .TP
 108 \fBInterpreter Creation And Deletion\fR
 109 .
 110 When a new interpreter is created and used in a call to \fBTcl_Eval\fR,
 111 \fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_SetVar\fR, or
 112 \fBTcl_GetVar\fR, a pair of calls to \fBTcl_Preserve\fR and
 113 \fBTcl_Release\fR should be wrapped around all uses of the interpreter.
 114 Remember that it is unsafe to use the interpreter once \fBTcl_Release\fR
 115 has been called. To ensure that the interpreter is properly deleted when
 116 it is no longer needed, call \fBTcl_InterpDeleted\fR to test if some other
 117 code already called \fBTcl_DeleteInterp\fR; if not, call
 118 \fBTcl_DeleteInterp\fR before calling \fBTcl_Release\fR in your own code.
 119 .TP
 120 \fBRetrieving An Interpreter From A Data Structure\fR
 121 .
 122 When an interpreter is retrieved from a data structure (e.g. the client
 123 data of a callback) for use in one of the evaluation functions
 124 (\fBTcl_Eval\fR, \fBTcl_VarEval\fR, \fBTcl_GlobalEval\fR, \fBTcl_EvalObjv\fR,
 125 etc.) or variable access functions (\fBTcl_SetVar\fR, \fBTcl_GetVar\fR,
 126 \fBTcl_SetVar2Ex\fR, etc.), a pair of
 127 calls to \fBTcl_Preserve\fR and \fBTcl_Release\fR should be wrapped around
 128 all uses of the interpreter; it is unsafe to reuse the interpreter once
 129 \fBTcl_Release\fR has been called. If an interpreter is stored inside a
 130 callback data structure, an appropriate deletion cleanup mechanism should
 131 be set up by the code that creates the data structure so that the
 132 interpreter is removed from the data structure (e.g. by setting the field
 133 to NULL) when the interpreter is deleted. Otherwise, you may be using an
 134 interpreter that has been freed and whose memory may already have been
 135 reused.
 136 .PP
 137 All uses of interpreters in Tcl and Tk have already been protected.
 138 Extension writers should ensure that their code also properly protects any
 139 additional interpreters used, as described above.
 140 .PP
 141 .VS 8.6
 142 Note that the protection mechanisms do not work well with conventional garbage
 143 collection systems. When in such a managed environment, \fBTcl_InterpActive\fR
 144 should be used to determine when an interpreter is a candidate for deletion
 145 due to inactivity.
 146 .VE 8.6
 147 .SH "SEE ALSO"
 148 Tcl_Preserve(3), Tcl_Release(3)
 149 .SH KEYWORDS
 150 command, create, delete, interpreter