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

FreeBSD Manual Pages

  
 
  

home | help
Tcl_Preserve(3)		    Tcl	Library	Procedures	       Tcl_Preserve(3)

______________________________________________________________________________

NAME
       Tcl_Preserve,  Tcl_Release,  Tcl_EventuallyFree - avoid freeing storage
       while it	is being used

SYNOPSIS
       #include	<tcl.h>

       Tcl_Preserve(clientData)

       Tcl_Release(clientData)

       Tcl_EventuallyFree(clientData, freeProc)

ARGUMENTS
       ClientData clientData (in)	     Token describing structure	to  be
					     freed  or reallocated.  Usually a
					     pointer to	memory for structure.

       Tcl_FreeProc *freeProc (in)	     Procedure	to  invoke   to	  free
					     clientData.
______________________________________________________________________________

DESCRIPTION
       These  three  procedures	help implement a simple	reference count	mecha-
       nism for	managing storage.  They	are designed to	solve a	problem	having
       to  do  with  widget deletion, but are also useful in many other	situa-
       tions.  When a widget is	deleted,  its  widget  record  (the  structure
       holding	information  specific  to  the widget) must be returned	to the
       storage allocator.  However, it is possible that	the widget  record  is
       in  active use by one of	the procedures on the stack at the time	of the
       deletion.  This can happen, for example,	if the command associated with
       a  button  widget causes	the button to be destroyed:  an	X event	causes
       an event-handling C procedure in	the button to  be  invoked,  which  in
       turn  causes  the button's associated Tcl command to be executed, which
       in turn causes the button to be deleted,	which in turn causes the  but-
       ton's  widget  record  to be de-allocated.  Unfortunately, when the Tcl
       command returns,	the button's event-handling  procedure	will  need  to
       reference  the  button's	 widget	 record.   Because of this, the	widget
       record must not be freed	as part	of the deletion, but must be  retained
       until the event-handling	procedure has finished with it.	 In other sit-
       uations where the widget	is deleted, it may be  possible	 to  free  the
       widget record immediately.

       Tcl_Preserve  and Tcl_Release implement short-term reference counts for
       their clientData	argument.  The clientData argument identifies  an  ob-
       ject and	usually	consists of the	address	of a structure.	 The reference
       counts guarantee	that an	object will not	be freed until	each  call  to
       Tcl_Preserve  for  the object has been matched by calls to Tcl_Release.
       There may be any	number of unmatched Tcl_Preserve calls	in  effect  at
       once.

       Tcl_EventuallyFree  is  invoked to free up its clientData argument.  It
       checks to see if	there are unmatched Tcl_Preserve calls for the object.
       If  not,	then Tcl_EventuallyFree	calls freeProc immediately.  Otherwise
       Tcl_EventuallyFree records the fact that	clientData needs eventually to
       be  freed.  When	all calls to Tcl_Preserve have been matched with calls
       to Tcl_Release then freeProc will be called by Tcl_Release  to  do  the
       cleanup.

       All  the	work of	freeing	the object is carried out by freeProc.	FreeP-
       roc must	have arguments and result that match the type Tcl_FreeProc:

	      typedef void Tcl_FreeProc(
		      char *blockPtr);

       The blockPtr argument to	freeProc will be the same  as  the  clientData
       argument	 to Tcl_EventuallyFree.	 The type of blockPtr (char *) is dif-
       ferent than the type of the clientData argument	to  Tcl_EventuallyFree
       for historical reasons, but the value is	the same.

       When  the  clientData  argument to Tcl_EventuallyFree refers to storage
       allocated and returned by a prior call to Tcl_Alloc,  ckalloc,  or  an-
       other function of the Tcl library, then the freeProc argument should be
       given the special value of TCL_DYNAMIC.

       This mechanism can be used to solve  the	 problem  described  above  by
       placing	Tcl_Preserve  and  Tcl_Release	calls  around actions that may
       cause undesired storage re-allocation.  The mechanism is	intended  only
       for  short-term	use  (i.e. while procedures are	pending	on the stack);
       it will not work	efficiently as a  mechanism  for  long-term  reference
       counts.	 The implementation does not depend in any way on the internal
       structure of the	objects	being freed;  it keeps the reference counts in
       a separate structure.

SEE ALSO
       Tcl_Interp, Tcl_Alloc

KEYWORDS
       free, reference count, storage

Tcl				      7.5		       Tcl_Preserve(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tcl_EventuallyFree.tcl87&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help