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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=Tcl_EventuallyFree.tcl86&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help