xref: /netbsd-src/external/gpl3/gcc/dist/libstdc++-v3/doc/xml/manual/debug_mode.xml (revision b1e838363e3c6fc78a55519254d99869742dd33c)
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"?>
4
5<info><title>Debug Mode</title>
6  <keywordset>
7    <keyword>C++</keyword>
8    <keyword>library</keyword>
9    <keyword>debug</keyword>
10  </keywordset>
11</info>
12
13
14
15<section xml:id="manual.ext.debug_mode.intro" xreflabel="Intro"><info><title>Intro</title></info>
16
17  <para>
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.
30  </para>
31
32  <para>
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:
36  </para>
37
38  <itemizedlist>
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>
44
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>
56  </itemizedlist>
57
58</section>
59
60<section xml:id="manual.ext.debug_mode.semantics" xreflabel="Semantics"><info><title>Semantics</title></info>
61  <?dbhtml filename="debug_mode_semantics.html"?>
62
63  <para>
64  </para>
65
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>
77
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>
103
104<para>The following library components provide extra debugging
105  capabilities in debug mode:</para>
106<itemizedlist>
107  <listitem><para><code>std::array</code> (no safe iterators)</para></listitem>
108  <listitem><para><code>std::basic_string</code> (no safe iterators and see note below)</para></listitem>
109  <listitem><para><code>std::bitset</code></para></listitem>
110  <listitem><para><code>std::deque</code></para></listitem>
111  <listitem><para><code>std::list</code></para></listitem>
112  <listitem><para><code>std::map</code></para></listitem>
113  <listitem><para><code>std::multimap</code></para></listitem>
114  <listitem><para><code>std::multiset</code></para></listitem>
115  <listitem><para><code>std::set</code></para></listitem>
116  <listitem><para><code>std::vector</code></para></listitem>
117  <listitem><para><code>std::unordered_map</code></para></listitem>
118  <listitem><para><code>std::unordered_multimap</code></para></listitem>
119  <listitem><para><code>std::unordered_set</code></para></listitem>
120  <listitem><para><code>std::unordered_multiset</code></para></listitem>
121</itemizedlist>
122
123<para>N.B. although there are precondition checks for some string operations,
124e.g.  <code>operator[]</code>,
125they will not always be run when using the <code>char</code> and
126<code>wchar_t</code> specializations (<code>std::string</code> and
127<code>std::wstring</code>).  This is because libstdc++ uses GCC's
128<code>extern template</code> extension to provide explicit instantiations
129of <code>std::string</code> and <code>std::wstring</code>, and those
130explicit instantiations don't include the debug-mode checks.  If the
131containing functions are inlined then the checks will run, so compiling
132with <code>-O1</code> might be enough to enable them.  Alternatively
133<code>-D_GLIBCXX_EXTERN_TEMPLATE=0</code> will suppress the declarations
134of the explicit instantiations and cause the functions to be instantiated
135with the debug-mode checks included, but this is unsupported and not
136guaranteed to work.  For full debug-mode support you can use the
137<code>__gnu_debug::basic_string</code> debugging container directly,
138which always works correctly.
139</para>
140
141</section>
142
143<section xml:id="manual.ext.debug_mode.using" xreflabel="Using"><info><title>Using</title></info>
144  <?dbhtml filename="debug_mode_using.html"?>
145
146  <para>
147  </para>
148<section xml:id="debug_mode.using.mode" xreflabel="Using Mode"><info><title>Using the Debug Mode</title></info>
149
150
151<para>To use the libstdc++ debug mode, compile your application with the
152  compiler flag <code>-D_GLIBCXX_DEBUG</code>. Note that this flag
153  changes the sizes and behavior of standard class templates such
154  as <code>std::vector</code>, and therefore you can only link code
155  compiled with debug mode and code compiled without debug mode if no
156  instantiation of a container is passed between the two translation
157  units.</para>
158
159<para>By default, error messages are formatted to fit on lines of about
160  78 characters.  The environment variable
161  <code>GLIBCXX_DEBUG_MESSAGE_LENGTH</code> can be used to request a
162  different length.</para>
163
164</section>
165
166<section xml:id="debug_mode.using.specific" xreflabel="Using Specific"><info><title>Using a Specific Debug Container</title></info>
167
168<para>When it is not feasible to recompile your entire application, or
169  only specific containers need checking, debugging containers are
170  available as GNU extensions. These debugging containers are
171  functionally equivalent to the standard drop-in containers used in
172  debug mode, but they are available in a separate namespace as GNU
173  extensions and may be used in programs compiled with either release
174  mode or with debug mode. The
175  following table provides the names and headers of the debugging
176  containers:
177</para>
178
179<table frame="all" xml:id="table.debug_mode_containers">
180<title>Debugging Containers</title>
181
182<tgroup cols="4" align="left" colsep="1" rowsep="1">
183<colspec colname="c1"/>
184<colspec colname="c2"/>
185<colspec colname="c3"/>
186<colspec colname="c4"/>
187
188<thead>
189  <row>
190    <entry>Container</entry>
191    <entry>Header</entry>
192    <entry>Debug container</entry>
193    <entry>Debug header</entry>
194  </row>
195</thead>
196<tbody>
197  <row>
198    <entry><classname>std::bitset</classname></entry>
199    <entry><filename class="headerfile">bitset</filename></entry>
200    <entry><classname>__gnu_debug::bitset</classname></entry>
201    <entry><filename class="headerfile">&lt;debug/bitset&gt;</filename></entry>
202  </row>
203  <row>
204    <entry><classname>std::deque</classname></entry>
205    <entry><filename class="headerfile">deque</filename></entry>
206    <entry><classname>__gnu_debug::deque</classname></entry>
207    <entry><filename class="headerfile">&lt;debug/deque&gt;</filename></entry>
208  </row>
209  <row>
210    <entry><classname>std::list</classname></entry>
211    <entry><filename class="headerfile">list</filename></entry>
212    <entry><classname>__gnu_debug::list</classname></entry>
213    <entry><filename class="headerfile">&lt;debug/list&gt;</filename></entry>
214  </row>
215  <row>
216    <entry><classname>std::map</classname></entry>
217    <entry><filename class="headerfile">map</filename></entry>
218    <entry><classname>__gnu_debug::map</classname></entry>
219    <entry><filename class="headerfile">&lt;debug/map&gt;</filename></entry>
220  </row>
221  <row>
222    <entry><classname>std::multimap</classname></entry>
223    <entry><filename class="headerfile">map</filename></entry>
224    <entry><classname>__gnu_debug::multimap</classname></entry>
225    <entry><filename class="headerfile">&lt;debug/map&gt;</filename></entry>
226  </row>
227  <row>
228    <entry><classname>std::multiset</classname></entry>
229    <entry><filename class="headerfile">set</filename></entry>
230    <entry><classname>__gnu_debug::multiset</classname></entry>
231    <entry><filename class="headerfile">&lt;debug/set&gt;</filename></entry>
232  </row>
233  <row>
234    <entry><classname>std::set</classname></entry>
235    <entry><filename class="headerfile">set</filename></entry>
236    <entry><classname>__gnu_debug::set</classname></entry>
237    <entry><filename class="headerfile">&lt;debug/set&gt;</filename></entry>
238  </row>
239  <row>
240    <entry><classname>std::string</classname></entry>
241    <entry><filename class="headerfile">string</filename></entry>
242    <entry><classname>__gnu_debug::string</classname></entry>
243    <entry><filename class="headerfile">&lt;debug/string&gt;</filename></entry>
244  </row>
245  <row>
246    <entry><classname>std::wstring</classname></entry>
247    <entry><filename class="headerfile">string</filename></entry>
248    <entry><classname>__gnu_debug::wstring</classname></entry>
249    <entry><filename class="headerfile">&lt;debug/string&gt;</filename></entry>
250  </row>
251  <row>
252    <entry><classname>std::basic_string</classname></entry>
253    <entry><filename class="headerfile">string</filename></entry>
254    <entry><classname>__gnu_debug::basic_string</classname></entry>
255    <entry><filename class="headerfile">&lt;debug/string&gt;</filename></entry>
256  </row>
257  <row>
258    <entry><classname>std::vector</classname></entry>
259    <entry><filename class="headerfile">vector</filename></entry>
260    <entry><classname>__gnu_debug::vector</classname></entry>
261    <entry><filename class="headerfile">&lt;debug/vector&gt;</filename></entry>
262  </row>
263</tbody>
264</tgroup>
265</table>
266
267<para>When compiling in C++11 mode (or newer), these
268containers have additional debug capability.
269</para>
270
271<table frame="all" xml:id="table.debug_mode_containers_cxx11">
272<title>Debugging Containers C++11</title>
273
274<tgroup cols="4" align="left" colsep="1" rowsep="1">
275<colspec colname="c1"/>
276<colspec colname="c2"/>
277<colspec colname="c3"/>
278<colspec colname="c4"/>
279
280<thead>
281  <row>
282    <entry>Container</entry>
283    <entry>Header</entry>
284    <entry>Debug container</entry>
285    <entry>Debug header</entry>
286  </row>
287</thead>
288<tbody>
289  <row>
290    <entry><classname>std::forward_list</classname></entry>
291    <entry><filename class="headerfile">forward_list</filename></entry>
292    <entry><classname>__gnu_debug::forward_list</classname></entry>
293    <entry><filename class="headerfile">&lt;debug/forward_list&gt;</filename></entry>
294  </row>
295  <row>
296    <entry><classname>std::unordered_map</classname></entry>
297    <entry><filename class="headerfile">unordered_map</filename></entry>
298    <entry><classname>__gnu_debug::unordered_map</classname></entry>
299    <entry><filename class="headerfile">&lt;debug/unordered_map&gt;</filename></entry>
300  </row>
301  <row>
302    <entry><classname>std::unordered_multimap</classname></entry>
303    <entry><filename class="headerfile">unordered_map</filename></entry>
304    <entry><classname>__gnu_debug::unordered_multimap</classname></entry>
305    <entry><filename class="headerfile">&lt;debug/unordered_map&gt;</filename></entry>
306  </row>
307  <row>
308    <entry><classname>std::unordered_set</classname></entry>
309    <entry><filename class="headerfile">unordered_set</filename></entry>
310    <entry><classname>__gnu_debug::unordered_set</classname></entry>
311    <entry><filename class="headerfile">&lt;debug/unordered_set&gt;</filename></entry>
312  </row>
313  <row>
314    <entry><classname>std::unordered_multiset</classname></entry>
315    <entry><filename class="headerfile">unordered_set</filename></entry>
316    <entry><classname>__gnu_debug::unordered_multiset</classname></entry>
317    <entry><filename class="headerfile">&lt;debug/unordered_set&gt;</filename></entry>
318  </row>
319</tbody>
320</tgroup>
321</table>
322
323<para>Prior to GCC 11 a debug version of <classname>std::array</classname>
324was available as <classname>__gnu_debug::array</classname> in the
325header <filename class="headerfile">&lt;debug/array&gt;</filename>.
326Because <classname>array::iterator</classname> is just a pointer,
327the debug <classname>array</classname> can't check iterator operations,
328it can only check direct accesses to the container.
329Starting with GCC 11 all the debug capabilities are available in
330<classname>std::array</classname>, without needing a separate type,
331so <classname>__gnu_debug::array</classname> is just an alias for
332<classname>std::array</classname>.
333That alias is deprecated and may be removed in a future release.
334</para>
335
336</section>
337</section>
338
339<section xml:id="manual.ext.debug_mode.design" xreflabel="Design"><info><title>Design</title></info>
340  <?dbhtml filename="debug_mode_design.html"?>
341
342  <para>
343  </para>
344  <section xml:id="debug_mode.design.goals" xreflabel="Goals"><info><title>Goals</title></info>
345
346    <para>
347    </para>
348<para> The libstdc++ debug mode replaces unsafe (but efficient) standard
349  containers and iterators with semantically equivalent safe standard
350  containers and iterators to aid in debugging user programs. The
351  following goals directed the design of the libstdc++ debug mode:</para>
352
353  <itemizedlist>
354
355    <listitem><para><emphasis>Correctness</emphasis>: the libstdc++ debug mode must not change
356    the semantics of the standard library for all cases specified in
357    the ANSI/ISO C++ standard. The essence of this constraint is that
358    any valid C++ program should behave in the same manner regardless
359    of whether it is compiled with debug mode or release mode. In
360    particular, entities that are defined in namespace std in release
361    mode should remain defined in namespace std in debug mode, so that
362    legal specializations of namespace std entities will remain
363    valid. A program that is not valid C++ (e.g., invokes undefined
364    behavior) is not required to behave similarly, although the debug
365    mode will abort with a diagnostic when it detects undefined
366    behavior.</para></listitem>
367
368    <listitem><para><emphasis>Performance</emphasis>: the additional of the libstdc++ debug mode
369    must not affect the performance of the library when it is compiled
370    in release mode. Performance of the libstdc++ debug mode is
371    secondary (and, in fact, will be worse than the release
372    mode).</para></listitem>
373
374    <listitem><para><emphasis>Usability</emphasis>: the libstdc++ debug mode should be easy to
375    use. It should be easily incorporated into the user's development
376    environment (e.g., by requiring only a single new compiler switch)
377    and should produce reasonable diagnostics when it detects a
378    problem with the user program. Usability also involves detection
379    of errors when using the debug mode incorrectly, e.g., by linking
380    a release-compiled object against a debug-compiled object if in
381    fact the resulting program will not run correctly.</para></listitem>
382
383    <listitem><para><emphasis>Minimize recompilation</emphasis>: While it is expected that
384    users recompile at least part of their program to use debug
385    mode, the amount of recompilation affects the
386    detect-compile-debug turnaround time. This indirectly affects the
387    usefulness of the debug mode, because debugging some applications
388    may require rebuilding a large amount of code, which may not be
389    feasible when the suspect code may be very localized. There are
390    several levels of conformance to this requirement, each with its
391    own usability and implementation characteristics. In general, the
392    higher-numbered conformance levels are more usable (i.e., require
393    less recompilation) but are more complicated to implement than
394    the lower-numbered conformance levels.
395      <orderedlist inheritnum="ignore" continuation="restarts">
396	<listitem><para><emphasis>Full recompilation</emphasis>: The user must recompile
397	their entire application and all C++ libraries it depends on,
398	including the C++ standard library that ships with the
399	compiler. This must be done even if only a small part of the
400	program can use debugging features.</para></listitem>
401
402	<listitem><para><emphasis>Full user recompilation</emphasis>: The user must recompile
403	their entire application and all C++ libraries it depends
404	on, but not the C++ standard library itself. This must be done
405	even if only a small part of the program can use debugging
406	features. This can be achieved given a full recompilation
407	system by compiling two versions of the standard library when
408	the compiler is installed and linking against the appropriate
409	one, e.g., a multilibs approach.</para></listitem>
410
411	<listitem><para><emphasis>Partial recompilation</emphasis>: The user must recompile the
412	parts of their application and the C++ libraries it
413	depends on that will use the debugging facilities
414	directly. This means that any code that uses the debuggable
415	standard containers would need to be recompiled, but code
416	that does not use them (but may, for instance, use IOStreams)
417	would not have to be recompiled.</para></listitem>
418
419	<listitem><para><emphasis>Per-use recompilation</emphasis>: The user must recompile the
420	parts of their application and the C++ libraries it
421	depends on where debugging should occur, and any other code
422	that interacts with those containers. This means that a set of
423	translation units that accesses a particular standard
424	container instance may either be compiled in release mode (no
425	checking) or debug mode (full checking), but must all be
426	compiled in the same way; a translation unit that does not see
427	that standard container instance need not be recompiled. This
428	also means that a translation unit <emphasis>A</emphasis> that contains a
429	particular instantiation
430	(say, <code>std::vector&lt;int&gt;</code>) compiled in release
431	mode can be linked against a translation unit <emphasis>B</emphasis> that
432	contains the same instantiation compiled in debug mode (a
433	feature not present with partial recompilation). While this
434	behavior is technically a violation of the One Definition
435	Rule, this ability tends to be very important in
436	practice. The libstdc++ debug mode supports this level of
437	recompilation. </para></listitem>
438
439	<listitem><para><emphasis>Per-unit recompilation</emphasis>: The user must only
440	recompile the translation units where checking should occur,
441	regardless of where debuggable standard containers are
442	used. This has also been dubbed "<code>-g</code> mode",
443	because the <code>-g</code> compiler switch works in this way,
444	emitting debugging information at a per--translation-unit
445	granularity. We believe that this level of recompilation is in
446	fact not possible if we intend to supply safe iterators, leave
447	the program semantics unchanged, and not regress in
448	performance under release mode because we cannot associate
449	extra information with an iterator (to form a safe iterator)
450	without either reserving that space in release mode
451	(performance regression) or allocating extra memory associated
452	with each iterator with <code>new</code> (changes the program
453	semantics).</para></listitem>
454      </orderedlist>
455    </para></listitem>
456  </itemizedlist>
457  </section>
458
459  <section xml:id="debug_mode.design.methods" xreflabel="Methods"><info><title>Methods</title></info>
460
461    <para>
462    </para>
463<para>This section provides an overall view of the design of the
464  libstdc++ debug mode and details the relationship between design
465  decisions and the stated design goals.</para>
466
467  <section xml:id="debug_mode.design.methods.wrappers" xreflabel="Method Wrapper"><info><title>The Wrapper Model</title></info>
468
469<para>The libstdc++ debug mode uses a wrapper model where the
470  debugging versions of library components (e.g., iterators and
471  containers) form a layer on top of the release versions of the
472  library components. The debugging components first verify that the
473  operation is correct (aborting with a diagnostic if an error is
474  found) and will then forward to the underlying release-mode
475  container that will perform the actual work. This design decision
476  ensures that we cannot regress release-mode performance (because the
477  release-mode containers are left untouched) and partially
478  enables <link linkend="methods.coexistence.link">mixing debug and
479  release code</link> at link time, although that will not be
480  discussed at this time.</para>
481
482<para>Two types of wrappers are used in the implementation of the debug
483  mode: container wrappers and iterator wrappers. The two types of
484  wrappers interact to maintain relationships between iterators and
485  their associated containers, which are necessary to detect certain
486  types of standard library usage errors such as dereferencing
487  past-the-end iterators or inserting into a container using an
488  iterator from a different container.</para>
489
490  <section xml:id="debug_mode.design.methods.safe_iter" xreflabel="Method Safe Iter"><info><title>Safe Iterators</title></info>
491
492<para>Iterator wrappers provide a debugging layer over any iterator that
493  is attached to a particular container, and will manage the
494  information detailing the iterator's state (singular,
495  dereferenceable, etc.) and tracking the container to which the
496  iterator is attached. Because iterators have a well-defined, common
497  interface the iterator wrapper is implemented with the iterator
498  adaptor class template <code>__gnu_debug::_Safe_iterator</code>,
499  which takes two template parameters:</para>
500
501<itemizedlist>
502  <listitem><para><code>Iterator</code>: The underlying iterator type, which must
503    be either the <code>iterator</code> or <code>const_iterator</code>
504    typedef from the sequence type this iterator can reference.</para></listitem>
505
506  <listitem><para><code>Sequence</code>: The type of sequence that this iterator
507  references. This sequence must be a safe sequence (discussed below)
508  whose <code>iterator</code> or <code>const_iterator</code> typedef
509  is the type of the safe iterator.</para></listitem>
510</itemizedlist>
511  </section>
512
513  <section xml:id="debug_mode.design.methods.safe_seq" xreflabel="Method Safe Seq"><info><title>Safe Sequences (Containers)</title></info>
514
515
516<para>Container wrappers provide a debugging layer over a particular
517  container type. Because containers vary greatly in the member
518  functions they support and the semantics of those member functions
519  (especially in the area of iterator invalidation), container
520  wrappers are tailored to the container they reference, e.g., the
521  debugging version of <code>std::list</code> duplicates the entire
522  interface of <code>std::list</code>, adding additional semantic
523  checks and then forwarding operations to the
524  real <code>std::list</code> (a public base class of the debugging
525  version) as appropriate. However, all safe containers inherit from
526  the class template <code>__gnu_debug::_Safe_sequence</code>,
527  instantiated with the type of the safe container itself (an instance
528  of the curiously recurring template pattern).</para>
529
530<para>The iterators of a container wrapper will be
531  <link linkend="debug_mode.design.methods.safe_iter">safe
532  iterators</link> that reference sequences of this type and wrap the
533  iterators provided by the release-mode base class. The debugging
534  container will use only the safe iterators within its own interface
535  (therefore requiring the user to use safe iterators, although this
536  does not change correct user code) and will communicate with the
537  release-mode base class with only the underlying, unsafe,
538  release-mode iterators that the base class exports.</para>
539
540<para> The debugging version of <code>std::list</code> will have the
541  following basic structure:</para>
542
543<programlisting>
544template&lt;typename _Tp, typename _Allocator = allocator&lt;_Tp&gt;
545  class debug-list :
546    public release-list&lt;_Tp, _Allocator&gt;,
547    public __gnu_debug::_Safe_sequence&lt;debug-list&lt;_Tp, _Allocator&gt; &gt;
548  {
549    typedef release-list&lt;_Tp, _Allocator&gt; _Base;
550    typedef debug-list&lt;_Tp, _Allocator&gt;   _Self;
551
552  public:
553    typedef __gnu_debug::_Safe_iterator&lt;typename _Base::iterator, _Self&gt;       iterator;
554    typedef __gnu_debug::_Safe_iterator&lt;typename _Base::const_iterator, _Self&gt; const_iterator;
555
556    // duplicate std::list interface with debugging semantics
557  };
558</programlisting>
559  </section>
560  </section>
561
562  <section xml:id="debug_mode.design.methods.precond" xreflabel="Precondition check"><info><title>Precondition Checking</title></info>
563
564<para>The debug mode operates primarily by checking the preconditions of
565  all standard library operations that it supports. Preconditions that
566  are always checked (regardless of whether or not we are in debug
567  mode) are checked via the <code>__check_xxx</code> macros defined
568  and documented in the source
569  file <code>include/debug/debug.h</code>. Preconditions that may or
570  may not be checked, depending on the debug-mode
571  macro <code>_GLIBCXX_DEBUG</code>, are checked via
572  the <code>__requires_xxx</code> macros defined and documented in the
573  same source file. Preconditions are validated using any additional
574  information available at run-time, e.g., the containers that are
575  associated with a particular iterator, the position of the iterator
576  within those containers, the distance between two iterators that may
577  form a valid range, etc. In the absence of suitable information,
578  e.g., an input iterator that is not a safe iterator, these
579  precondition checks will silently succeed.</para>
580
581<para>The majority of precondition checks use the aforementioned macros,
582  which have the secondary benefit of having prewritten debug
583  messages that use information about the current status of the
584  objects involved (e.g., whether an iterator is singular or what
585  sequence it is attached to) along with some static information
586  (e.g., the names of the function parameters corresponding to the
587  objects involved). When not using these macros, the debug mode uses
588  either the debug-mode assertion
589  macro <code>_GLIBCXX_DEBUG_ASSERT</code> , its pedantic
590  cousin <code>_GLIBCXX_DEBUG_PEDASSERT</code>, or the assertion
591  check macro that supports more advance formulation of error
592  messages, <code>_GLIBCXX_DEBUG_VERIFY</code>. These macros are
593  documented more thoroughly in the debug mode source code.</para>
594  </section>
595
596  <section xml:id="debug_mode.design.methods.coexistence" xreflabel="Coexistence"><info><title>Release- and debug-mode coexistence</title></info>
597
598<para>The libstdc++ debug mode is the first debug mode we know of that
599  is able to provide the "Per-use recompilation" (4) guarantee, that
600  allows release-compiled and debug-compiled code to be linked and
601  executed together without causing unpredictable behavior. This
602  guarantee minimizes the recompilation that users are required to
603  perform, shortening the detect-compile-debug bug hunting cycle
604  and making the debug mode easier to incorporate into development
605  environments by minimizing dependencies.</para>
606
607<para>Achieving link- and run-time coexistence is not a trivial
608  implementation task. To achieve this goal we use inline namespaces and
609  a complex organization of debug- and release-modes. The end result is
610  that we have achieved per-use recompilation but have had to give up
611  some checking of the <code>std::basic_string</code> class template
612  (namely, safe iterators).</para>
613
614 <section xml:id="methods.coexistence.compile" xreflabel="Compile"><info><title>Compile-time coexistence of release- and debug-mode components</title></info>
615
616
617<para>Both the release-mode components and the debug-mode
618  components need to exist within a single translation unit so that
619  the debug versions can wrap the release versions. However, only one
620  of these components should be user-visible at any particular
621  time with the standard name, e.g., <code>std::list</code>. </para>
622
623<para>In release mode, we define only the release-mode version of the
624  component with its standard name and do not include the debugging
625  component at all. The release mode version is defined within the
626  namespace <code>std</code>. Minus the namespace associations, this
627  method leaves the behavior of release mode completely unchanged from
628  its behavior prior to the introduction of the libstdc++ debug
629  mode. Here's an example of what this ends up looking like, in
630  C++.</para>
631
632<programlisting>
633namespace std
634{
635  template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
636    class list
637    {
638      // ...
639     };
640} // namespace std
641</programlisting>
642
643<para>In debug mode we include the release-mode container (which is now
644defined in the namespace <code>__cxx1998</code>) and also the
645debug-mode container. The debug-mode container is defined within the
646namespace <code>__debug</code>, which is associated with namespace
647<code>std</code> via the C++11 namespace association language feature.  This
648method allows the debug and release versions of the same component to
649coexist at compile-time and link-time without causing an unreasonable
650maintenance burden, while minimizing confusion. Again, this boils down
651to C++ code as follows:</para>
652
653<programlisting>
654namespace std
655{
656  namespace __cxx1998
657  {
658    template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
659      class list
660      {
661	// ...
662      };
663  } // namespace __gnu_norm
664
665  namespace __debug
666  {
667    template&lt;typename _Tp, typename _Alloc = allocator&lt;_Tp&gt; &gt;
668      class list
669      : public __cxx1998::list&lt;_Tp, _Alloc&gt;,
670	public __gnu_debug::_Safe_sequence&lt;list&lt;_Tp, _Alloc&gt; &gt;
671      {
672	// ...
673      };
674  } // namespace __cxx1998
675
676  inline namespace __debug { }
677}
678</programlisting>
679 </section>
680
681 <section xml:id="methods.coexistence.link" xreflabel="Link"><info><title>Link- and run-time coexistence of release- and
682    debug-mode components</title></info>
683
684
685<para>Because each component has a distinct and separate release and
686debug implementation, there is no issue with link-time
687coexistence: the separate namespaces result in different mangled
688names, and thus unique linkage.</para>
689
690<para>However, components that are defined and used within the C++
691standard library itself face additional constraints. For instance,
692some of the member functions of <code> std::moneypunct</code> return
693<code>std::basic_string</code>. Normally, this is not a problem, but
694with a mixed mode standard library that could be using either
695debug-mode or release-mode <code> basic_string</code> objects, things
696get more complicated.  As the return value of a function is not
697encoded into the mangled name, there is no way to specify a
698release-mode or a debug-mode string. In practice, this results in
699runtime errors. A simplified example of this problem is as follows.
700</para>
701
702<para> Take this translation unit, compiled in debug-mode: </para>
703<programlisting>
704// -D_GLIBCXX_DEBUG
705#include &lt;string&gt;
706
707std::string test02();
708
709std::string test01()
710{
711  return test02();
712}
713
714int main()
715{
716  test01();
717  return 0;
718}
719</programlisting>
720
721<para> ... and linked to this translation unit, compiled in release mode:</para>
722
723<programlisting>
724#include &lt;string&gt;
725
726std::string
727test02()
728{
729  return std::string("toast");
730}
731</programlisting>
732
733<para> For this reason we cannot easily provide safe iterators for
734  the <code>std::basic_string</code> class template, as it is present
735  throughout the C++ standard library. For instance, locale facets
736  define typedefs that include <code>basic_string</code>: in a mixed
737  debug/release program, should that typedef be based on the
738  debug-mode <code>basic_string</code> or the
739  release-mode <code>basic_string</code>? While the answer could be
740  "both", and the difference hidden via renaming a la the
741  debug/release containers, we must note two things about locale
742  facets:</para>
743
744<orderedlist inheritnum="ignore" continuation="restarts">
745  <listitem><para>They exist as shared state: one can create a facet in one
746  translation unit and access the facet via the same type name in a
747  different translation unit. This means that we cannot have two
748  different versions of locale facets, because the types would not be
749  the same across debug/release-mode translation unit barriers.</para></listitem>
750
751  <listitem><para>They have virtual functions returning strings: these functions
752  mangle in the same way regardless of the mangling of their return
753  types (see above), and their precise signatures can be relied upon
754  by users because they may be overridden in derived classes.</para></listitem>
755</orderedlist>
756
757<para>With the design of libstdc++ debug mode, we cannot effectively hide
758  the differences between debug and release-mode strings from the
759  user. Failure to hide the differences may result in unpredictable
760  behavior, and for this reason we have opted to only
761  perform <code>basic_string</code> changes that do not require ABI
762  changes. The effect on users is expected to be minimal, as there are
763  simple alternatives (e.g., <code>__gnu_debug::basic_string</code>),
764  and the usability benefit we gain from the ability to mix debug- and
765  release-compiled translation units is enormous.</para>
766 </section>
767
768 <section xml:id="methods.coexistence.alt" xreflabel="Alternatives"><info><title>Alternatives for Coexistence</title></info>
769
770
771<para>The coexistence scheme above was chosen over many alternatives,
772  including language-only solutions and solutions that also required
773  extensions to the C++ front end. The following is a partial list of
774  solutions, with justifications for our rejection of each.</para>
775
776<itemizedlist>
777  <listitem><para><emphasis>Completely separate debug/release libraries</emphasis>: This is by
778  far the simplest implementation option, where we do not allow any
779  coexistence of debug- and release-compiled translation units in a
780  program. This solution has an extreme negative affect on usability,
781  because it is quite likely that some libraries an application
782  depends on cannot be recompiled easily. This would not meet
783  our <emphasis>usability</emphasis> or <emphasis>minimize recompilation</emphasis> criteria
784  well.</para></listitem>
785
786  <listitem><para><emphasis>Add a <code>Debug</code> boolean template parameter</emphasis>:
787  Partial specialization could be used to select the debug
788  implementation when <code>Debug == true</code>, and the state
789  of <code>_GLIBCXX_DEBUG</code> could decide whether the
790  default <code>Debug</code> argument is <code>true</code>
791  or <code>false</code>. This option would break conformance with the
792  C++ standard in both debug <emphasis>and</emphasis> release modes. This would
793  not meet our <emphasis>correctness</emphasis> criteria. </para></listitem>
794
795  <listitem><para><emphasis>Packaging a debug flag in the allocators</emphasis>: We could
796    reuse the <code>Allocator</code> template parameter of containers
797    by adding a sentinel wrapper <code>debug&lt;&gt;</code> that
798    signals the user's intention to use debugging, and pick up
799    the <code>debug&lt;&gt;</code> allocator wrapper in a partial
800    specialization. However, this has two drawbacks: first, there is a
801    conformance issue because the default allocator would not be the
802    standard-specified <code>std::allocator&lt;T&gt;</code>. Secondly
803    (and more importantly), users that specify allocators instead of
804    implicitly using the default allocator would not get debugging
805    containers. Thus this solution fails the <emphasis>correctness</emphasis>
806    criteria.</para></listitem>
807
808  <listitem><para><emphasis>Define debug containers in another namespace, and employ
809      a <code>using</code> declaration (or directive)</emphasis>: This is an
810      enticing option, because it would eliminate the need for
811      the <code>link_name</code> extension by aliasing the
812      templates. However, there is no true template aliasing mechanism
813      in C++, because both <code>using</code> directives and using
814      declarations disallow specialization. This method fails
815      the <emphasis>correctness</emphasis> criteria.</para></listitem>
816
817  <listitem><para><emphasis> Use implementation-specific properties of anonymous
818    namespaces. </emphasis>
819    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>.
820    This method fails the <emphasis>correctness</emphasis> criteria.</para></listitem>
821
822  <listitem><para><emphasis>Extension: allow reopening on namespaces</emphasis>: This would
823    allow the debug mode to effectively alias the
824    namespace <code>std</code> to an internal namespace, such
825    as <code>__gnu_std_debug</code>, so that it is completely
826    separate from the release-mode <code>std</code> namespace. While
827    this will solve some renaming problems and ensure that
828    debug- and release-compiled code cannot be mixed unsafely, it ensures that
829    debug- and release-compiled code cannot be mixed at all. For
830    instance, the program would have two <code>std::cout</code>
831    objects! This solution would fails the <emphasis>minimize
832    recompilation</emphasis> requirement, because we would only be able to
833    support option (1) or (2).</para></listitem>
834
835  <listitem><para><emphasis>Extension: use link name</emphasis>: This option
836    involves complicated re-naming between debug-mode and release-mode
837    components at compile time, and then a g++ extension called <emphasis>
838    link name </emphasis> to recover the original names at link time. There
839    are two drawbacks to this approach. One, it's very verbose,
840    relying on macro renaming at compile time and several levels of
841    include ordering. Two, ODR issues remained with container member
842    functions taking no arguments in mixed-mode settings resulting in
843    equivalent link names, <code> vector::push_back() </code> being
844    one example.
845    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
846    name</link>. </para></listitem>
847</itemizedlist>
848
849<para>Other options may exist for implementing the debug mode, many of
850  which have probably been considered and others that may still be
851  lurking. This list may be expanded over time to include other
852  options that we could have implemented, but in all cases the full
853  ramifications of the approach (as measured against the design goals
854  for a libstdc++ debug mode) should be considered first. The DejaGNU
855  testsuite includes some testcases that check for known problems with
856  some solutions (e.g., the <code>using</code> declaration solution
857  that breaks user specialization), and additional testcases will be
858  added as we are able to identify other typical problem cases. These
859  test cases will serve as a benchmark by which we can compare debug
860  mode implementations.</para>
861 </section>
862  </section>
863  </section>
864
865  <section xml:id="debug_mode.design.other" xreflabel="Other"><info><title>Other Implementations</title></info>
866
867    <para>
868    </para>
869<para> There are several existing implementations of debug modes for C++
870  standard library implementations, although none of them directly
871  supports debugging for programs using libstdc++. The existing
872  implementations include:</para>
873<itemizedlist>
874  <listitem><para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.cs.sjsu.edu/faculty/horstman/safestl.html">SafeSTL</link>:
875  SafeSTL was the original debugging version of the Standard Template
876  Library (STL), implemented by Cay S. Horstmann on top of the
877  Hewlett-Packard STL. Though it inspired much work in this area, it
878  has not been kept up-to-date for use with modern compilers or C++
879  standard library implementations.</para></listitem>
880
881  <listitem><para><link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.stlport.org/">STLport</link>: STLport is a free
882  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
883  ported to many other platforms. It includes a debug mode that uses a
884  wrapper model (that in some ways inspired the libstdc++ debug mode
885  design), although at the time of this writing the debug mode is
886  somewhat incomplete and meets only the "Full user recompilation" (2)
887  recompilation guarantee by requiring the user to link against a
888  different library in debug mode vs. release mode.</para></listitem>
889
890  <listitem><para>Metrowerks CodeWarrior: The C++ standard library
891  that ships with Metrowerks CodeWarrior includes a debug mode. It is
892  a full debug-mode implementation (including debugging for
893  CodeWarrior extensions) and is easy to use, although it meets only
894  the "Full recompilation" (1) recompilation
895  guarantee.</para></listitem>
896</itemizedlist>
897
898  </section>
899</section>
900
901</chapter>
902