From 7fd4efa1d0dbab63e6d9bddd1d72fa4aafc8ad52 Mon Sep 17 00:00:00 2001 From: Ivan Maidanski Date: Tue, 26 Jul 2011 14:48:42 +0400 Subject: gc4.1 tarball import --- gc.man | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 gc.man (limited to 'gc.man') diff --git a/gc.man b/gc.man new file mode 100644 index 00000000..73f8318b --- /dev/null +++ b/gc.man @@ -0,0 +1,63 @@ +.TH GC_MALLOC 1L "20 April 1994" +.SH NAME +GC_malloc, GC_malloc_atomic, GC_free, GC_realloc, GC_enable_incremental, GC_register_finalizer \- Garbage collecting malloc replacement +.SH SYNOPSIS +#include "gc.h" +.br +# define malloc(n) GC_malloc(n) +.br +... malloc(...) ... +.br +.sp +cc ... gc.a +.LP +.SH DESCRIPTION +.I GC_malloc +and +.I GC_free +are plug-in replacements for standard malloc and free. However, +.I +GC_malloc +will attempt to reclaim inaccessible space automaticaly 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 +.I +GC_malloc +or friends. +.LP +Unlike the standard implementations of malloc, +.I +GC_malloc +clears the newly allocated storage. +.I +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. +.I +GC_free +can be used to deallocate objects, but its use is optional, and discouraged. +.I +GC_realloc +has the standard realloc semantics. It preserves pointer-free-ness. +.I +GC_register_finalizer +allows for registration of functions that are invoked when an object becomes inaccessible. +.LP +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 malloc after a previous malloc call was interrupted by a signal, provided the original malloc call is not resumed. +.LP +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. +.LP +On some machines, collection will be performed incrementally after a call to +.I +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. +.LP +Other facilities not discussed here include a C++ interface, limited facilities to support 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, etc. +.LP +.SH "SEE ALSO" +The README and gc.h files in the distribution. More detailed definitions of the functions exported by the collector are given there. (The above list is not complete.) +.LP +Boehm, H., and M. Weiser, "Garbage Collection in an Uncooperative Environment", +\fISoftware Practice & Experience\fP, September 1988, pp. 807-820. +.LP +The malloc(3) man page. +.LP +.SH AUTHOR +Hans-J. Boehm (boehm@parc.xerox.com). Some of the code was written by others, most notably Alan Demers. -- cgit v1.2.1