Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
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  to-
       ken  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 de-
       tails.	The  new interpreter is	initialized with the built-in Tcl com-
       mands and with the variables documented in tclvars(n).  To bind in  ad-
       ditional	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 as-
       sociated	with it, including variables, procedures, and application-spe-
       cific  command  bindings,  will be deleted.  After Tcl_DeleteInterp re-
       turns any attempt to use	Tcl_Eval on the	interpreter will fail and  re-
       turn  TCL_ERROR.	After the call to Tcl_DeleteInterp it is safe to exam-
       ine the interpreter's result, query or set the values of	variables, de-
       fine,  undefine or retrieve procedures, and examine the runtime evalua-
       tion 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 be-
       tween 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 im-
       plements	 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 in-
       terpreter be freed. See the manual entry	for  Tcl_Preserve  for	a  de-
       scription 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)


Want to link to this manual page? Use this URL:

home | help