Tcl_InterpDeleted man page on QNX

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

Tcl_CreateInterp(3)	    Tcl Library Procedures	   Tcl_CreateInterp(3)


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

       #include <tcl.h>

       Tcl_Interp *



       Tcl_Interp   *interp   (in)	Token for interpreter to be destroyed.

       Tcl_CreateInterp creates a new  interpreter  structure  and  returns  a
       token  for it.  The token is required in calls to most other Tcl proce‐
       dures,  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 com‐
       mands and with the variables documented	in  tclvars(n).	  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 evalu‐
       ation stack. See below, in the section INTERPRETERS AND MEMORY  MANAGE‐
       MENT for details.

       Tcl_InterpDeleted  returns  nonzero if Tcl_DeleteInterp was called with
       interp as its argument; this indicates that the interpreter will	 even‐
       tually 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.

       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 argu‐
	      ments. 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_Get‐
	      Var, 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 mech‐
	      anism  should be set up by the code that creates the data struc‐
	      ture 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.

       Tcl_Preserve(3), Tcl_Release(3)

       command, create, delete, interpreter

Tcl				      7.5		   Tcl_CreateInterp(3)
                             _         _         _ 
                            | |       | |       | |     
                            | |       | |       | |     
                         __ | | __ __ | | __ __ | | __  
                         \ \| |/ / \ \| |/ / \ \| |/ /  
                          \ \ / /   \ \ / /   \ \ / /   
                           \   /     \   /     \   /    
                            \_/       \_/       \_/ 
More information is available in HTML format for server QNX

List of man pages available for QNX

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]
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