NAME

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


SYNOPSIS

       #include <tcl.h>

       Tcl_Interp *
       Tcl_CreateInterp()

       Tcl_DeleteInterp(interp)

       int
       Tcl_InterpDeleted(interp)


ARGUMENTS

       Tcl_Interp   *interp   (in)      Token for interpreter  to
                                        be destroyed.
_________________________________________________________________


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.  Clients are only  allowed
       to  access  a  few of the fields of Tcl_Interp structures;
       see the Tcl_Interp and  Tcl_CreateCommand  man  pages  for
       details.   The  new  interpreter  is  initialized  with no
       defined variables and only the built-in Tcl commands.   To
       bind in additional commands, call Tcl_CreateCommand.

       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 inter­
       preter'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 INTER­
       PRETERS 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.

       tinguish  between  when  only  the  memory the callback is
       responsible for is being deleted and when the whole inter­
       preter  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.


INTERPRETERS AND MEMORY MANAGEMENT

       Tcl_DeleteInterp can be called at any time  on  an  inter­
       preter  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  exten­
              sion  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.   Do   not   call
              Tcl_DeleteInterp   on   an  interpreter  for  which
              Tcl_InterpDeleted returns nonzero.

              When an interpreter is retrieved from a data struc­
              ture  (e.g.  the client data of a callback) for use
              in Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval,  Tcl_Set­
              Var, or Tcl_GetVar, 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  mecha­
              nism  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.  Other­
              wise, 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.


SEE ALSO

       Tcl_Preserve(3), Tcl_Release(3)


KEYWORDS

       command, create, delete, interpreter


Man(1) output converted with man2html