Manual Pages for UNIX Operating System command usage for man gc

Misc. Reference Manual Pages                        GC_MALLOC(1L)



NAME
     GC_malloc,    GC_malloc_atomic,     GC_free,     GC_realloc,
     GC_enable_incremental,                GC_register_finalizer,
     GC_malloc_ignore_off_page, GC_malloc_atomic_ignore_off_page,
     GC_set_warn_proc - Garbage collecting malloc replacement

SYNOPSIS
     #include "gc.h"
     void * GC_malloc(size_t size);
     void GC_free(void *ptr);
     void * GC_realloc(void *ptr, size_t size);

     cc ... gc.a

DESCRIPTION
     GC_malloc and GC_free are plug-in replacements for  standard
     malloc and free.  However, GC_malloc will attempt to reclaim
     inaccessible space automatically by invoking a  conservative
     garbage  collector  at  appropriate  points.   The collector
     traverses  all  data  structures  accessible  by   following
     pointers  from  the  machines registers, stack(s), data, and
     bss segments.  Inaccessible structures will be reclaimed.  A
     machine word is considered to be a valid pointer if it is an
     address inside an object allocated by GC_malloc or friends.

     In most cases it is preferable to call the macros GC_MALLOC,
     GC_FREE,  etc.   instead  of  calling  GC_malloc and friends
     directly.  This allows debugging versions of the routines to
     be substituted by defining GC_DEBUG before including gc.h.

     See the documentation in the include file  gc_cpp.h  for  an
     alternate, C++ specific interface to the garbage collector.

     Unlike the standard  implementations  of  malloc,  GC_malloc
     clears  the  newly allocated storage.  GC_malloc_atomic does
     not.  Furthermore, it informs the collector that the result-
     ing  object  will  never  contain  any  pointers, and should
     therefore not be scanned by the collector.

     GC_free can be used to deallocate objects, but  its  use  is
     optional,  and  generally  discouraged.   GC_realloc has the
     standard realloc semantics.  It preserves pointer-free-ness.
     GC_register_finalizer  allows  for registration of functions
     that are invoked when an object becomes inaccessible.

     The garbage collector tries to avoid  allocating  memory  at
     locations  that already appear to be referenced before allo-
     cation.   (Such  apparent  ``pointers''  are  usually  large
     integers  and  the  like  that  just  happen to look like an
     address.)  This may make it  hard  to  allocate  very  large
     objects.  An attempt to do so may generate a warning.




SunOS 5.10         Last change: 2 October 2003                  1






Misc. Reference Manual Pages                        GC_MALLOC(1L)



     GC_malloc_ignore_off_page                                and
     GC_malloc_atomic_ignore_off_page  inform  the collector that
     the client code will always maintain a pointer to  near  the
     beginning  of  the  object (within the first 512 bytes), and
     that pointers beyond that can be ignored by  the  collector.
     This  makes  it much easier for the collector to place large
     objects.  These are recommended for large object allocation.
     (Objects  expected  to be larger than about 100KBytes should
     be allocated this way.)

     It is also possible to use the  collector  to  find  storage
     leaks   in   programs  destined  to  be  run  with  standard
     malloc/free.  The collector can be compiled for  thread-safe
     operation.   Unlike standard malloc, it is safe to call mal-
     loc after a previous malloc call was interrupted by  a  sig-
     nal, provided the original malloc call is not resumed.

     The collector may, on rare  occasion  produce  warning  mes-
     sages.   On  UNIX  machines these appear on stderr.  Warning
     messages  can  be  filtered,  redirected,  or  ignored  with
     GC_set_warn_proc  This  is  recommended for production code.
     See gc.h for details.

     Fully portable code should call GC_INIT from the  main  pro-
     gram  before  making  any other GC calls.  On most platforms
     this does nothing and the collector is initialized on  first
     use.   On  a few platforms explicit initialization is neces-
     sary.  And it can never hurt.

     Debugging versions of many of the above  routines  are  pro-
     vided  as  macros.   Their names are identical to the above,
     but consist of all capital letters.  If GC_DEBUG is  defined
     before gc.h is included, these routines do additional check-
     ing, and allow the leak detecting version of  the  collector
     to  produce  slightly  more useful output.  Without GC_DEBUG
     defined, they behave exactly like the lower-case versions.

     On some machines, collection will be performed incrementally
     after a call to GC_enable_incremental.  This may temporarily
     write protect pages in the heap.  See the  README  file  for
     more  information  on  how  this interacts with system calls
     that write to the heap.

     Other facilities not discussed here include limited  facili-
     ties  to  support incremental collection on machines without
     appropriate VM support, provisions for providing more expli-
     cit object layout information to the garbage collector, more
     direct support for ``weak'' pointers, support  for  ``abort-
     able'' garbage collections during idle time, etc.

SEE ALSO
     The  README  and  gc.h  files  in  the  distribution.   More



SunOS 5.10         Last change: 2 October 2003                  2






Misc. Reference Manual Pages                        GC_MALLOC(1L)



     detailed  definitions  of the functions exported by the col-
     lector are given there.  (The above list is not complete.)

     The web site at http://www.hpl.hp.com/personal/Hans_Boehm/gc
     .

     Boehm,  H.,  and  M.  Weiser,  "Garbage  Collection  in   an
     Uncooperative  Environment", Software Practice & Experience,
     September 1988, pp. 807-820.

     The malloc(3) man page.

AUTHOR
     Hans-J. Boehm (Hans.Boehm@hp.com).  Some  of  the  code  was
     written by others, most notably Alan Demers.


ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWlibgc                   |
    |_____________________________|_____________________________|
    | Interface stability         | Uncommitted                 |
    |                             |                             |
    |_____________________________|_____________________________|


























SunOS 5.10         Last change: 2 October 2003                  3