home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / sa104os2.zip / SATHR104.ZIP / SATHER / DOC / MAN / CAT1 / GC.1 < prev   
Text File  |  1994-11-18  |  4KB  |  133 lines
  1.  
  2.  
  3.  
  4. GC_MALLOC(1L)     Misc. Reference Manual Pages      GC_MALLOC(1L)
  5.  
  6.  
  7.  
  8. NAME
  9.      GC_malloc,    GC_malloc_atomic,     GC_free,     GC_realloc,
  10.      GC_enable_incremental,  GC_register_finalizer - Garbage col-
  11.      lecting malloc replacement
  12.  
  13. SYNOPSIS
  14.      #include "gc.h"
  15.      # define malloc(n) GC_malloc(n)
  16.  
  17.      cc ... gc.a
  18.  
  19. DESCRIPTION
  20.      _G_C__m_a_l_l_o_c and _G_C__f_r_e_e are plug-in replacements for  standard
  21.      malloc and free.  However, _G_C__m_a_l_l_o_c will attempt to reclaim
  22.      inaccessible space automaticaly by invoking  a  conservative
  23.      garbage  collector  at  appropriate  points.   The collector
  24.      traverses  all  data  structures  accessible  by   following
  25.      pointers  from  the  machines registers, stack(s), data, and
  26.      bss segments.  Inaccessible structures will be reclaimed.  A
  27.      machine word is considered to be a valid pointer if it is an
  28.      address inside an object allocated by _G_C__m_a_l_l_o_c or friends.
  29.  
  30.      Unlike the standard  implementations  of  malloc,  _G_C__m_a_l_l_o_c
  31.      clears  the  newly allocated storage.  _G_C__m_a_l_l_o_c__a_t_o_m_i_c does
  32.      not.  Furthermore, it informs the collector that the result-
  33.      ing  object  will  never  contain  any  pointers, and should
  34.      therefore not be scanned by the collector.  _G_C__f_r_e_e  can  be
  35.      used  to  deallocate  objects,  but its use is optional, and
  36.      discouraged.  _G_C__r_e_a_l_l_o_c has the standard realloc semantics.
  37.      It   preserves   pointer-free-ness.    _G_C__r_e_g_i_s_t_e_r__f_i_n_a_l_i_z_e_r
  38.      allows for registration of functions that are  invoked  when
  39.      an object becomes inaccessible.
  40.  
  41.      It is also possible to use the  collector  to  find  storage
  42.      leaks   in   programs  destined  to  be  run  with  standard
  43.      malloc/free.  The collector can be compiled for  thread-safe
  44.      operation.   Unlike standard malloc, it is safe to call mal-
  45.      loc after a previous malloc call was interrupted by  a  sig-
  46.      nal, provided the original malloc call is not resumed.
  47.  
  48.      Debugging versions of many of the above  routines  are  pro-
  49.      vided  as  macros.   Their names are identical to the above,
  50.      but consist of all capital letters.  If GC_DEBUG is  defined
  51.      before gc.h is included, these routines do additional check-
  52.      ing, and allow the leak detecting version of  the  collector
  53.      to  produce  slightly  more useful output.  Without GC_DEBUG
  54.      defined, they behave exactly like the lower-case versions.
  55.  
  56.      On some machines, collection will be performed incrementally
  57.      after a call to _G_C__e_n_a_b_l_e__i_n_c_r_e_m_e_n_t_a_l.  This may temporarily
  58.      write protect pages in the heap.  See the  README  file  for
  59.      more  information  on  how  this interacts with system calls
  60.  
  61.  
  62.  
  63. Sun Microsystems   Last change: 20 April 1994                   1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. GC_MALLOC(1L)     Misc. Reference Manual Pages      GC_MALLOC(1L)
  71.  
  72.  
  73.  
  74.      that write to the heap.
  75.  
  76.      Other facilities not discussed here include a C++ interface,
  77.      limited  facilities  to  support  incremental  collection on
  78.      machines without appropriate VM support, provisions for pro-
  79.      viding  more  explicit object layout information to the gar-
  80.      bage collector, more direct support for  ``weak''  pointers,
  81.      etc.
  82.  
  83. SEE ALSO
  84.      The  README  and  gc.h  files  in  the  distribution.   More
  85.      detailed  definitions  of the functions exported by the col-
  86.      lector are given there.  (The above list is not complete.)
  87.  
  88.      Boehm,  H.,  and  M.  Weiser,  "Garbage  Collection  in   an
  89.      Uncooperative  Environment", _S_o_f_t_w_a_r_e _P_r_a_c_t_i_c_e & _E_x_p_e_r_i_e_n_c_e,
  90.      September 1988, pp. 807-820.
  91.  
  92.      The malloc(3) man page.
  93.  
  94. AUTHOR
  95.      Hans-J. Boehm (boehm@parc.xerox.com).  Some of the code  was
  96.      written by others, most notably Alan Demers.
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129. Sun Microsystems   Last change: 20 April 1994                   2
  130.  
  131.  
  132.  
  133.