<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html lang="en-us">
<HEAD>
<meta http-equiv="Content-Type" content="text/html;charset=US-ASCII" >
<TITLE>N2587: Minimal Support for Garbage Collection and Reachability-Based Leak Detection (revised)</title>
<BODY>
<table summary="This table provides identifying information for this document.">
	<tr>
		<th>Doc. No.:</th>
		<td>WG21/N2587<br>
		J16/08-0097</td>
	</tr>
	<tr>
		<th>Date:</th>
		<td>2008-03-16</td>
	</tr>
	<tr>
		<th>Reply to:</th>
		<td>Mike Spertus</td>
		<td>Hans-J. Boehm</td>
	</tr>
	<tr>
		<th>Phone:</th>
		<td>+1-312-961-7140</td>
		<td></td>
	</tr>
	<tr>
		<th>Email:</th>
		<td><a href="mailto:mike_spertus@symantec.com">mike_spertus@symantec.com</a></td>
		<td><a href="mailto:Hans.Boehm@hp.com">Hans.Boehm@hp.com</a></td>
	</tr>
</table>
<H1>N2587: Minimal Garbage Collection Status API</h1>
This is a proposal for a supplemental status API for <A HREF="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2007/n2586.html">
N2586</a>: "Minimal Support for Garbage Collection and Reachability-Based Leak Detection (revised)." At the request of the 
Library Working Group, this API is split into a separate proposal.
<p>
The goal of this proposal is to provide an API that a program can use to determine if garbage collection
or leak detection as described in N2586 is enabled. Reasons this is useful include:
<UL>
<LI>The concern expressed in the Library Working Group that it may be awkward to detect
when garbage collection is enabled on code that relies on behavior that N2586 specifies as undefined in the presence of garbage collection.
<LI>Some programs may wish to behave differently in the presence of garbage collectors or leak detectors. For example,
code that uses the "XOR trick" may choose to call <tt>declare_reachable</tt> when a leak detector is enabled to avoid
spurious leaks being reported, but avoid the overhead (likely just the overhead of calling an empty library function)
of calling <tt>declare_reachable</tt> on each list operation during deployment.
<LI>In a similar vein, this can help leak detectors produce more accurate reports for programs
that are not suitable for running in a garbage collected environment. Since programs that are not suitable for deployment with
garbage collection arguably stand to benefit the most from leak detection, this helps make garbage-collection
based technologies benefit important additional classes programs.
<LI>Analogous APIs have proven useful in memory analysis tools, such as Purify's 
<A href="ftp://ftp.software.ibm.com/software/rational/docs/v2002/dev_tools/purify/html/ht_api_misc.htm"><samp>purify_is_running()</a> API.
</UL>


<H2>Library Wording</H2>
<pre><samp>namespace std {
    enum invalidly_derived_pointer_behavior {
        invalid = 0;
        valid = 1;
        leak_detection = 2;
    };
}
</samp></pre>

<samp>invalidly_derived_pointer_behavior invalidly_derived_pointer_behavior_for_default_allocator()</samp><br/>
<dl>
<dt><i>Returns:</i>
</dt><dd>
<samp>valid</samp> if all dynamically allocated memory is implicitly declared reachable [Note This
guarantess C++03 behavior];<br><samp>invalid</samp> if memory allocated by the global <samp>operator new</samp> is
not declared reachable; <br><samp>leak_detection</samp> in implementation-defined circumstances to indicate that
although C++03 behavior is in effect, external tools such as leak detectors are enabled and may produce
more accurate reports if <samp>declare_reachable</samp> declarations are used.
</dd>
</dl>


<H2>Observations and Issues</H2>
<ul>
<li>We will come up with shorter names prior to the upcoming meeting, but that is a bicycle shed. Essentially, <samp>invalid</samp> means
(minimal) garbage collection may be enabled, <samp>valid</samp> means garbage collection is not enabled, and <samp>leak_detection</samp>
means that that garbage collection is not enabled so program behavior is not affected, but garbage <i>detection</i> is.
<li>The values above are chosen so that leak detection and validity can be considered as bit maps, easing use.
<li>Since the library allocator is required to use <samp>operator new</samp>, this applies to the library allocator as well.
</ul>
