HPUX Preserve[3]

 Tk_Preserve(3)                      Tk                       Tk_Preserve(3)

 Tk Library Procedures                                 Tk Library Procedures





 ___________________________________________________________________________

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

 SYNOPSIS
      #include <tk.h>

      Tk_Preserve(clientData)

      Tk_Release(clientData)

      Tk_EventuallyFree(clientData, freeProc)

 ARGUMENTS
      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
      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



                                    - 1 -        Formatted:  August 11, 1996






 Tk_Preserve(3)                      Tk                       Tk_Preserve(3)

 Tk Library Procedures                                 Tk Library Procedures





      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 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
      free, reference count, storage




















                                    - 2 -        Formatted:  August 11, 1996