Tcl_InterpDeleted man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



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 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
       interp->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			       7.5				1

Tcl_CreateInterp(3)   Tcl Library Procedures  Tcl_CreateInterp(3)

       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.	  Do   not   call
	      Tcl_DeleteInterp	 on   an  interpreter  for  which
	      Tcl_InterpDeleted returns nonzero.

Tcl			       7.5				2

Tcl_CreateInterp(3)   Tcl Library Procedures  Tcl_CreateInterp(3)

       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.

KEYWORDS
       command, create, delete, interpreter

SEE ALSO
       Tcl_Preserve(3), Tcl_Release(3)

Tcl			       7.5				3

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net