home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / Preserve.3 < prev    next >
Encoding:
Text File  |  1995-07-26  |  7.2 KB  |  133 lines
  1.  
  2.  
  3.  
  4.      TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee((((3333))))               TTTTkkkk (((( ))))                TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee((((3333))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           Tk_Preserve, Tk_Release, Tk_EventuallyFree -  avoid  freeing
  12.           storage while it's being used
  13.  
  14.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.           ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
  16.  
  17.           TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee(_c_l_i_e_n_t_D_a_t_a)
  18.  
  19.           TTTTkkkk____RRRReeeelllleeeeaaaasssseeee(_c_l_i_e_n_t_D_a_t_a)
  20.  
  21.           TTTTkkkk____EEEEvvvveeeennnnttttuuuuaaaallllllllyyyyFFFFrrrreeeeeeee(_c_l_i_e_n_t_D_a_t_a, _f_r_e_e_P_r_o_c)
  22.  
  23.      AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  24.           ClientData    _c_l_i_e_n_t_D_a_t_a   (in)      Token        describing
  25.                                                structure  to  be freed
  26.                                                or         reallocated.
  27.                                                Usually  a  pointer  to
  28.                                                memory for structure.
  29.  
  30.           Tk_FreeProc   *_f_r_e_e_P_r_o_c    (in)      Procedure to invoke  to
  31.                                                free _c_l_i_e_n_t_D_a_t_a.
  32.      _________________________________________________________________
  33.  
  34.  
  35.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  36.           These three procedures help  implement  a  simple  reference
  37.           count  mechanism for managing storage.  They are designed to
  38.           solve a problem having to do with widget deletion.   When  a
  39.           widget  is deleted, its widget record (the structure holding
  40.           information specific to the widget) must be returned to  the
  41.           storage  allocator.   However, it's possible that the widget
  42.           record is in active use by one  of  the  procedures  on  the
  43.           stack  at  the  time  of the deletion.  This can happen, for
  44.           example, if the command  associated  with  a  button  widget
  45.           causes  the  button  to  be destroyed:  an X event causes an
  46.           event-handling C procedure in  the  button  to  be  invoked,
  47.           which  in turn causes the button's associated Tcl command to
  48.           be executed, which in turn causes the button to be  deleted,
  49.           which  in  turn  causes the button's widget record to be de-
  50.           allocated.  Unfortunately, when the Tcl command returns, the
  51.           button's event-handling procedure will need to reference the
  52.           button's widget record.  Because of this, the widget  record
  53.           must  not  be  freed  as  part  of the deletion, but must be
  54.           retained until the  event-handling  procedure  has  finished
  55.           with  it.   In other situations where the widget is deleted,
  56.           it may be possible to free the widget record immediately.
  57.  
  58.           TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee and TTTTkkkk____RRRReeeelllleeeeaaaasssseeee  implement  short-term  reference
  59.           counts   for  their  _c_l_i_e_n_t_D_a_t_a  argument.   The  _c_l_i_e_n_t_D_a_t_a
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/23/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee((((3333))))               TTTTkkkk (((( ))))                TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee((((3333))))
  71.  
  72.  
  73.  
  74.           argument identifies an object and usually  consists  of  the
  75.           address of a structure.  The reference counts guarantee that
  76.           an object will not be freed until each call  to  TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee
  77.           for  the  object  has  been  matched by calls to TTTTkkkk____RRRReeeelllleeeeaaaasssseeee.
  78.           There may be any number of unmatched  TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee  calls  in
  79.           effect at once.
  80.  
  81.           TTTTkkkk____EEEEvvvveeeennnnttttuuuuaaaallllllllyyyyFFFFrrrreeeeeeee is  invoked  to  free  up  its  _c_l_i_e_n_t_D_a_t_a
  82.           argument.    It   checks  to  see  if  there  are  unmatched
  83.           TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee  calls   for   the   object.    If   not,   then
  84.           TTTTkkkk____EEEEvvvveeeennnnttttuuuuaaaallllllllyyyyFFFFrrrreeeeeeee  calls  _f_r_e_e_P_r_o_c  immediately.   Otherwise
  85.           TTTTkkkk____EEEEvvvveeeennnnttttuuuuaaaallllllllyyyyFFFFrrrreeeeeeee records the  fact  that  _c_l_i_e_n_t_D_a_t_a  needs
  86.           eventually  to be freed.  When all calls to TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee have
  87.           been matched with calls to TTTTkkkk____RRRReeeelllleeeeaaaasssseeee then _f_r_e_e_P_r_o_c will  be
  88.           called by TTTTkkkk____RRRReeeelllleeeeaaaasssseeee to do the cleanup.
  89.  
  90.           All the work  of  freeing  the  object  is  carried  out  by
  91.           _f_r_e_e_P_r_o_c.   _F_r_e_e_P_r_o_c  must  have  arguments  and result that
  92.           match the type TTTTkkkk____FFFFrrrreeeeeeeePPPPrrrroooocccc:
  93.                typedef void Tk_FreeProc(ClientData _c_l_i_e_n_t_D_a_t_a);
  94.           The _c_l_i_e_n_t_D_a_t_a argument to _f_r_e_e_P_r_o_c will be the same as  the
  95.           _c_l_i_e_n_t_D_a_t_a argument to TTTTkkkk____EEEEvvvveeeennnnttttuuuuaaaallllllllyyyyFFFFrrrreeeeeeee.
  96.  
  97.           This mechanism can be used to solve  the  problem  described
  98.           above  by  placing  TTTTkkkk____PPPPrrrreeeesssseeeerrrrvvvveeee  and TTTTkkkk____RRRReeeelllleeeeaaaasssseeee calls around
  99.           actions that may cause undesired storage re-allocation.  The
  100.           mechanism  is  intended  only for short-term use (i.e. while
  101.           procedures are pending on the  stack);   it  will  not  work
  102.           efficiently  as  a mechanism for long-term reference counts.
  103.           The implementation  does  not  depend  in  any  way  on  the
  104.           internal structure of the objects being freed;  it keeps the
  105.           reference counts in a separate structure.
  106.  
  107.  
  108.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  109.           free, reference count, storage
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/23/95)
  130.  
  131.  
  132.  
  133.