[ceph.git] / ceph / src / boost / tools / build / src / engine / boehm_gc / doc / leak.html

<HTML>
<HEAD>
<TITLE>Using the Garbage Collector as Leak Detector</title>
</head>
<BODY>
<H1>Using the Garbage Collector as Leak Detector</h1>
The garbage collector may be used as a leak detector.
In this case, the primary function of the collector is to report
objects that were allocated (typically with <TT>GC_MALLOC</tt>),
not deallocated (normally with <TT>GC_FREE</tt>), but are
no longer accessible.  Since the object is no longer accessible,
there in normally no way to deallocate the object at a later time;
thus it can safely be assumed that the object has been "leaked".
<P>
This is substantially different from counting leak detectors,
which simply verify that all allocated objects are eventually
deallocated.  A garbage-collector based leak detector can provide
somewhat more precise information when an object was leaked.
More importantly, it does not report objects that are never
deallocated because they are part of "permanent" data structures.
Thus it does not require all objects to be deallocated at process
exit time, a potentially useless activity that often triggers
large amounts of paging.
<P>
All non-ancient versions of the garbage collector provide
leak detection support.  Version 5.3 adds the following
features:
<OL>
<LI> Leak detection mode can be initiated at run-time by
setting GC_find_leak instead of building the collector with FIND_LEAK
defined.  This variable should be set to a nonzero value
at program startup.
<LI> Leaked objects should be reported and then correctly garbage collected.
Prior versions either reported leaks or functioned as a garbage collector.
</ol>
For the rest of this description we will give instructions that work
with any reasonable version of the collector.
<P>
To use the collector as a leak detector, follow the following steps:
<OL>
<LI> Build the collector with -DFIND_LEAK.  Otherwise use default
build options.
<LI> Change the program so that all allocation and deallocation goes
through the garbage collector.
<LI> Arrange to call <TT>GC_gcollect</tt> at appropriate points to check
for leaks.
(For sufficiently long running programs, this will happen implicitly,
but probably not with sufficient frequency.)
</ol>
The second step can usually be accomplished with the
<TT>-DREDIRECT_MALLOC=GC_malloc</tt> option when the collector is built,
or by defining <TT>malloc</tt>, <TT>calloc</tt>,
<TT>realloc</tt> and <TT>free</tt>
to call the corresponding garbage collector functions.
But this, by itself, will not yield very informative diagnostics,
since the collector does not keep track of information about
how objects were allocated.  The error reports will include
only object addresses.
<P>
For more precise error reports, as much of the program as possible
should use the all uppercase variants of these functions, after
defining <TT>GC_DEBUG</tt>, and then including <TT>gc.h</tt>.
In this environment <TT>GC_MALLOC</tt> is a macro which causes
at least the file name and line number at the allocation point to
be saved as part of the object.  Leak reports will then also include
this information.
<P>
Many collector features (<I>e.g</i> stubborn objects, finalization,
and disappearing links) are less useful in this context, and are not
fully supported.  Their use will usually generate additional bogus
leak reports, since the collector itself drops some associated objects.
<P>
The same is generally true of thread support.  However, as of 6.0alpha4,
correct leak reports should be generated with linuxthreads.
<P>
On a few platforms (currently Solaris/SPARC, Irix, and, with -DSAVE_CALL_CHAIN,
Linux/X86), <TT>GC_MALLOC</tt>
also causes some more information about its call stack to be saved
in the object.  Such information is reproduced in the error
reports in very non-symbolic form, but it can be very useful with the
aid of a debugger.
<H2>An Example</h2>
The following header file <TT>leak_detector.h</tt> is included in the
"include" subdirectory of the distribution:
<PRE>
#define GC_DEBUG
#include "gc.h"
#define malloc(n) GC_MALLOC(n)
#define calloc(m,n) GC_MALLOC((m)*(n))
#define free(p) GC_FREE(p)
#define realloc(p,n) GC_REALLOC((p),(n))
#define CHECK_LEAKS() GC_gcollect()
</pre>
<P>
Assume the collector has been built with -DFIND_LEAK.  (For very
new versions of the collector, we could instead add the statement
<TT>GC_find_leak = 1</tt> as the first statement in <TT>main</tt>.
<P>
The program to be tested for leaks can then look like:
<PRE>
#include "leak_detector.h"

main() {
    int *p[10];
    int i;
    /* GC_find_leak = 1; for new collector versions not 	*/
    /* compiled with -DFIND_LEAK.				*/
    for (i = 0; i < 10; ++i) {
	p[i] = malloc(sizeof(int)+i);
    }
    for (i = 1; i < 10; ++i) {
	free(p[i]);
    }
    for (i = 0; i < 9; ++i) {
	p[i] = malloc(sizeof(int)+i);
    }
    CHECK_LEAKS();
}	
</pre>
<P>
On an Intel X86 Linux system this produces on the stderr stream:
<PRE>
Leaked composite object at 0x806dff0 (leak_test.c:8, sz=4)
</pre>
(On most unmentioned operating systems, the output is similar to this.
If the collector had been built on Linux/X86 with -DSAVE_CALL_CHAIN,
the output would be closer to the Solaris example. For this to work,
the program should not be compiled with -fomit_frame_pointer.)
<P>
On Irix it reports
<PRE>
Leaked composite object at 0x10040fe0 (leak_test.c:8, sz=4)
        Caller at allocation:
                ##PC##= 0x10004910
</pre>
and on Solaris the error report is
<PRE>
Leaked composite object at 0xef621fc8 (leak_test.c:8, sz=4)
        Call chain at allocation:
                args: 4 (0x4), 200656 (0x30FD0)
                ##PC##= 0x14ADC
                args: 1 (0x1), -268436012 (0xEFFFFDD4)
                ##PC##= 0x14A64
</pre>
In the latter two cases some additional information is given about
how malloc was called when the leaked object was allocated.  For
Solaris, the first line specifies the arguments to <TT>GC_debug_malloc</tt>
(the actual allocation routine), The second the program counter inside
main, the third the arguments to <TT>main</tt>, and finally the program
counter inside the caller to main (i.e. in the C startup code).
<P>
In the Irix case, only the address inside the caller to main is given.
<P>
In many cases, a debugger is needed to interpret the additional information.
On systems supporting the "adb" debugger, the <TT>callprocs</tt> script
can be used to replace program counter values with symbolic names.
As of version 6.1, the collector tries to generate symbolic names for
call stacks if it knows how to do so on the platform.  This is true on
Linux/X86, but not on most other platforms.
<H2>Simplified leak detection under Linux</h2>
Since version 6.1, it should be possible to run the collector in leak
detection mode on a program a.out under Linux/X86 as follows:
<OL>
<LI> <I>Ensure that a.out is a single-threaded executable, or you are using
a very recent (7.0alpha7+) collector version on Linux.</i>
On most platforms this does not
work at all for multithreaded programs.
<LI> If possible, ensure that the addr2line program is installed in
/usr/bin.  (It comes with RedHat Linux.)
<LI> If possible, compile a.out with full debug information.
This will improve the quality of the leak reports.  With this approach, it is
no longer necessary to call GC_ routines explicitly, though that can also
improve the quality of the leak reports.
<LI> Build the collector and install it in directory <I>foo</i> as follows:
<UL>
<LI> <TT>configure --prefix=<I>foo</i> --enable-full-debug --enable-redirect-malloc
--disable-threads</tt>
<LI> <TT>make</tt>
<LI> <TT>make install</tt>
</ul>
With a very recent collector on Linux, it may be safe to omit the <TT>--disable-threads</tt>.
<LI> Set environment variables as follows:
<UL>
<LI> LD_PRELOAD=<I>foo</i>/lib/libgc.so
<LI> GC_FIND_LEAK
<LI> You may also want to set GC_PRINT_STATS (to confirm that the collector
is running) and/or GC_LOOP_ON_ABORT (to facilitate debugging from another
window if something goes wrong).
</ul
<LI> Simply run a.out as you normally would.  Note that if you run anything
else (<I>e.g.</i> your editor) with those environment variables set,
it will also be leak tested.  This may or may not be useful and/or
embarrassing.  It can generate
mountains of leak reports if the application wasn't designed to avoid leaks,
<I>e.g.</i> because it's always short-lived.
</ol>
This has not yet been thoroughly tested on large applications, but it's known
to do the right thing on at least some small ones.
</body>
</html>
Commit	Line	Data
7c673cae FG	1	<HTML>
	2	<HEAD>
	3	<TITLE>Using the Garbage Collector as Leak Detector</title>
	4	</head>
	5	<BODY>
	6	<H1>Using the Garbage Collector as Leak Detector</h1>
	7	The garbage collector may be used as a leak detector.
	8	In this case, the primary function of the collector is to report
	9	objects that were allocated (typically with <TT>GC_MALLOC</tt>),
	10	not deallocated (normally with <TT>GC_FREE</tt>), but are
	11	no longer accessible. Since the object is no longer accessible,
	12	there in normally no way to deallocate the object at a later time;
	13	thus it can safely be assumed that the object has been "leaked".
	14	<P>
	15	This is substantially different from counting leak detectors,
	16	which simply verify that all allocated objects are eventually
	17	deallocated. A garbage-collector based leak detector can provide
	18	somewhat more precise information when an object was leaked.
	19	More importantly, it does not report objects that are never
	20	deallocated because they are part of "permanent" data structures.
	21	Thus it does not require all objects to be deallocated at process
	22	exit time, a potentially useless activity that often triggers
	23	large amounts of paging.
	24	<P>
	25	All non-ancient versions of the garbage collector provide
	26	leak detection support. Version 5.3 adds the following
	27	features:
	28	<OL>
	29	<LI> Leak detection mode can be initiated at run-time by
	30	setting GC_find_leak instead of building the collector with FIND_LEAK
	31	defined. This variable should be set to a nonzero value
	32	at program startup.
	33	<LI> Leaked objects should be reported and then correctly garbage collected.
	34	Prior versions either reported leaks or functioned as a garbage collector.
	35	</ol>
	36	For the rest of this description we will give instructions that work
	37	with any reasonable version of the collector.
	38	<P>
	39	To use the collector as a leak detector, follow the following steps:
	40	<OL>
	41	<LI> Build the collector with -DFIND_LEAK. Otherwise use default
	42	build options.
	43	<LI> Change the program so that all allocation and deallocation goes
	44	through the garbage collector.
	45	<LI> Arrange to call <TT>GC_gcollect</tt> at appropriate points to check
	46	for leaks.
	47	(For sufficiently long running programs, this will happen implicitly,
	48	but probably not with sufficient frequency.)
	49	</ol>
	50	The second step can usually be accomplished with the
	51	<TT>-DREDIRECT_MALLOC=GC_malloc</tt> option when the collector is built,
	52	or by defining <TT>malloc</tt>, <TT>calloc</tt>,
	53	<TT>realloc</tt> and <TT>free</tt>
	54	to call the corresponding garbage collector functions.
	55	But this, by itself, will not yield very informative diagnostics,
	56	since the collector does not keep track of information about
	57	how objects were allocated. The error reports will include
	58	only object addresses.
	59	<P>
	60	For more precise error reports, as much of the program as possible
	61	should use the all uppercase variants of these functions, after
	62	defining <TT>GC_DEBUG</tt>, and then including <TT>gc.h</tt>.
	63	In this environment <TT>GC_MALLOC</tt> is a macro which causes
	64	at least the file name and line number at the allocation point to
65	be saved as part of the object. Leak reports will then also include
66	this information.
67	<P>
68	Many collector features (<I>e.g</i> stubborn objects, finalization,
69	and disappearing links) are less useful in this context, and are not
70	fully supported. Their use will usually generate additional bogus
71	leak reports, since the collector itself drops some associated objects.
72	<P>
73	The same is generally true of thread support. However, as of 6.0alpha4,
74	correct leak reports should be generated with linuxthreads.
75	<P>
76	On a few platforms (currently Solaris/SPARC, Irix, and, with -DSAVE_CALL_CHAIN,
77	Linux/X86), <TT>GC_MALLOC</tt>
78	also causes some more information about its call stack to be saved
79	in the object. Such information is reproduced in the error
80	reports in very non-symbolic form, but it can be very useful with the
81	aid of a debugger.
82	<H2>An Example</h2>
83	The following header file <TT>leak_detector.h</tt> is included in the
84	"include" subdirectory of the distribution:
85	<PRE>
86	#define GC_DEBUG
87	#include "gc.h"
88	#define malloc(n) GC_MALLOC(n)
89	#define calloc(m,n) GC_MALLOC((m)*(n))
90	#define free(p) GC_FREE(p)
91	#define realloc(p,n) GC_REALLOC((p),(n))
92	#define CHECK_LEAKS() GC_gcollect()
93	</pre>
94	<P>
95	Assume the collector has been built with -DFIND_LEAK. (For very
96	new versions of the collector, we could instead add the statement
97	<TT>GC_find_leak = 1</tt> as the first statement in <TT>main</tt>.
98	<P>
99	The program to be tested for leaks can then look like:
100	<PRE>
101	#include "leak_detector.h"
102
103	main() {
104	int *p[10];
105	int i;
106	/* GC_find_leak = 1; for new collector versions not */
107	/* compiled with -DFIND_LEAK. */
108	for (i = 0; i < 10; ++i) {
109	p[i] = malloc(sizeof(int)+i);
110	}
111	for (i = 1; i < 10; ++i) {
112	free(p[i]);
113	}
114	for (i = 0; i < 9; ++i) {
115	p[i] = malloc(sizeof(int)+i);
116	}
117	CHECK_LEAKS();
118	}
119	</pre>
120	<P>
121	On an Intel X86 Linux system this produces on the stderr stream:
122	<PRE>
123	Leaked composite object at 0x806dff0 (leak_test.c:8, sz=4)
124	</pre>
125	(On most unmentioned operating systems, the output is similar to this.
126	If the collector had been built on Linux/X86 with -DSAVE_CALL_CHAIN,
127	the output would be closer to the Solaris example. For this to work,
128	the program should not be compiled with -fomit_frame_pointer.)
129	<P>
130	On Irix it reports
131	<PRE>
132	Leaked composite object at 0x10040fe0 (leak_test.c:8, sz=4)
133	Caller at allocation:
134	##PC##= 0x10004910
135	</pre>
136	and on Solaris the error report is
137	<PRE>
138	Leaked composite object at 0xef621fc8 (leak_test.c:8, sz=4)
139	Call chain at allocation:
140	args: 4 (0x4), 200656 (0x30FD0)
141	##PC##= 0x14ADC
142	args: 1 (0x1), -268436012 (0xEFFFFDD4)
143	##PC##= 0x14A64
144	</pre>
145	In the latter two cases some additional information is given about
146	how malloc was called when the leaked object was allocated. For
147	Solaris, the first line specifies the arguments to <TT>GC_debug_malloc</tt>
148	(the actual allocation routine), The second the program counter inside
149	main, the third the arguments to <TT>main</tt>, and finally the program
150	counter inside the caller to main (i.e. in the C startup code).
151	<P>
152	In the Irix case, only the address inside the caller to main is given.
153	<P>
154	In many cases, a debugger is needed to interpret the additional information.
155	On systems supporting the "adb" debugger, the <TT>callprocs</tt> script
156	can be used to replace program counter values with symbolic names.
157	As of version 6.1, the collector tries to generate symbolic names for
158	call stacks if it knows how to do so on the platform. This is true on
159	Linux/X86, but not on most other platforms.
160	<H2>Simplified leak detection under Linux</h2>
161	Since version 6.1, it should be possible to run the collector in leak
162	detection mode on a program a.out under Linux/X86 as follows:
163	<OL>
164	<LI> <I>Ensure that a.out is a single-threaded executable, or you are using
165	a very recent (7.0alpha7+) collector version on Linux.</i>
166	On most platforms this does not
167	work at all for multithreaded programs.
168	<LI> If possible, ensure that the addr2line program is installed in
169	/usr/bin. (It comes with RedHat Linux.)
170	<LI> If possible, compile a.out with full debug information.
171	This will improve the quality of the leak reports. With this approach, it is
172	no longer necessary to call GC_ routines explicitly, though that can also
173	improve the quality of the leak reports.
174	<LI> Build the collector and install it in directory <I>foo</i> as follows:
175	<UL>
176	<LI> <TT>configure --prefix=<I>foo</i> --enable-full-debug --enable-redirect-malloc
177	--disable-threads</tt>
178	<LI> <TT>make</tt>
179	<LI> <TT>make install</tt>
180	</ul>
181	With a very recent collector on Linux, it may be safe to omit the <TT>--disable-threads</tt>.
182	<LI> Set environment variables as follows:
183	<UL>
184	<LI> LD_PRELOAD=<I>foo</i>/lib/libgc.so
185	<LI> GC_FIND_LEAK
186	<LI> You may also want to set GC_PRINT_STATS (to confirm that the collector
187	is running) and/or GC_LOOP_ON_ABORT (to facilitate debugging from another
188	window if something goes wrong).
189	</ul
190	<LI> Simply run a.out as you normally would. Note that if you run anything
191	else (<I>e.g.</i> your editor) with those environment variables set,
192	it will also be leak tested. This may or may not be useful and/or
193	embarrassing. It can generate
194	mountains of leak reports if the application wasn't designed to avoid leaks,
195	<I>e.g.</i> because it's always short-lived.
196	</ol>
197	This has not yet been thoroughly tested on large applications, but it's known
198	to do the right thing on at least some small ones.
199	</body>
200	</html>