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