[ceph.git] / ceph / src / boost / tools / build / src / engine / boehm_gc / doc / gc.man

.TH GC_MALLOC 1L "2 October 2003"
.SH 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
.SH SYNOPSIS
#include "gc.h"
.br
void * GC_malloc(size_t size);
.br
void GC_free(void *ptr);
.br
void * GC_realloc(void *ptr, size_t size);
.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 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
.I
GC_malloc
or friends.
.LP
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.
.LP
See the documentation in the include file gc_cpp.h for an alternate, C++ specific interface to the garbage collector.
.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.
.LP
.I
GC_free
can be used to deallocate objects, but its use is optional, and generally 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
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.
.LP
.I
GC_malloc_ignore_off_page
and
.I
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.)
.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
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
.I
GC_set_warn_proc
This is recommended for production code.  See gc.h for details.
.LP
Fully portable code should call
.I
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. 
.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 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, support for ``abortable'' garbage collections during idle time, 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
The web site at http://www.hpl.hp.com/personal/Hans_Boehm/gc .
.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 (Hans.Boehm@hp.com).
Some of the code was written by others, most notably Alan Demers.
Commit	Line	Data
7c673cae FG	1	.TH GC_MALLOC 1L "2 October 2003"
	2	.SH NAME
	3	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
	4	.SH SYNOPSIS
	5	#include "gc.h"
	6	.br
	7	void * GC_malloc(size_t size);
	8	.br
	9	void GC_free(void *ptr);
	10	.br
	11	void * GC_realloc(void *ptr, size_t size);
	12	.br
	13	.sp
	14	cc ... gc.a
	15	.LP
	16	.SH DESCRIPTION
	17	.I GC_malloc
	18	and
	19	.I GC_free
	20	are plug-in replacements for standard malloc and free. However,
	21	.I
	22	GC_malloc
	23	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
	24	.I
	25	GC_malloc
	26	or friends.
	27	.LP
	28	In most cases it is preferable to call the macros GC_MALLOC, GC_FREE, etc.
	29	instead of calling GC_malloc and friends directly. This allows debugging
	30	versions of the routines to be substituted by defining GC_DEBUG before
	31	including gc.h.
	32	.LP
	33	See the documentation in the include file gc_cpp.h for an alternate, C++ specific interface to the garbage collector.
	34	.LP
	35	Unlike the standard implementations of malloc,
	36	.I
	37	GC_malloc
	38	clears the newly allocated storage.
	39	.I
	40	GC_malloc_atomic
	41	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.
	42	.LP
	43	.I
	44	GC_free
	45	can be used to deallocate objects, but its use is optional, and generally discouraged.
	46	.I
	47	GC_realloc
	48	has the standard realloc semantics. It preserves pointer-free-ness.
	49	.I
	50	GC_register_finalizer
	51	allows for registration of functions that are invoked when an object becomes inaccessible.
	52	.LP
	53	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.
	54	.LP
	55	.I
	56	GC_malloc_ignore_off_page
	57	and
	58	.I
	59	GC_malloc_atomic_ignore_off_page
	60	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.)
	61	.LP
	62	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.
	63	.LP
	64	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
65	.I
66	GC_set_warn_proc
67	This is recommended for production code. See gc.h for details.
68	.LP
69	Fully portable code should call
70	.I
71	GC_INIT
72	from the main program before making any other GC calls.
73	On most platforms this does nothing and the collector is initialized on first use.
74	On a few platforms explicit initialization is necessary. And it can never hurt.
75	.LP
76	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.
77	.LP
78	On some machines, collection will be performed incrementally after a call to
79	.I
80	GC_enable_incremental.
81	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.
82	.LP
83	Other facilities not discussed here include 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, support for ``abortable'' garbage collections during idle time, etc.
84	.LP
85	.SH "SEE ALSO"
86	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.)
87	.LP
88	The web site at http://www.hpl.hp.com/personal/Hans_Boehm/gc .
89	.LP
90	Boehm, H., and M. Weiser, "Garbage Collection in an Uncooperative Environment",
91	\fISoftware Practice & Experience\fP, September 1988, pp. 807-820.
92	.LP
93	The malloc(3) man page.
94	.LP
95	.SH AUTHOR
96	Hans-J. Boehm (Hans.Boehm@hp.com).
97	Some of the code was written by others, most notably Alan Demers.