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_InterpActive, Tcl_InterpDeleted
       - create	and delete Tcl command interpreters

       #include	<tcl.h>

       Tcl_Interp *



       int								       |
       Tcl_InterpActive(interp)						       |

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

       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.  The
       token returned by Tcl_CreateInterp may only be passed to	 Tcl  routines
       called  from the	same thread as the original Tcl_CreateInterp call.  It
       is not safe for multiple	threads	to pass	the same token to  Tcl's  rou-
       tines.	The  new interpreter is	initialized with the built-in Tcl com-
       mands and with standard variables like tcl_platform and env. To bind in
       additional  commands,  call Tcl_CreateCommand, and to create additional
       variables, call Tcl_SetVar.

       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 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, un-
       define or retrieve  procedures,	and  examine  the  runtime  evaluation
       stack. See below, in the	section	INTERPRETERS AND MEMORY	MANAGEMENT for

       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_InterpActive	is useful for determining whether there	is any	execu- |
       tion  of	 scripts ongoing in an interpreter, which is a useful piece of |
       information when	Tcl is embedded	in a garbage-collected environment and |
       it  becomes  necessary to determine whether the interpreter is a	candi- |
       date for	deletion. The function returns a true value if the interpreter |
       has  at least one active	execution running inside it, and a false value |

       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  one  of  the  evaluation
	      functions	 (Tcl_Eval, Tcl_VarEval, Tcl_GlobalEval, Tcl_EvalObjv,
	      etc.) or	variable  access  functions  (Tcl_SetVar,  Tcl_GetVar,
	      Tcl_SetVar2Ex,  etc.),  a	 pair  of  calls  to  Tcl_Preserve and
	      Tcl_Release should be wrapped around  all	 uses  of  the	inter-
	      preter;  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 set-
	      ting 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.

       Note that the protection	mechanisms do not work well with  conventional |
       garbage collection systems. When	in such	a managed environment, Tcl_In- |
       terpActive should be used to determine when an interpreter is a	candi- |
       date for	deletion due to	inactivity.

       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