Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

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.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(n).  To bind in addi-tional additional
       tional 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 bind-ings, bindings,
       ings, 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 interpreter's
       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 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 inter-preter interpreter
       preter 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 inter-preters interpreters
       preters  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_DeleteIn-terp Tcl_DeleteInterp
       terp 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 func-tions. functions.
       tions.

       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_DeleteIn-terp; Tcl_DeleteInterp;
              terp; 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(3), Tcl_Release(3)


KEYWORDS
       command, create, delete, interpreter



Tcl                                                  7.5                                 Tcl_CreateInterp(3)