Ubuntu Manpage: Tcl_CreateInterp, Tcl_DeleteInterp, Tcl_InterpActive, Tcl_InterpDeleted

Provided by: tcl8.6-doc_8.6.14+dfsg-1build1_all

NAME

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

SYNOPSIS

       #include <tcl.h>

       Tcl_Interp *
       Tcl_CreateInterp()

       Tcl_DeleteInterp(interp)

       int
       Tcl_InterpDeleted(interp)

       int                                                                                                       2
       Tcl_InterpActive(interp)                                                                                  2

ARGUMENTS

       Tcl_Interp *interp (in)          Token for interpreter to be destroyed or queried.
________________________________________________________________________________________________________________

DESCRIPTION

       Tcl_CreateInterp creates a new interpreter structure and returns a token for it. The token is required in
       calls to most other Tcl procedures, such as Tcl_CreateCommand, Tcl_Eval, and Tcl_DeleteInterp.  The token
       returned by Tcl_CreateInterp may only be passed to Tcl routines  called  from  the  same  thread  as  the
       original  Tcl_CreateInterp  call.   It  is  not safe for multiple threads to pass the same token to Tcl's
       routines.  The new interpreter is initialized with the built-in Tcl commands and with standard  variables
       like  tcl_platform  and  env.  To  bind  in  additional  commands,  call Tcl_CreateCommand, and to create
       additional variables, call Tcl_SetVar.

       Tcl_DeleteInterp marks an interpreter as deleted; the interpreter will eventually  be  deleted  when  all
       calls  to  Tcl_Preserve  for  it  have  been  matched  by  calls to Tcl_Release. At that time, all of the
       resources associated with it, including variables, procedures, and application-specific command bindings,
       will be deleted. After Tcl_DeleteInterp returns any attempt to use Tcl_Eval on the interpreter will  fail
       and  return TCL_ERROR. After the call to Tcl_DeleteInterp it is safe to examine the interpreter's result,
       query or set the values of variables, define, undefine or retrieve procedures, and  examine  the  runtime
       evaluation stack. See below, in the section INTERPRETERS AND MEMORY MANAGEMENT for details.

       Tcl_InterpDeleted  returns  nonzero  if  Tcl_DeleteInterp  was  called  with interp as its argument; this
       indicates that the interpreter will eventually be deleted, when the last call to Tcl_Preserve for  it  is
       matched  by  a call to Tcl_Release. If nonzero is returned, further calls to Tcl_Eval in this interpreter
       will return TCL_ERROR.

       Tcl_InterpDeleted is useful in deletion callbacks  to  distinguish  between  when  only  the  memory  the
       callback  is  responsible  for  is  being deleted and when the whole interpreter is being deleted. In the
       former case the callback may recreate the data being deleted, but this would lead to an infinite loop  if
       the interpreter were being deleted.

       Tcl_InterpActive  is  useful  for  determining  whether  there  is any execution of scripts ongoing in an 2
       interpreter, which is a useful  piece  of  information  when  Tcl  is  embedded  in  a  garbage-collected 2
       environment  and  it  becomes necessary to determine whether the interpreter is a candidate for deletion. 2
       The function returns a true value if the interpreter has at least one active execution running inside it, 2
       and a false value otherwise.

INTERPRETERS AND MEMORY MANAGEMENT

Tcl_DeleteInterp can be called at any time on an interpreter that may be used by nested evaluations and C
code in various extensions. Tcl implements a simple mechanism that allows callers to use interpreters
without worrying about the interpreter being deleted in a nested call, and without requiring special code
to protect the interpreter, in most cases. This mechanism ensures that nested uses of an interpreter can
safely continue using it even after Tcl_DeleteInterp is called.

The mechanism relies on matching up calls to Tcl_Preserve with calls to Tcl_Release. If Tcl_DeleteInterp
has been called, only when the last call to Tcl_Preserve is matched by a call to Tcl_Release, will the
interpreter be freed. See the manual entry for Tcl_Preserve for a description of these functions.

The rules for when the user of an interpreter must call Tcl_Preserve and Tcl_Release are simple:

Interpreters Passed As Arguments
Functions that are passed an interpreter as an argument can safely use the interpreter without any
special protection. Thus, when you write an extension consisting of new Tcl commands, no special
code is needed to protect interpreters received as arguments. This covers the majority of all
uses.

Interpreter Creation And Deletion
When a new interpreter is created and used in a call to Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval,
Tcl_SetVar, or Tcl_GetVar, a pair of calls to Tcl_Preserve and Tcl_Release should be wrapped
around all uses of the interpreter. Remember that it is unsafe to use the interpreter once
Tcl_Release has been called. To ensure that the interpreter is properly deleted when it is no
longer needed, call Tcl_InterpDeleted to test if some other code already called Tcl_DeleteInterp;
if not, call Tcl_DeleteInterp before calling Tcl_Release in your own code.

Retrieving An Interpreter From A Data Structure
When an interpreter is retrieved from a data structure (e.g. the client data of a callback) for
use in one of the evaluation functions (Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_EvalObjv, etc.)
or variable access functions (Tcl_SetVar, Tcl_GetVar, Tcl_SetVar2Ex, etc.), a pair of calls to
Tcl_Preserve and Tcl_Release should be wrapped around all uses of the interpreter; it is unsafe to
reuse the interpreter once Tcl_Release has been called. If an interpreter is stored inside a
callback data structure, an appropriate deletion cleanup mechanism should be set up by the code
that creates the data structure so that the interpreter is removed from the data structure (e.g.
by setting the field to NULL) when the interpreter is deleted. Otherwise, you may be using an
interpreter that has been freed and whose memory may already have been reused.

All uses of interpreters in Tcl and Tk have already been protected. Extension writers should ensure that
their code also properly protects any additional interpreters used, as described above.

Note that the protection mechanisms do not work well with conventional garbage collection systems. When 2
in such a managed environment, Tcl_InterpActive should be used to determine when an interpreter is a 2
candidate for deletion due to inactivity.

KEYWORDS