Tcl_CreateInterp(3)   Tcl Library Procedures  Tcl_CreateInterp(3)



_________________________________________________________________

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

SYNOPSIS
       #include 

       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(n).  To bind in additional commands, call Tcl_Cre-
       ateCommand.

       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.

       Tcl_InterpDeleted  is useful in deletion callbacks to dis-
       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.

       Retrieving An Interpreter From A Data Structure
              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



Tcl                            7.5            Tcl_CreateInterp(3)