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  the  built-in  Tcl
       commands  and  with  the  variables  documented  in  tclvars(3tcl).  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 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.

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  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; 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.

SEE ALSO

       Tcl_Preserve(3tcl), Tcl_Release(3tcl)

KEYWORDS

       command, create, delete, interpreter