*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> Tk/preserve (3)              
Title
Content
Arch
Section
 

Contents


Tk_Preserve(3Tk)					      Tk_Preserve(3Tk)


NAME    [Toc]    [Back]

     Tk_Preserve, Tk_Release, Tk_EventuallyFree	- avoid	freeing	storage	while
     it's being	used

SYNOPSIS    [Toc]    [Back]

     #include <tk.h>

     Tk_Preserve(clientData)

     Tk_Release(clientData)

     Tk_EventuallyFree(clientData, freeProc)

ARGUMENTS    [Toc]    [Back]

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

     Tk_FreeProc   *freeProc	(in)	  Procedure to invoke to free
					  clientData.

DESCRIPTION    [Toc]    [Back]

     These three procedures help implement a simple reference count mechanism
     for managing storage.  They are designed to solve a problem having	to do
     with widget deletion.  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's 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 button'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 situations where	the widget is
     deleted, it may be	possible to free the widget record immediately.

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

     Tk_EventuallyFree is invoked to free up its clientData argument.  It
     checks to see if there are	unmatched Tk_Preserve calls for	the object.
     If	not, then Tk_EventuallyFree calls freeProc immediately.	 Otherwise
     Tk_EventuallyFree records the fact	that clientData	needs eventually to be



									Page 1






Tk_Preserve(3Tk)					      Tk_Preserve(3Tk)



     freed.  When all calls to Tk_Preserve have	been matched with calls	to
     Tk_Release	then freeProc will be called by	Tk_Release to do the cleanup.

     All the work of freeing the object	is carried out by freeProc.  FreeProc
     must have arguments and result that match the type	Tk_FreeProc:
	  typedef void Tk_FreeProc(ClientData clientData);
     The clientData argument to	freeProc will be the same as the clientData
     argument to Tk_EventuallyFree.

     This mechanism can	be used	to solve the problem described above by
     placing Tk_Preserve and Tk_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.

KEYWORDS    [Toc]    [Back]

     free, reference count, storage


									PPPPaaaaggggeeee 2222
[ Back ]
 Similar pages
Name OS Title
dlag2 IRIX w B, with scaling as necessary to avoid over-/underflow
slag2 IRIX w B, with scaling as necessary to avoid over-/underflow
locale IRIX Perl pragma to use and avoid POSIX locales for built-in operations
BIO_new Tru64 BIO allocation and freeing functions
BIO_free Tru64 BIO allocation and freeing functions
BIO_set Tru64 BIO allocation and freeing functions
BIO_free_all Tru64 BIO allocation and freeing functions
BIO_new NetBSD BIO allocation and freeing functions
BIO_vfree Tru64 BIO allocation and freeing functions
volmigrate Tru64 Moves AdvFS domain storage from physical storage to LSM volumes (volmigrate) or from LSM volumes to ...
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service