Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
BDWGC(3)		   Library Functions Manual		      BDWGC(3)

       GC_malloc,  GC_malloc_atomic,  GC_free, GC_realloc, GC_enable_incremen-
       tal,    GC_register_finalizer,	 GC_malloc_ignore_off_page,    GC_mal-
       loc_atomic_ignore_off_page,  GC_set_warn_proc - Garbage collecting mal-
       loc replacement

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

       cc ... -lgc

       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 appropri-
       ate  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  ob-
       ject 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_DE-
       BUG before including gc.h.

       See the documentation in	the include files gc_cpp.h and gc_allocator.h,
       as  well	 as the file in the distribution, for an	alter-
       nate, C++ specific interface to the garbage collector.  Note  that  C++
       programs	generally need to be careful to	ensure that all	allocated mem-
       ory (whether via	new, malloc, or	STL  allocators)  that	may  point  to
       garbage	collected  memory  is  either  itself garbage collected, or at
       least traced by the 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 resulting	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 reg-
       istration of functions that are invoked when an object becomes inacces-

       The  garbage  collector	tries  to avoid	allocating memory at locations
       that already appear to be referenced before allocation.	(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.

       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	recom-
       mended 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 pro-
       grams 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 malloc after a previous malloc call	was interrupted	 by  a
       signal, provided	the original malloc call is not	resumed.

       The  collector may, on rare occasion produce warning messages.  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  program	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 necessary.  And it can	never hurt.

       Debugging  versions  of	many  of  the  above  routines are provided 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 checking,	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 facilities to sup-
       port incremental	collection on machines without appropriate VM support,
       provisions for providing	more explicit object layout information	to the
       garbage collector, more direct support for ``weak''  pointers,  support
       for ``abortable'' garbage collections during idle time, etc.

       In this (FreeBSD	package) installation, gc.h and	gc_cpp.h will probably
       be found	in /usr/local/include, and the library in /usr/local/lib.

       This library has	been compiled as drop-in replacements for  malloc  and
       free  (which  is	 to  say,  all malloc calls will allocate garbage-col-
       lectable	data).	There is no need to include "gc.h" in your C files un-
       less  you  want	access	to the debugging (and other) functions defined
       there, or unless	you want to explicitly use GC_malloc_uncollectable for
       some  allocations.   Just  link	against	 them whenever you want	either
       garbage collection or leak detection.

       The C++ header file, "gc_cpp.h",	is necessary for C++ programs, to  ob-
       tain  the appropriate definitions of the	new and	delete operators.  The
       comments	in both	of these header	files  presently  provide  far	better
       documentation  for  the package than this man page; look	there for more

       This library is compiled	without	(explicit) support for the  experimen-
       tal gc extension	of g++.	 This may or may not make a difference.

       The  README  and	gc.h files in the distribution.	 More detailed defini-
       tions of	the functions exported by the collector	are given there.  (The
       above list is not complete.)

       The  web	 site at (or

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

       The malloc(3) man page.

       Hans-J. Boehm (  Some of the code	was written by	others
       (see  the  AUTHORS  file	for the	details), most notably by Alan Demers,
       and, recently, Ivan Maidanski.

				  15 Aug 2018			      BDWGC(3)


Want to link to this manual page? Use this URL:

home | help