1 <chapter xmlns="http://docbook.org/ns/docbook" version="5.0"
2 xml:id="manual.ext.debug_mode" xreflabel="Debug Mode">
3 <?dbhtml filename="debug_mode.html"?>
5 <info><title>Debug Mode</title>
8 <keyword>library</keyword>
9 <keyword>debug</keyword>
15 <section xml:id="manual.ext.debug_mode.intro" xreflabel="Intro"><info><title>Intro</title></info>
18 By default, libstdc++ is built with efficiency in mind, and
19 therefore performs little or no error checking that is not
20 required by the C++ standard. This means that programs that
21 incorrectly use the C++ standard library will exhibit behavior
22 that is not portable and may not even be predictable, because they
23 tread into implementation-specific or undefined behavior. To
24 detect some of these errors before they can become problematic,
25 libstdc++ offers a debug mode that provides additional checking of
26 library facilities, and will report errors in the use of libstdc++
27 as soon as they can be detected by emitting a description of the
28 problem to standard error and aborting the program. This debug
29 mode is available with GCC 3.4.0 and later versions.
33 The libstdc++ debug mode performs checking for many areas of the
34 C++ standard, but the focus is on checking interactions among
35 standard iterators, containers, and algorithms, including:
39 <listitem><para><emphasis>Safe iterators</emphasis>: Iterators keep track of the
40 container whose elements they reference, so errors such as
41 incrementing a past-the-end iterator or dereferencing an iterator
42 that points to a container that has been destructed are diagnosed
43 immediately.</para></listitem>
45 <listitem><para><emphasis>Algorithm preconditions</emphasis>: Algorithms attempt to
46 validate their input parameters to detect errors as early as
47 possible. For instance, the <code>set_intersection</code>
48 algorithm requires that its iterator
49 parameters <code>first1</code> and <code>last1</code> form a valid
50 iterator range, and that the sequence
51 [<code>first1</code>, <code>last1</code>) is sorted according to
52 the same predicate that was passed
53 to <code>set_intersection</code>; the libstdc++ debug mode will
54 detect an error if the sequence is not sorted or was sorted by a
55 different predicate.</para></listitem>
60 <section xml:id="manual.ext.debug_mode.semantics" xreflabel="Semantics"><info><title>Semantics</title></info>
61 <?dbhtml filename="debug_mode_semantics.html"?>
66 <para>A program that uses the C++ standard library correctly
67 will maintain the same semantics under debug mode as it had with
68 the normal (release) library. All functional and exception-handling
69 guarantees made by the normal library also hold for the debug mode
70 library, with one exception: performance guarantees made by the
71 normal library may not hold in the debug mode library. For
72 instance, erasing an element in a <code>std::list</code> is a
73 constant-time operation in normal library, but in debug mode it is
74 linear in the number of iterators that reference that particular
75 list. So while your (correct) program won't change its results, it
76 is likely to execute more slowly.</para>
78 <para>libstdc++ includes many extensions to the C++ standard library. In
79 some cases the extensions are obvious, such as the hashed
80 associative containers, whereas other extensions give predictable
81 results to behavior that would otherwise be undefined, such as
82 throwing an exception when a <code>std::basic_string</code> is
83 constructed from a NULL character pointer. This latter category also
84 includes implementation-defined and unspecified semantics, such as
85 the growth rate of a vector. Use of these extensions is not
86 considered incorrect, so code that relies on them will not be
87 rejected by debug mode. However, use of these extensions may affect
88 the portability of code to other implementations of the C++ standard
89 library, and is therefore somewhat hazardous. For this reason, the
90 libstdc++ debug mode offers a "pedantic" mode (similar to
91 GCC's <code>-pedantic</code> compiler flag) that attempts to emulate
92 the semantics guaranteed by the C++ standard. For
93 instance, constructing a <code>std::basic_string</code> with a NULL
94 character pointer would result in an exception under normal mode or
95 non-pedantic debug mode (this is a libstdc++ extension), whereas
96 under pedantic debug mode libstdc++ would signal an error. To enable
97 the pedantic debug mode, compile your program with
98 both <code>-D_GLIBCXX_DEBUG</code>
99 and <code>-D_GLIBCXX_DEBUG_PEDANTIC</code> .
100 (N.B. In GCC 3.4.x and 4.0.0, due to a bug,
101 <code>-D_GLIBXX_DEBUG_PEDANTIC</code> was also needed. The problem has
102 been fixed in GCC 4.0.1 and later versions.) </para>
104 <para>The following library components provide extra debugging
105 capabilities in debug mode:</para>
107 <listitem><para><code>std::basic_string</code> (no safe iterators and see note below)</para></listitem>
108 <listitem><para><code>std::bitset</code></para></listitem>
109 <listitem><para><code>std::deque</code></para></listitem>
110 <listitem><para><code>std::list</code></para></listitem>
111 <listitem><para><code>std::map</code></para></listitem>
112 <listitem><para><code>std::multimap</code></para></listitem>
113 <listitem><para><code>std::multiset</code></para></listitem>
114 <listitem><para><code>std::set</code></para></listitem>
115 <listitem><para><code>std::vector</code></para></listitem>
116 <listitem><para><code>std::unordered_map</code></para></listitem>
117 <listitem><para><code>std::unordered_multimap</code></para></listitem>
118 <listitem><para><code>std::unordered_set</code></para></listitem>
119 <listitem><para><code>std::unordered_multiset</code></para></listitem>
122 <para>N.B. although there are precondition checks for some string operations,
123 e.g. <code>operator[]</code>,
124 they will not always be run when using the <code>char</code> and
125 <code>wchar_t</code> specialisations (<code>std::string</code> and
126 <code>std::wstring</code>). This is because libstdc++ uses GCC's
127 <code>extern template</code> extension to provide explicit instantiations
128 of <code>std::string</code> and <code>std::wstring</code>, and those
129 explicit instantiations don't include the debug-mode checks. If the
130 containing functions are inlined then the checks will run, so compiling
131 with <code>-O1</code> might be enough to enable them. Alternatively
132 <code>-D_GLIBCXX_EXTERN_TEMPLATE=0</code> will suppress the declarations
133 of the explicit instantiations and cause the functions to be instantiated
134 with the debug-mode checks included, but this is unsupported and not
135 guaranteed to work. For full debug-mode support you can use the
136 <code>__gnu_debug::basic_string</code> debugging container directly,
137 which always works correctly.
142 <section xml:id="manual.ext.debug_mode.using" xreflabel="Using"><info><title>Using</title></info>
143 <?dbhtml filename="debug_mode_using.html"?>
147 <section xml:id="debug_mode.using.mode" xreflabel="Using Mode"><info><title>Using the Debug Mode</title></info>
150 <para>To use the libstdc++ debug mode, compile your application with the
151 compiler flag <code>-D_GLIBCXX_DEBUG</code>. Note that this flag
152 changes the sizes and behavior of standard class templates such
153 as <code>std::vector</code>, and therefore you can only link code
154 compiled with debug mode and code compiled without debug mode if no
155 instantiation of a container is passed between the two translation
158 <para>By default, error messages are formatted to fit on lines of about
159 78 characters. The environment variable
160 <code>GLIBCXX_DEBUG_MESSAGE_LENGTH</code> can be used to request a
161 different length.</para>
165 <section xml:id="debug_mode.using.specific" xreflabel="Using Specific"><info><title>Using a Specific Debug Container</title></info>
167 <para>When it is not feasible to recompile your entire application, or
168 only specific containers need checking, debugging containers are
169 available as GNU extensions. These debugging containers are
170 functionally equivalent to the standard drop-in containers used in
171 debug mode, but they are available in a separate namespace as GNU
172 extensions and may be used in programs compiled with either release
173 mode or with debug mode. The
174 following table provides the names and headers of the debugging
178 <table frame="all" xml:id="table.debug_mode_containers">
179 <title>Debugging Containers</title>
181 <tgroup cols="4" align="left" colsep="1" rowsep="1">
182 <colspec colname="c1"/>
183 <colspec colname="c2"/>
184 <colspec colname="c3"/>
185 <colspec colname="c4"/>
189 <entry>Container</entry>
190 <entry>Header</entry>
191 <entry>Debug container</entry>
192 <entry>Debug header</entry>
197 <entry><classname>std::bitset</classname></entry>
198 <entry><filename class="headerfile">bitset</filename></entry>
199 <entry><classname>__gnu_debug::bitset</classname></entry>
200 <entry><filename class="headerfile"><debug/bitset></filename></entry>
203 <entry><classname>std::deque</classname></entry>
204 <entry><filename class="headerfile">deque</filename></entry>
205 <entry><classname>__gnu_debug::deque</classname></entry>
206 <entry><filename class="headerfile"><debug/deque></filename></entry>
209 <entry><classname>std::list</classname></entry>
210 <entry><filename class="headerfile">list</filename></entry>
211 <entry><classname>__gnu_debug::list</classname></entry>
212 <entry><filename class="headerfile"><debug/list></filename></entry>
215 <entry><classname>std::map</classname></entry>
216 <entry><filename class="headerfile">map</filename></entry>
217 <entry><classname>__gnu_debug::map</classname></entry>
218 <entry><filename class="headerfile"><debug/map></filename></entry>
221 <entry><classname>std::multimap</classname></entry>
222 <entry><filename class="headerfile">map</filename></entry>
223 <entry><classname>__gnu_debug::multimap</classname></entry>
224 <entry><filename class="headerfile"><debug/map></filename></entry>
227 <entry><classname>std::multiset</classname></entry>
228 <entry><filename class="headerfile">set</filename></entry>
229 <entry><classname>__gnu_debug::multiset</classname></entry>
230 <entry><filename class="headerfile"><debug/set></filename></entry>
233 <entry><classname>std::set</classname></entry>
234 <entry><filename class="headerfile">set</filename></entry>
235 <entry><classname>__gnu_debug::set</classname></entry>
236 <entry><filename class="headerfile"><debug/set></filename></entry>
239 <entry><classname>std::string</classname></entry>
240 <entry><filename class="headerfile">string</filename></entry>
241 <entry><classname>__gnu_debug::string</classname></entry>
242 <entry><filename class="headerfile"><debug/string></filename></entry>
245 <entry><classname>std::wstring</classname></entry>
246 <entry><filename class="headerfile">string</filename></entry>
247 <entry><classname>__gnu_debug::wstring</classname></entry>
248 <entry><filename class="headerfile"><debug/string></filename></entry>
251 <entry><classname>std::basic_string</classname></entry>
252 <entry><filename class="headerfile">string</filename></entry>
253 <entry><classname>__gnu_debug::basic_string</classname></entry>
254 <entry><filename class="headerfile"><debug/string></filename></entry>
257 <entry><classname>std::vector</classname></entry>
258 <entry><filename class="headerfile">vector</filename></entry>
259 <entry><classname>__gnu_debug::vector</classname></entry>
260 <entry><filename class="headerfile"><debug/vector></filename></entry>
266 <para>In addition, when compiling in C++11 mode, these additional
267 containers have additional debug capability.
270 <table frame="all" xml:id="table.debug_mode_containers_cxx11">
271 <title>Debugging Containers C++11</title>
273 <tgroup cols="4" align="left" colsep="1" rowsep="1">
274 <colspec colname="c1"/>
275 <colspec colname="c2"/>
276 <colspec colname="c3"/>
277 <colspec colname="c4"/>
281 <entry>Container</entry>
282 <entry>Header</entry>
283 <entry>Debug container</entry>
284 <entry>Debug header</entry>
289 <entry><classname>std::array</classname></entry>
290 <entry><filename class="headerfile">array</filename></entry>
291 <entry><classname>__gnu_debug::array</classname></entry>
292 <entry><filename class="headerfile"><debug/array></filename></entry>
295 <entry><classname>std::forward_list</classname></entry>
296 <entry><filename class="headerfile">forward_list</filename></entry>
297 <entry><classname>__gnu_debug::forward_list</classname></entry>
298 <entry><filename class="headerfile"><debug/forward_list></filename></entry>
301 <entry><classname>std::unordered_map</classname></entry>
302 <entry><filename class="headerfile">unordered_map</filename></entry>
303 <entry><classname>__gnu_debug::unordered_map</classname></entry>
304 <entry><filename class="headerfile"><debug/unordered_map></filename></entry>
307 <entry><classname>std::unordered_multimap</classname></entry>
308 <entry><filename class="headerfile">unordered_map</filename></entry>
309 <entry><classname>__gnu_debug::unordered_multimap</classname></entry>
310 <entry><filename class="headerfile"><debug/unordered_map></filename></entry>
313 <entry><classname>std::unordered_set</classname></entry>
314 <entry><filename class="headerfile">unordered_set</filename></entry>
315 <entry><classname>__gnu_debug::unordered_set</classname></entry>
316 <entry><filename class="headerfile"><debug/unordered_set></filename></entry>
319 <entry><classname>std::unordered_multiset</classname></entry>
320 <entry><filename class="headerfile">unordered_set</filename></entry>
321 <entry><classname>__gnu_debug::unordered_multiset</classname></entry>
322 <entry><filename class="headerfile"><debug/unordered_set></filename></entry>
330 <section xml:id="manual.ext.debug_mode.design" xreflabel="Design"><info><title>Design</title></info>
331 <?dbhtml filename="debug_mode_design.html"?>
335 <section xml:id="debug_mode.design.goals" xreflabel="Goals"><info><title>Goals</title></info>
339 <para> The libstdc++ debug mode replaces unsafe (but efficient) standard
340 containers and iterators with semantically equivalent safe standard
341 containers and iterators to aid in debugging user programs. The
342 following goals directed the design of the libstdc++ debug mode:</para>
346 <listitem><para><emphasis>Correctness</emphasis>: the libstdc++ debug mode must not change
347 the semantics of the standard library for all cases specified in
348 the ANSI/ISO C++ standard. The essence of this constraint is that
349 any valid C++ program should behave in the same manner regardless
350 of whether it is compiled with debug mode or release mode. In
351 particular, entities that are defined in namespace std in release
352 mode should remain defined in namespace std in debug mode, so that
353 legal specializations of namespace std entities will remain
354 valid. A program that is not valid C++ (e.g., invokes undefined
355 behavior) is not required to behave similarly, although the debug
356 mode will abort with a diagnostic when it detects undefined
357 behavior.</para></listitem>
359 <listitem><para><emphasis>Performance</emphasis>: the additional of the libstdc++ debug mode
360 must not affect the performance of the library when it is compiled
361 in release mode. Performance of the libstdc++ debug mode is
362 secondary (and, in fact, will be worse than the release
363 mode).</para></listitem>
365 <listitem><para><emphasis>Usability</emphasis>: the libstdc++ debug mode should be easy to
366 use. It should be easily incorporated into the user's development
367 environment (e.g., by requiring only a single new compiler switch)
368 and should produce reasonable diagnostics when it detects a
369 problem with the user program. Usability also involves detection
370 of errors when using the debug mode incorrectly, e.g., by linking
371 a release-compiled object against a debug-compiled object if in
372 fact the resulting program will not run correctly.</para></listitem>
374 <listitem><para><emphasis>Minimize recompilation</emphasis>: While it is expected that
375 users recompile at least part of their program to use debug
376 mode, the amount of recompilation affects the
377 detect-compile-debug turnaround time. This indirectly affects the
378 usefulness of the debug mode, because debugging some applications
379 may require rebuilding a large amount of code, which may not be
380 feasible when the suspect code may be very localized. There are
381 several levels of conformance to this requirement, each with its
382 own usability and implementation characteristics. In general, the
383 higher-numbered conformance levels are more usable (i.e., require
384 less recompilation) but are more complicated to implement than
385 the lower-numbered conformance levels.
386 <orderedlist inheritnum="ignore" continuation="restarts">
387 <listitem><para><emphasis>Full recompilation</emphasis>: The user must recompile his or
388 her entire application and all C++ libraries it depends on,
389 including the C++ standard library that ships with the
390 compiler. This must be done even if only a small part of the
391 program can use debugging features.</para></listitem>
393 <listitem><para><emphasis>Full user recompilation</emphasis>: The user must recompile
394 his or her entire application and all C++ libraries it depends
395 on, but not the C++ standard library itself. This must be done
396 even if only a small part of the program can use debugging
397 features. This can be achieved given a full recompilation
398 system by compiling two versions of the standard library when
399 the compiler is installed and linking against the appropriate
400 one, e.g., a multilibs approach.</para></listitem>
402 <listitem><para><emphasis>Partial recompilation</emphasis>: The user must recompile the
403 parts of his or her application and the C++ libraries it
404 depends on that will use the debugging facilities
405 directly. This means that any code that uses the debuggable
406 standard containers would need to be recompiled, but code
407 that does not use them (but may, for instance, use IOStreams)
408 would not have to be recompiled.</para></listitem>
410 <listitem><para><emphasis>Per-use recompilation</emphasis>: The user must recompile the
411 parts of his or her application and the C++ libraries it
412 depends on where debugging should occur, and any other code
413 that interacts with those containers. This means that a set of
414 translation units that accesses a particular standard
415 container instance may either be compiled in release mode (no
416 checking) or debug mode (full checking), but must all be
417 compiled in the same way; a translation unit that does not see
418 that standard container instance need not be recompiled. This
419 also means that a translation unit <emphasis>A</emphasis> that contains a
420 particular instantiation
421 (say, <code>std::vector<int></code>) compiled in release
422 mode can be linked against a translation unit <emphasis>B</emphasis> that
423 contains the same instantiation compiled in debug mode (a
424 feature not present with partial recompilation). While this
425 behavior is technically a violation of the One Definition
426 Rule, this ability tends to be very important in
427 practice. The libstdc++ debug mode supports this level of
428 recompilation. </para></listitem>
430 <listitem><para><emphasis>Per-unit recompilation</emphasis>: The user must only
431 recompile the translation units where checking should occur,
432 regardless of where debuggable standard containers are
433 used. This has also been dubbed "<code>-g</code> mode",
434 because the <code>-g</code> compiler switch works in this way,
435 emitting debugging information at a per--translation-unit
436 granularity. We believe that this level of recompilation is in
437 fact not possible if we intend to supply safe iterators, leave
438 the program semantics unchanged, and not regress in
439 performance under release mode because we cannot associate
440 extra information with an iterator (to form a safe iterator)
441 without either reserving that space in release mode
442 (performance regression) or allocating extra memory associated
443 with each iterator with <code>new</code> (changes the program
444 semantics).</para></listitem>
450 <section xml:id="debug_mode.design.methods" xreflabel="Methods"><info><title>Methods</title></info>
454 <para>This section provides an overall view of the design of the
455 libstdc++ debug mode and details the relationship between design
456 decisions and the stated design goals.</para>
458 <section xml:id="debug_mode.design.methods.wrappers" xreflabel="Method Wrapper"><info><title>The Wrapper Model</title></info>
460 <para>The libstdc++ debug mode uses a wrapper model where the
461 debugging versions of library components (e.g., iterators and
462 containers) form a layer on top of the release versions of the
463 library components. The debugging components first verify that the
464 operation is correct (aborting with a diagnostic if an error is
465 found) and will then forward to the underlying release-mode
466 container that will perform the actual work. This design decision
467 ensures that we cannot regress release-mode performance (because the
468 release-mode containers are left untouched) and partially
469 enables <link linkend="methods.coexistence.link">mixing debug and
470 release code</link> at link time, although that will not be
471 discussed at this time.</para>
473 <para>Two types of wrappers are used in the implementation of the debug
474 mode: container wrappers and iterator wrappers. The two types of
475 wrappers interact to maintain relationships between iterators and
476 their associated containers, which are necessary to detect certain
477 types of standard library usage errors such as dereferencing
478 past-the-end iterators or inserting into a container using an
479 iterator from a different container.</para>
481 <section xml:id="debug_mode.design.methods.safe_iter" xreflabel="Method Safe Iter"><info><title>Safe Iterators</title></info>
483 <para>Iterator wrappers provide a debugging layer over any iterator that
484 is attached to a particular container, and will manage the
485 information detailing the iterator's state (singular,
486 dereferenceable, etc.) and tracking the container to which the
487 iterator is attached. Because iterators have a well-defined, common
488 interface the iterator wrapper is implemented with the iterator
489 adaptor class template <code>__gnu_debug::_Safe_iterator</code>,
490 which takes two template parameters:</para>
493 <listitem><para><code>Iterator</code>: The underlying iterator type, which must
494 be either the <code>iterator</code> or <code>const_iterator</code>
495 typedef from the sequence type this iterator can reference.</para></listitem>
497 <listitem><para><code>Sequence</code>: The type of sequence that this iterator
498 references. This sequence must be a safe sequence (discussed below)
499 whose <code>iterator</code> or <code>const_iterator</code> typedef
500 is the type of the safe iterator.</para></listitem>
504 <section xml:id="debug_mode.design.methods.safe_seq" xreflabel="Method Safe Seq"><info><title>Safe Sequences (Containers)</title></info>
507 <para>Container wrappers provide a debugging layer over a particular
508 container type. Because containers vary greatly in the member
509 functions they support and the semantics of those member functions
510 (especially in the area of iterator invalidation), container
511 wrappers are tailored to the container they reference, e.g., the
512 debugging version of <code>std::list</code> duplicates the entire
513 interface of <code>std::list</code>, adding additional semantic
514 checks and then forwarding operations to the
515 real <code>std::list</code> (a public base class of the debugging
516 version) as appropriate. However, all safe containers inherit from
517 the class template <code>__gnu_debug::_Safe_sequence</code>,
518 instantiated with the type of the safe container itself (an instance
519 of the curiously recurring template pattern).</para>
521 <para>The iterators of a container wrapper will be
522 <link linkend="debug_mode.design.methods.safe_iter">safe
523 iterators</link> that reference sequences of this type and wrap the
524 iterators provided by the release-mode base class. The debugging
525 container will use only the safe iterators within its own interface
526 (therefore requiring the user to use safe iterators, although this
527 does not change correct user code) and will communicate with the
528 release-mode base class with only the underlying, unsafe,
529 release-mode iterators that the base class exports.</para>
531 <para> The debugging version of <code>std::list</code> will have the
532 following basic structure:</para>
535 template<typename _Tp, typename _Allocator = allocator<_Tp>
537 public release-list<_Tp, _Allocator>,
538 public __gnu_debug::_Safe_sequence<debug-list<_Tp, _Allocator> >
540 typedef release-list<_Tp, _Allocator> _Base;
541 typedef debug-list<_Tp, _Allocator> _Self;
544 typedef __gnu_debug::_Safe_iterator<typename _Base::iterator, _Self> iterator;
545 typedef __gnu_debug::_Safe_iterator<typename _Base::const_iterator, _Self> const_iterator;
547 // duplicate std::list interface with debugging semantics
553 <section xml:id="debug_mode.design.methods.precond" xreflabel="Precondition check"><info><title>Precondition Checking</title></info>
555 <para>The debug mode operates primarily by checking the preconditions of
556 all standard library operations that it supports. Preconditions that
557 are always checked (regardless of whether or not we are in debug
558 mode) are checked via the <code>__check_xxx</code> macros defined
559 and documented in the source
560 file <code>include/debug/debug.h</code>. Preconditions that may or
561 may not be checked, depending on the debug-mode
562 macro <code>_GLIBCXX_DEBUG</code>, are checked via
563 the <code>__requires_xxx</code> macros defined and documented in the
564 same source file. Preconditions are validated using any additional
565 information available at run-time, e.g., the containers that are
566 associated with a particular iterator, the position of the iterator
567 within those containers, the distance between two iterators that may
568 form a valid range, etc. In the absence of suitable information,
569 e.g., an input iterator that is not a safe iterator, these
570 precondition checks will silently succeed.</para>
572 <para>The majority of precondition checks use the aforementioned macros,
573 which have the secondary benefit of having prewritten debug
574 messages that use information about the current status of the
575 objects involved (e.g., whether an iterator is singular or what
576 sequence it is attached to) along with some static information
577 (e.g., the names of the function parameters corresponding to the
578 objects involved). When not using these macros, the debug mode uses
579 either the debug-mode assertion
580 macro <code>_GLIBCXX_DEBUG_ASSERT</code> , its pedantic
581 cousin <code>_GLIBCXX_DEBUG_PEDASSERT</code>, or the assertion
582 check macro that supports more advance formulation of error
583 messages, <code>_GLIBCXX_DEBUG_VERIFY</code>. These macros are
584 documented more thoroughly in the debug mode source code.</para>
587 <section xml:id="debug_mode.design.methods.coexistence" xreflabel="Coexistence"><info><title>Release- and debug-mode coexistence</title></info>
589 <para>The libstdc++ debug mode is the first debug mode we know of that
590 is able to provide the "Per-use recompilation" (4) guarantee, that
591 allows release-compiled and debug-compiled code to be linked and
592 executed together without causing unpredictable behavior. This
593 guarantee minimizes the recompilation that users are required to
594 perform, shortening the detect-compile-debug bug hunting cycle
595 and making the debug mode easier to incorporate into development
596 environments by minimizing dependencies.</para>
598 <para>Achieving link- and run-time coexistence is not a trivial
599 implementation task. To achieve this goal we use inline namespaces and
600 a complex organization of debug- and release-modes. The end result is
601 that we have achieved per-use recompilation but have had to give up
602 some checking of the <code>std::basic_string</code> class template
603 (namely, safe iterators).</para>
605 <section xml:id="methods.coexistence.compile" xreflabel="Compile"><info><title>Compile-time coexistence of release- and debug-mode components</title></info>
608 <para>Both the release-mode components and the debug-mode
609 components need to exist within a single translation unit so that
610 the debug versions can wrap the release versions. However, only one
611 of these components should be user-visible at any particular
612 time with the standard name, e.g., <code>std::list</code>. </para>
614 <para>In release mode, we define only the release-mode version of the
615 component with its standard name and do not include the debugging
616 component at all. The release mode version is defined within the
617 namespace <code>std</code>. Minus the namespace associations, this
618 method leaves the behavior of release mode completely unchanged from
619 its behavior prior to the introduction of the libstdc++ debug
620 mode. Here's an example of what this ends up looking like, in
626 template<typename _Tp, typename _Alloc = allocator<_Tp> >
634 <para>In debug mode we include the release-mode container (which is now
635 defined in the namespace <code>__cxx1998</code>) and also the
636 debug-mode container. The debug-mode container is defined within the
637 namespace <code>__debug</code>, which is associated with namespace
638 <code>std</code> via the C++11 namespace association language feature. This
639 method allows the debug and release versions of the same component to
640 coexist at compile-time and link-time without causing an unreasonable
641 maintenance burden, while minimizing confusion. Again, this boils down
642 to C++ code as follows:</para>
649 template<typename _Tp, typename _Alloc = allocator<_Tp> >
654 } // namespace __gnu_norm
658 template<typename _Tp, typename _Alloc = allocator<_Tp> >
660 : public __cxx1998::list<_Tp, _Alloc>,
661 public __gnu_debug::_Safe_sequence<list<_Tp, _Alloc> >
665 } // namespace __cxx1998
667 inline namespace __debug { }
672 <section xml:id="methods.coexistence.link" xreflabel="Link"><info><title>Link- and run-time coexistence of release- and
673 debug-mode components</title></info>
676 <para>Because each component has a distinct and separate release and
677 debug implementation, there is no issue with link-time
678 coexistence: the separate namespaces result in different mangled
679 names, and thus unique linkage.</para>
681 <para>However, components that are defined and used within the C++
682 standard library itself face additional constraints. For instance,
683 some of the member functions of <code> std::moneypunct</code> return
684 <code>std::basic_string</code>. Normally, this is not a problem, but
685 with a mixed mode standard library that could be using either
686 debug-mode or release-mode <code> basic_string</code> objects, things
687 get more complicated. As the return value of a function is not
688 encoded into the mangled name, there is no way to specify a
689 release-mode or a debug-mode string. In practice, this results in
690 runtime errors. A simplified example of this problem is as follows.
693 <para> Take this translation unit, compiled in debug-mode: </para>
696 #include <string>
698 std::string test02();
712 <para> ... and linked to this translation unit, compiled in release mode:</para>
715 #include <string>
720 return std::string("toast");
724 <para> For this reason we cannot easily provide safe iterators for
725 the <code>std::basic_string</code> class template, as it is present
726 throughout the C++ standard library. For instance, locale facets
727 define typedefs that include <code>basic_string</code>: in a mixed
728 debug/release program, should that typedef be based on the
729 debug-mode <code>basic_string</code> or the
730 release-mode <code>basic_string</code>? While the answer could be
731 "both", and the difference hidden via renaming a la the
732 debug/release containers, we must note two things about locale
735 <orderedlist inheritnum="ignore" continuation="restarts">
736 <listitem><para>They exist as shared state: one can create a facet in one
737 translation unit and access the facet via the same type name in a
738 different translation unit. This means that we cannot have two
739 different versions of locale facets, because the types would not be
740 the same across debug/release-mode translation unit barriers.</para></listitem>
742 <listitem><para>They have virtual functions returning strings: these functions
743 mangle in the same way regardless of the mangling of their return
744 types (see above), and their precise signatures can be relied upon
745 by users because they may be overridden in derived classes.</para></listitem>
748 <para>With the design of libstdc++ debug mode, we cannot effectively hide
749 the differences between debug and release-mode strings from the
750 user. Failure to hide the differences may result in unpredictable
751 behavior, and for this reason we have opted to only
752 perform <code>basic_string</code> changes that do not require ABI
753 changes. The effect on users is expected to be minimal, as there are
754 simple alternatives (e.g., <code>__gnu_debug::basic_string</code>),
755 and the usability benefit we gain from the ability to mix debug- and
756 release-compiled translation units is enormous.</para>
759 <section xml:id="methods.coexistence.alt" xreflabel="Alternatives"><info><title>Alternatives for Coexistence</title></info>
762 <para>The coexistence scheme above was chosen over many alternatives,
763 including language-only solutions and solutions that also required
764 extensions to the C++ front end. The following is a partial list of
765 solutions, with justifications for our rejection of each.</para>
768 <listitem><para><emphasis>Completely separate debug/release libraries</emphasis>: This is by
769 far the simplest implementation option, where we do not allow any
770 coexistence of debug- and release-compiled translation units in a
771 program. This solution has an extreme negative affect on usability,
772 because it is quite likely that some libraries an application
773 depends on cannot be recompiled easily. This would not meet
774 our <emphasis>usability</emphasis> or <emphasis>minimize recompilation</emphasis> criteria
775 well.</para></listitem>
777 <listitem><para><emphasis>Add a <code>Debug</code> boolean template parameter</emphasis>:
778 Partial specialization could be used to select the debug
779 implementation when <code>Debug == true</code>, and the state
780 of <code>_GLIBCXX_DEBUG</code> could decide whether the
781 default <code>Debug</code> argument is <code>true</code>
782 or <code>false</code>. This option would break conformance with the
783 C++ standard in both debug <emphasis>and</emphasis> release modes. This would
784 not meet our <emphasis>correctness</emphasis> criteria. </para></listitem>
786 <listitem><para><emphasis>Packaging a debug flag in the allocators</emphasis>: We could
787 reuse the <code>Allocator</code> template parameter of containers
788 by adding a sentinel wrapper <code>debug<></code> that
789 signals the user's intention to use debugging, and pick up
790 the <code>debug<></code> allocator wrapper in a partial
791 specialization. However, this has two drawbacks: first, there is a
792 conformance issue because the default allocator would not be the
793 standard-specified <code>std::allocator<T></code>. Secondly
794 (and more importantly), users that specify allocators instead of
795 implicitly using the default allocator would not get debugging
796 containers. Thus this solution fails the <emphasis>correctness</emphasis>
797 criteria.</para></listitem>
799 <listitem><para><emphasis>Define debug containers in another namespace, and employ
800 a <code>using</code> declaration (or directive)</emphasis>: This is an
801 enticing option, because it would eliminate the need for
802 the <code>link_name</code> extension by aliasing the
803 templates. However, there is no true template aliasing mechanism
804 in C++, because both <code>using</code> directives and using
805 declarations disallow specialization. This method fails
806 the <emphasis>correctness</emphasis> criteria.</para></listitem>
808 <listitem><para><emphasis> Use implementation-specific properties of anonymous
809 namespaces. </emphasis>
810 See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00004.html">this post</link>.
811 This method fails the <emphasis>correctness</emphasis> criteria.</para></listitem>
813 <listitem><para><emphasis>Extension: allow reopening on namespaces</emphasis>: This would
814 allow the debug mode to effectively alias the
815 namespace <code>std</code> to an internal namespace, such
816 as <code>__gnu_std_debug</code>, so that it is completely
817 separate from the release-mode <code>std</code> namespace. While
818 this will solve some renaming problems and ensure that
819 debug- and release-compiled code cannot be mixed unsafely, it ensures that
820 debug- and release-compiled code cannot be mixed at all. For
821 instance, the program would have two <code>std::cout</code>
822 objects! This solution would fails the <emphasis>minimize
823 recompilation</emphasis> requirement, because we would only be able to
824 support option (1) or (2).</para></listitem>
826 <listitem><para><emphasis>Extension: use link name</emphasis>: This option
827 involves complicated re-naming between debug-mode and release-mode
828 components at compile time, and then a g++ extension called <emphasis>
829 link name </emphasis> to recover the original names at link time. There
830 are two drawbacks to this approach. One, it's very verbose,
831 relying on macro renaming at compile time and several levels of
832 include ordering. Two, ODR issues remained with container member
833 functions taking no arguments in mixed-mode settings resulting in
834 equivalent link names, <code> vector::push_back() </code> being
836 See <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/ml/libstdc++/2003-08/msg00177.html">proof-of-concept using link
837 name</link>. </para></listitem>
840 <para>Other options may exist for implementing the debug mode, many of
841 which have probably been considered and others that may still be
842 lurking. This list may be expanded over time to include other
843 options that we could have implemented, but in all cases the full
844 ramifications of the approach (as measured against the design goals
845 for a libstdc++ debug mode) should be considered first. The DejaGNU
846 testsuite includes some testcases that check for known problems with
847 some solutions (e.g., the <code>using</code> declaration solution
848 that breaks user specialization), and additional testcases will be
849 added as we are able to identify other typical problem cases. These
850 test cases will serve as a benchmark by which we can compare debug
851 mode implementations.</para>
856 <section xml:id="debug_mode.design.other" xreflabel="Other"><info><title>Other Implementations</title></info>
860 <para> There are several existing implementations of debug modes for C++
861 standard library implementations, although none of them directly
862 supports debugging for programs using libstdc++. The existing
863 implementations include:</para>
865 <listitem><para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.cs.sjsu.edu/faculty/horstman/safestl.html">SafeSTL</link>:
866 SafeSTL was the original debugging version of the Standard Template
867 Library (STL), implemented by Cay S. Horstmann on top of the
868 Hewlett-Packard STL. Though it inspired much work in this area, it
869 has not been kept up-to-date for use with modern compilers or C++
870 standard library implementations.</para></listitem>
872 <listitem><para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stlport.org/">STLport</link>: STLport is a free
873 implementation of the C++ standard library derived from the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/">SGI implementation</link>, and
874 ported to many other platforms. It includes a debug mode that uses a
875 wrapper model (that in some ways inspired the libstdc++ debug mode
876 design), although at the time of this writing the debug mode is
877 somewhat incomplete and meets only the "Full user recompilation" (2)
878 recompilation guarantee by requiring the user to link against a
879 different library in debug mode vs. release mode.</para></listitem>
881 <listitem><para>Metrowerks CodeWarrior: The C++ standard library
882 that ships with Metrowerks CodeWarrior includes a debug mode. It is
883 a full debug-mode implementation (including debugging for
884 CodeWarrior extensions) and is easy to use, although it meets only
885 the "Full recompilation" (1) recompilation
886 guarantee.</para></listitem>