Manual Pages for UNIX Operating System command usage for man Tcl_CreateInterp

Tcl Library Procedures                     Tcl_CreateInterp(3TCL)



_________________________________________________________________

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(1T).
     To bind in additional commands, call Tcl_CreateCommand.

     Tcl_DeleteInterp marks an interpreter as deleted; the inter-
     preter   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, unde-
     fine or retrieve procedures, and examine the runtime evalua-
     tion  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.



Tcl                     Last change: 7.5                        1






Tcl Library Procedures                     Tcl_CreateInterp(3TCL)



     If nonzero is returned, further calls to  Tcl_Eval  in  this
     interpreter will return TCL_ERROR.

     Tcl_InterpDeleted is useful in deletion callbacks to distin-
     guish between when only the memory the callback is responsi-
     ble 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 inter-
     preter   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 pro-
          tection. Thus, when you write an  extension  consisting
          of  new Tcl commands, no special code is needed to pro-
          tect 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.



Tcl                     Last change: 7.5                        2






Tcl Library Procedures                     Tcl_CreateInterp(3TCL)



     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. 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(3TCL), Tcl_Release(3TCL)


KEYWORDS
     command, create, delete, interpreter

ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     _______________________________________
    |   ATTRIBUTE TYPE   |  ATTRIBUTE VALUE|
    |____________________|__________________|_
    | Availability       |  runtime/tcl-8  |
    |____________________|__________________|_
    | Interface Stability|  Uncommitted    |
    |____________________|_________________|

NOTES
     Source for Tcl is available on http://opensolaris.org.












Tcl                     Last change: 7.5                        3