libstdc++-v3/doc/html/manual/bk01pt03ch17s04.html

   1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Design</title><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><meta name="keywords" content="
   2       C++
   3     ,
   4       library
   5     ,
   6       debug
   7     "><meta name="keywords" content="
   8       ISO C++
   9     ,
  10       library
  11     "><meta name="keywords" content="
  12       ISO C++
  13     ,
  14       runtime
  15     ,
  16       library
  17     "><link rel="home" href="../index.html" title="The GNU C++ Library"><link rel="up" href="debug_mode.html" title="Chapter 17. Debug Mode"><link rel="prev" href="bk01pt03ch17s03.html" title="Using"><link rel="next" href="parallel_mode.html" title="Chapter 18. Parallel Mode"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Design</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="bk01pt03ch17s03.html">Prev</a> </td><th width="60%" align="center">Chapter 17. Debug Mode</th><td width="20%" align="right"> <a accesskey="n" href="parallel_mode.html">Next</a></td></tr></table><hr></div><div class="section" title="Design"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="manual.ext.debug_mode.design"></a>Design</h2></div></div></div><p>
  18   </p><div class="section" title="Goals"><div class="titlepage"><div><div><h3 class="title"><a name="debug_mode.design.goals"></a>Goals</h3></div></div></div><p>
  19     </p><p> The libstdc++ debug mode replaces unsafe (but efficient) standard
  20   containers and iterators with semantically equivalent safe standard
  21   containers and iterators to aid in debugging user programs. The
  22   following goals directed the design of the libstdc++ debug mode:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Correctness</em></span>: the libstdc++ debug mode must not change
  23     the semantics of the standard library for all cases specified in
  24     the ANSI/ISO C++ standard. The essence of this constraint is that
  25     any valid C++ program should behave in the same manner regardless
  26     of whether it is compiled with debug mode or release mode. In
  27     particular, entities that are defined in namespace std in release
  28     mode should remain defined in namespace std in debug mode, so that
  29     legal specializations of namespace std entities will remain
  30     valid. A program that is not valid C++ (e.g., invokes undefined
  31     behavior) is not required to behave similarly, although the debug
  32     mode will abort with a diagnostic when it detects undefined
  33     behavior.</p></li><li class="listitem"><p><span class="emphasis"><em>Performance</em></span>: the additional of the libstdc++ debug mode
  34     must not affect the performance of the library when it is compiled
  35     in release mode. Performance of the libstdc++ debug mode is
  36     secondary (and, in fact, will be worse than the release
  37     mode).</p></li><li class="listitem"><p><span class="emphasis"><em>Usability</em></span>: the libstdc++ debug mode should be easy to
  38     use. It should be easily incorporated into the user's development
  39     environment (e.g., by requiring only a single new compiler switch)
  40     and should produce reasonable diagnostics when it detects a
  41     problem with the user program. Usability also involves detection
  42     of errors when using the debug mode incorrectly, e.g., by linking
  43     a release-compiled object against a debug-compiled object if in
  44     fact the resulting program will not run correctly.</p></li><li class="listitem"><p><span class="emphasis"><em>Minimize recompilation</em></span>: While it is expected that
  45     users recompile at least part of their program to use debug
  46     mode, the amount of recompilation affects the
  47     detect-compile-debug turnaround time. This indirectly affects the
  48     usefulness of the debug mode, because debugging some applications
  49     may require rebuilding a large amount of code, which may not be
  50     feasible when the suspect code may be very localized. There are
  51     several levels of conformance to this requirement, each with its
  52     own usability and implementation characteristics. In general, the
  53     higher-numbered conformance levels are more usable (i.e., require
  54     less recompilation) but are more complicated to implement than
  55     the lower-numbered conformance levels.
  56       </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Full recompilation</em></span>: The user must recompile his or
  57         her entire application and all C++ libraries it depends on,
  58         including the C++ standard library that ships with the
  59         compiler. This must be done even if only a small part of the
  60         program can use debugging features.</p></li><li class="listitem"><p><span class="emphasis"><em>Full user recompilation</em></span>: The user must recompile
  61         his or her entire application and all C++ libraries it depends
  62         on, but not the C++ standard library itself. This must be done
  63         even if only a small part of the program can use debugging
  64         features. This can be achieved given a full recompilation
  65         system by compiling two versions of the standard library when
  66         the compiler is installed and linking against the appropriate
  67         one, e.g., a multilibs approach.</p></li><li class="listitem"><p><span class="emphasis"><em>Partial recompilation</em></span>: The user must recompile the
  68         parts of his or her application and the C++ libraries it
  69         depends on that will use the debugging facilities
  70         directly. This means that any code that uses the debuggable
  71         standard containers would need to be recompiled, but code
  72         that does not use them (but may, for instance, use IOStreams)
  73         would not have to be recompiled.</p></li><li class="listitem"><p><span class="emphasis"><em>Per-use recompilation</em></span>: The user must recompile the
  74         parts of his or her application and the C++ libraries it
  75         depends on where debugging should occur, and any other code
  76         that interacts with those containers. This means that a set of
  77         translation units that accesses a particular standard
  78         container instance may either be compiled in release mode (no
  79         checking) or debug mode (full checking), but must all be
  80         compiled in the same way; a translation unit that does not see
  81         that standard container instance need not be recompiled. This
  82         also means that a translation unit <span class="emphasis"><em>A</em></span> that contains a
  83         particular instantiation
  84         (say, <code class="code">std::vector&lt;int&gt;</code>) compiled in release
  85         mode can be linked against a translation unit <span class="emphasis"><em>B</em></span> that
  86         contains the same instantiation compiled in debug mode (a
  87         feature not present with partial recompilation). While this
  88         behavior is technically a violation of the One Definition
  89         Rule, this ability tends to be very important in
  90         practice. The libstdc++ debug mode supports this level of
  91         recompilation. </p></li><li class="listitem"><p><span class="emphasis"><em>Per-unit recompilation</em></span>: The user must only
  92         recompile the translation units where checking should occur,
  93         regardless of where debuggable standard containers are
  94         used. This has also been dubbed "<code class="code">-g</code> mode",
  95         because the <code class="code">-g</code> compiler switch works in this way,
  96         emitting debugging information at a per--translation-unit
  97         granularity. We believe that this level of recompilation is in
  98         fact not possible if we intend to supply safe iterators, leave
  99         the program semantics unchanged, and not regress in
 100         performance under release mode because we cannot associate
 101         extra information with an iterator (to form a safe iterator)
 102         without either reserving that space in release mode
 103         (performance regression) or allocating extra memory associated
 104         with each iterator with <code class="code">new</code> (changes the program
 105         semantics).</p></li></ol></div><p>
 106     </p></li></ul></div></div><div class="section" title="Methods"><div class="titlepage"><div><div><h3 class="title"><a name="debug_mode.design.methods"></a>Methods</h3></div></div></div><p>
 107     </p><p>This section provides an overall view of the design of the
 108   libstdc++ debug mode and details the relationship between design
 109   decisions and the stated design goals.</p><div class="section" title="The Wrapper Model"><div class="titlepage"><div><div><h4 class="title"><a name="debug_mode.design.methods.wrappers"></a>The Wrapper Model</h4></div></div></div><p>The libstdc++ debug mode uses a wrapper model where the
 110   debugging versions of library components (e.g., iterators and
 111   containers) form a layer on top of the release versions of the
 112   library components. The debugging components first verify that the
 113   operation is correct (aborting with a diagnostic if an error is
 114   found) and will then forward to the underlying release-mode
 115   container that will perform the actual work. This design decision
 116   ensures that we cannot regress release-mode performance (because the
 117   release-mode containers are left untouched) and partially
 118   enables <a class="link" href="bk01pt03ch17s04.html#methods.coexistence.link" title="Link- and run-time coexistence of release- and debug-mode components">mixing debug and
 119   release code</a> at link time, although that will not be
 120   discussed at this time.</p><p>Two types of wrappers are used in the implementation of the debug
 121   mode: container wrappers and iterator wrappers. The two types of
 122   wrappers interact to maintain relationships between iterators and
 123   their associated containers, which are necessary to detect certain
 124   types of standard library usage errors such as dereferencing
 125   past-the-end iterators or inserting into a container using an
 126   iterator from a different container.</p><div class="section" title="Safe Iterators"><div class="titlepage"><div><div><h5 class="title"><a name="debug_mode.design.methods.safe_iter"></a>Safe Iterators</h5></div></div></div><p>Iterator wrappers provide a debugging layer over any iterator that
 127   is attached to a particular container, and will manage the
 128   information detailing the iterator's state (singular,
 129   dereferenceable, etc.) and tracking the container to which the
 130   iterator is attached. Because iterators have a well-defined, common
 131   interface the iterator wrapper is implemented with the iterator
 132   adaptor class template <code class="code">__gnu_debug::_Safe_iterator</code>,
 133   which takes two template parameters:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="code">Iterator</code>: The underlying iterator type, which must
 134     be either the <code class="code">iterator</code> or <code class="code">const_iterator</code>
 135     typedef from the sequence type this iterator can reference.</p></li><li class="listitem"><p><code class="code">Sequence</code>: The type of sequence that this iterator
 136   references. This sequence must be a safe sequence (discussed below)
 137   whose <code class="code">iterator</code> or <code class="code">const_iterator</code> typedef
 138   is the type of the safe iterator.</p></li></ul></div></div><div class="section" title="Safe Sequences (Containers)"><div class="titlepage"><div><div><h5 class="title"><a name="debug_mode.design.methods.safe_seq"></a>Safe Sequences (Containers)</h5></div></div></div><p>Container wrappers provide a debugging layer over a particular
 139   container type. Because containers vary greatly in the member
 140   functions they support and the semantics of those member functions
 141   (especially in the area of iterator invalidation), container
 142   wrappers are tailored to the container they reference, e.g., the
 143   debugging version of <code class="code">std::list</code> duplicates the entire
 144   interface of <code class="code">std::list</code>, adding additional semantic
 145   checks and then forwarding operations to the
 146   real <code class="code">std::list</code> (a public base class of the debugging
 147   version) as appropriate. However, all safe containers inherit from
 148   the class template <code class="code">__gnu_debug::_Safe_sequence</code>,
 149   instantiated with the type of the safe container itself (an instance
 150   of the curiously recurring template pattern).</p><p>The iterators of a container wrapper will be
 151   <a class="link" href="bk01pt03ch17s04.html#debug_mode.design.methods.safe_iter" title="Safe Iterators">safe
 152   iterators</a> that reference sequences of this type and wrap the
 153   iterators provided by the release-mode base class. The debugging
 154   container will use only the safe iterators within its own interface
 155   (therefore requiring the user to use safe iterators, although this
 156   does not change correct user code) and will communicate with the
 157   release-mode base class with only the underlying, unsafe,
 158   release-mode iterators that the base class exports.</p><p> The debugging version of <code class="code">std::list</code> will have the
 159   following basic structure:</p><pre class="programlisting">
 160 template&lt;typename _Tp, typename _Allocator = allocator&lt;_Tp&gt;
 161   class debug-list :
 162     public release-list&lt;_Tp, _Allocator&gt;,
 163     public __gnu_debug::_Safe_sequence&lt;debug-list&lt;_Tp, _Allocator&gt; &gt;
 164   {
 165     typedef release-list&lt;_Tp, _Allocator&gt; _Base;
 166     typedef debug-list&lt;_Tp, _Allocator&gt;   _Self;
 167
 168   public:
 169     typedef __gnu_debug::_Safe_iterator&lt;typename _Base::iterator, _Self&gt;       iterator;
 170     typedef __gnu_debug::_Safe_iterator&lt;typename _Base::const_iterator, _Self&gt; const_iterator;
 171
 172     // duplicate std::list interface with debugging semantics
 173   };
 174 </pre></div></div><div class="section" title="Precondition Checking"><div class="titlepage"><div><div><h4 class="title"><a name="debug_mode.design.methods.precond"></a>Precondition Checking</h4></div></div></div><p>The debug mode operates primarily by checking the preconditions of
 175   all standard library operations that it supports. Preconditions that
 176   are always checked (regardless of whether or not we are in debug
 177   mode) are checked via the <code class="code">__check_xxx</code> macros defined
 178   and documented in the source
 179   file <code class="code">include/debug/debug.h</code>. Preconditions that may or
 180   may not be checked, depending on the debug-mode
 181   macro <code class="code">_GLIBCXX_DEBUG</code>, are checked via
 182   the <code class="code">__requires_xxx</code> macros defined and documented in the
 183   same source file. Preconditions are validated using any additional
 184   information available at run-time, e.g., the containers that are
 185   associated with a particular iterator, the position of the iterator
 186   within those containers, the distance between two iterators that may
 187   form a valid range, etc. In the absence of suitable information,
 188   e.g., an input iterator that is not a safe iterator, these
 189   precondition checks will silently succeed.</p><p>The majority of precondition checks use the aforementioned macros,
 190   which have the secondary benefit of having prewritten debug
 191   messages that use information about the current status of the
 192   objects involved (e.g., whether an iterator is singular or what
 193   sequence it is attached to) along with some static information
 194   (e.g., the names of the function parameters corresponding to the
 195   objects involved). When not using these macros, the debug mode uses
 196   either the debug-mode assertion
 197   macro <code class="code">_GLIBCXX_DEBUG_ASSERT</code> , its pedantic
 198   cousin <code class="code">_GLIBCXX_DEBUG_PEDASSERT</code>, or the assertion
 199   check macro that supports more advance formulation of error
 200   messages, <code class="code">_GLIBCXX_DEBUG_VERIFY</code>. These macros are
 201   documented more thoroughly in the debug mode source code.</p></div><div class="section" title="Release- and debug-mode coexistence"><div class="titlepage"><div><div><h4 class="title"><a name="debug_mode.design.methods.coexistence"></a>Release- and debug-mode coexistence</h4></div></div></div><p>The libstdc++ debug mode is the first debug mode we know of that
 202   is able to provide the "Per-use recompilation" (4) guarantee, that
 203   allows release-compiled and debug-compiled code to be linked and
 204   executed together without causing unpredictable behavior. This
 205   guarantee minimizes the recompilation that users are required to
 206   perform, shortening the detect-compile-debug bug hunting cycle
 207   and making the debug mode easier to incorporate into development
 208   environments by minimizing dependencies.</p><p>Achieving link- and run-time coexistence is not a trivial
 209   implementation task. To achieve this goal we required a small
 210   extension to the GNU C++ compiler (since incorporated into the C++11 language specification, described in the GCC Manual for the C++ language as
 211   <a class="link" href="http://gcc.gnu.org/onlinedocs/gcc/Namespace-Association.html#Namespace-Association" target="_top">namespace
 212   association</a>), and a complex organization of debug- and
 213   release-modes. The end result is that we have achieved per-use
 214   recompilation but have had to give up some checking of the
 215   <code class="code">std::basic_string</code> class template (namely, safe
 216   iterators).
 217 </p><div class="section" title="Compile-time coexistence of release- and debug-mode components"><div class="titlepage"><div><div><h5 class="title"><a name="methods.coexistence.compile"></a>Compile-time coexistence of release- and debug-mode components</h5></div></div></div><p>Both the release-mode components and the debug-mode
 218   components need to exist within a single translation unit so that
 219   the debug versions can wrap the release versions. However, only one
 220   of these components should be user-visible at any particular
 221   time with the standard name, e.g., <code class="code">std::list</code>. </p><p>In release mode, we define only the release-mode version of the
 222   component with its standard name and do not include the debugging
 223   component at all. The release mode version is defined within the
 224   namespace <code class="code">std</code>. Minus the namespace associations, this
 225   method leaves the behavior of release mode completely unchanged from
 226   its behavior prior to the introduction of the libstdc++ debug
 227   mode. Here's an example of what this ends up looking like, in
 228   C++.</p><pre class="programlisting">
 229 namespace std
 230 {
 231   template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
 232     class list
 233     {
 234       // ...
 235      };
 236 } // namespace std
 237 </pre><p>In debug mode we include the release-mode container (which is now
 238 defined in the namespace <code class="code">__cxx1998</code>) and also the
 239 debug-mode container. The debug-mode container is defined within the
 240 namespace <code class="code">__debug</code>, which is associated with namespace
 241 <code class="code">std</code> via the C++11 namespace association language feature.  This
 242 method allows the debug and release versions of the same component to
 243 coexist at compile-time and link-time without causing an unreasonable
 244 maintenance burden, while minimizing confusion. Again, this boils down
 245 to C++ code as follows:</p><pre class="programlisting">
 246 namespace std
 247 {
 248   namespace __cxx1998
 249   {
 250     template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
 251       class list
 252       {
 253         // ...
 254       };
 255   } // namespace __gnu_norm
 256
 257   namespace __debug
 258   {
 259     template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
 260       class list
 261       : public __cxx1998::list&lt;_Tp, _Alloc&gt;,
 262         public __gnu_debug::_Safe_sequence&lt;list&lt;_Tp, _Alloc&gt; &gt;
 263       {
 264         // ...
 265       };
 266   } // namespace __cxx1998
 267
 268   // namespace __debug __attribute__ ((strong));
 269   inline namespace __debug { }
 270 }
 271 </pre></div><div class="section" title="Link- and run-time coexistence of release- and debug-mode components"><div class="titlepage"><div><div><h5 class="title"><a name="methods.coexistence.link"></a>Link- and run-time coexistence of release- and
 272     debug-mode components</h5></div></div></div><p>Because each component has a distinct and separate release and
 273 debug implementation, there is no issue with link-time
 274 coexistence: the separate namespaces result in different mangled
 275 names, and thus unique linkage.</p><p>However, components that are defined and used within the C++
 276 standard library itself face additional constraints. For instance,
 277 some of the member functions of <code class="code"> std::moneypunct</code> return
 278 <code class="code">std::basic_string</code>. Normally, this is not a problem, but
 279 with a mixed mode standard library that could be using either
 280 debug-mode or release-mode <code class="code"> basic_string</code> objects, things
 281 get more complicated.  As the return value of a function is not
 282 encoded into the mangled name, there is no way to specify a
 283 release-mode or a debug-mode string. In practice, this results in
 284 runtime errors. A simplified example of this problem is as follows.
 285 </p><p> Take this translation unit, compiled in debug-mode: </p><pre class="programlisting">
 286 // -D_GLIBCXX_DEBUG
 287 #include &lt;string&gt;
 288
 289 std::string test02();
 290
 291 std::string test01()
 292 {
 293   return test02();
 294 }
 295
 296 int main()
 297 {
 298   test01();
 299   return 0;
 300 }
 301 </pre><p> ... and linked to this translation unit, compiled in release mode:</p><pre class="programlisting">
 302 #include &lt;string&gt;
 303
 304 std::string
 305 test02()
 306 {
 307   return std::string("toast");
 308 }
 309 </pre><p> For this reason we cannot easily provide safe iterators for
 310   the <code class="code">std::basic_string</code> class template, as it is present
 311   throughout the C++ standard library. For instance, locale facets
 312   define typedefs that include <code class="code">basic_string</code>: in a mixed
 313   debug/release program, should that typedef be based on the
 314   debug-mode <code class="code">basic_string</code> or the
 315   release-mode <code class="code">basic_string</code>? While the answer could be
 316   "both", and the difference hidden via renaming a la the
 317   debug/release containers, we must note two things about locale
 318   facets:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>They exist as shared state: one can create a facet in one
 319   translation unit and access the facet via the same type name in a
 320   different translation unit. This means that we cannot have two
 321   different versions of locale facets, because the types would not be
 322   the same across debug/release-mode translation unit barriers.</p></li><li class="listitem"><p>They have virtual functions returning strings: these functions
 323   mangle in the same way regardless of the mangling of their return
 324   types (see above), and their precise signatures can be relied upon
 325   by users because they may be overridden in derived classes.</p></li></ol></div><p>With the design of libstdc++ debug mode, we cannot effectively hide
 326   the differences between debug and release-mode strings from the
 327   user. Failure to hide the differences may result in unpredictable
 328   behavior, and for this reason we have opted to only
 329   perform <code class="code">basic_string</code> changes that do not require ABI
 330   changes. The effect on users is expected to be minimal, as there are
 331   simple alternatives (e.g., <code class="code">__gnu_debug::basic_string</code>),
 332   and the usability benefit we gain from the ability to mix debug- and
 333   release-compiled translation units is enormous.</p></div><div class="section" title="Alternatives for Coexistence"><div class="titlepage"><div><div><h5 class="title"><a name="methods.coexistence.alt"></a>Alternatives for Coexistence</h5></div></div></div><p>The coexistence scheme above was chosen over many alternatives,
 334   including language-only solutions and solutions that also required
 335   extensions to the C++ front end. The following is a partial list of
 336   solutions, with justifications for our rejection of each.</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><span class="emphasis"><em>Completely separate debug/release libraries</em></span>: This is by
 337   far the simplest implementation option, where we do not allow any
 338   coexistence of debug- and release-compiled translation units in a
 339   program. This solution has an extreme negative affect on usability,
 340   because it is quite likely that some libraries an application
 341   depends on cannot be recompiled easily. This would not meet
 342   our <span class="emphasis"><em>usability</em></span> or <span class="emphasis"><em>minimize recompilation</em></span> criteria
 343   well.</p></li><li class="listitem"><p><span class="emphasis"><em>Add a <code class="code">Debug</code> boolean template parameter</em></span>:
 344   Partial specialization could be used to select the debug
 345   implementation when <code class="code">Debug == true</code>, and the state
 346   of <code class="code">_GLIBCXX_DEBUG</code> could decide whether the
 347   default <code class="code">Debug</code> argument is <code class="code">true</code>
 348   or <code class="code">false</code>. This option would break conformance with the
 349   C++ standard in both debug <span class="emphasis"><em>and</em></span> release modes. This would
 350   not meet our <span class="emphasis"><em>correctness</em></span> criteria. </p></li><li class="listitem"><p><span class="emphasis"><em>Packaging a debug flag in the allocators</em></span>: We could
 351     reuse the <code class="code">Allocator</code> template parameter of containers
 352     by adding a sentinel wrapper <code class="code">debug&lt;&gt;</code> that
 353     signals the user's intention to use debugging, and pick up
 354     the <code class="code">debug&lt;&gt;</code> allocator wrapper in a partial
 355     specialization. However, this has two drawbacks: first, there is a
 356     conformance issue because the default allocator would not be the
 357     standard-specified <code class="code">std::allocator&lt;T&gt;</code>. Secondly
 358     (and more importantly), users that specify allocators instead of
 359     implicitly using the default allocator would not get debugging
 360     containers. Thus this solution fails the <span class="emphasis"><em>correctness</em></span>
 361     criteria.</p></li><li class="listitem"><p><span class="emphasis"><em>Define debug containers in another namespace, and employ
 362       a <code class="code">using</code> declaration (or directive)</em></span>: This is an
 363       enticing option, because it would eliminate the need for
 364       the <code class="code">link_name</code> extension by aliasing the
 365       templates. However, there is no true template aliasing mechanism
 366       in C++, because both <code class="code">using</code> directives and using
 367       declarations disallow specialization. This method fails
 368       the <span class="emphasis"><em>correctness</em></span> criteria.</p></li><li class="listitem"><p><span class="emphasis"><em> Use implementation-specific properties of anonymous
 369     namespaces. </em></span>
 370     See <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00004.html" target="_top"> this post
 371     </a>
 372     This method fails the <span class="emphasis"><em>correctness</em></span> criteria.</p></li><li class="listitem"><p><span class="emphasis"><em>Extension: allow reopening on namespaces</em></span>: This would
 373     allow the debug mode to effectively alias the
 374     namespace <code class="code">std</code> to an internal namespace, such
 375     as <code class="code">__gnu_std_debug</code>, so that it is completely
 376     separate from the release-mode <code class="code">std</code> namespace. While
 377     this will solve some renaming problems and ensure that
 378     debug- and release-compiled code cannot be mixed unsafely, it ensures that
 379     debug- and release-compiled code cannot be mixed at all. For
 380     instance, the program would have two <code class="code">std::cout</code>
 381     objects! This solution would fails the <span class="emphasis"><em>minimize
 382     recompilation</em></span> requirement, because we would only be able to
 383     support option (1) or (2).</p></li><li class="listitem"><p><span class="emphasis"><em>Extension: use link name</em></span>: This option involves
 384     complicated re-naming between debug-mode and release-mode
 385     components at compile time, and then a g++ extension called <span class="emphasis"><em>
 386     link name </em></span> to recover the original names at link time. There
 387     are two drawbacks to this approach. One, it's very verbose,
 388     relying on macro renaming at compile time and several levels of
 389     include ordering. Two, ODR issues remained with container member
 390     functions taking no arguments in mixed-mode settings resulting in
 391     equivalent link names, <code class="code"> vector::push_back() </code> being
 392     one example.
 393     See <a class="link" href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00177.html" target="_top">link
 394     name</a> </p></li></ul></div><p>Other options may exist for implementing the debug mode, many of
 395   which have probably been considered and others that may still be
 396   lurking. This list may be expanded over time to include other
 397   options that we could have implemented, but in all cases the full
 398   ramifications of the approach (as measured against the design goals
 399   for a libstdc++ debug mode) should be considered first. The DejaGNU
 400   testsuite includes some testcases that check for known problems with
 401   some solutions (e.g., the <code class="code">using</code> declaration solution
 402   that breaks user specialization), and additional testcases will be
 403   added as we are able to identify other typical problem cases. These
 404   test cases will serve as a benchmark by which we can compare debug
 405   mode implementations.</p></div></div></div><div class="section" title="Other Implementations"><div class="titlepage"><div><div><h3 class="title"><a name="debug_mode.design.other"></a>Other Implementations</h3></div></div></div><p>
 406     </p><p> There are several existing implementations of debug modes for C++
 407   standard library implementations, although none of them directly
 408   supports debugging for programs using libstdc++. The existing
 409   implementations include:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="link" href="http://www.mathcs.sjsu.edu/faculty/horstman/safestl.html" target="_top">SafeSTL</a>:
 410   SafeSTL was the original debugging version of the Standard Template
 411   Library (STL), implemented by Cay S. Horstmann on top of the
 412   Hewlett-Packard STL. Though it inspired much work in this area, it
 413   has not been kept up-to-date for use with modern compilers or C++
 414   standard library implementations.</p></li><li class="listitem"><p><a class="link" href="http://www.stlport.org/" target="_top">STLport</a>: STLport is a free
 415   implementation of the C++ standard library derived from the <a class="link" href="http://www.sgi.com/tech/stl/" target="_top">SGI implementation</a>, and
 416   ported to many other platforms. It includes a debug mode that uses a
 417   wrapper model (that in some ways inspired the libstdc++ debug mode
 418   design), although at the time of this writing the debug mode is
 419   somewhat incomplete and meets only the "Full user recompilation" (2)
 420   recompilation guarantee by requiring the user to link against a
 421   different library in debug mode vs. release mode.</p></li><li class="listitem"><p>Metrowerks CodeWarrior: The C++ standard library
 422   that ships with Metrowerks CodeWarrior includes a debug mode. It is
 423   a full debug-mode implementation (including debugging for
 424   CodeWarrior extensions) and is easy to use, although it meets only
 425   the "Full recompilation" (1) recompilation
 426   guarantee.</p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bk01pt03ch17s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="debug_mode.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="parallel_mode.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Using </td><td width="20%" align="center"><a accesskey="h" href="../index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 18. Parallel Mode</td></tr></table></div></body></html>