Preserve man page on DigitalUNIX

Man page or keyword search:  
man Server   12896 pages
apropos Keyword Search (all sections)
Output format
DigitalUNIX logo
[printable version]

Tcl_Preserve(3)		    Tcl Library Procedures	       Tcl_Preserve(3)

______________________________________________________________________________

NAME
       Tcl_Preserve,  Tcl_Release,  Tcl_EventuallyFree - avoid freeing storage
       while it's 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'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  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
       object  and usually consists of the address of a structure.  The refer‐
       ence 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.

       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.

KEYWORDS
       free, reference count, storage

Tcl				      7.5		       Tcl_Preserve(3)
[top]

List of man pages available for DigitalUNIX

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net