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"><debug/bitset></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"><debug/deque></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"><debug/list></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"><debug/map></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"><debug/map></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"><debug/set></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"><debug/set></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"><debug/string></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"><debug/string></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"><debug/string></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"><debug/vector></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"><debug/forward_list></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"><debug/unordered_map></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"><debug/unordered_map></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"><debug/unordered_set></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"><debug/unordered_set></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"><debug/array></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<int></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<typename _Tp, typename _Allocator = allocator<_Tp> 545 class debug-list : 546 public release-list<_Tp, _Allocator>, 547 public __gnu_debug::_Safe_sequence<debug-list<_Tp, _Allocator> > 548 { 549 typedef release-list<_Tp, _Allocator> _Base; 550 typedef debug-list<_Tp, _Allocator> _Self; 551 552 public: 553 typedef __gnu_debug::_Safe_iterator<typename _Base::iterator, _Self> iterator; 554 typedef __gnu_debug::_Safe_iterator<typename _Base::const_iterator, _Self> 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<typename _Tp, typename _Alloc = allocator<_Tp> > 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<typename _Tp, typename _Alloc = allocator<_Tp> > 659 class list 660 { 661 // ... 662 }; 663 } // namespace __gnu_norm 664 665 namespace __debug 666 { 667 template<typename _Tp, typename _Alloc = allocator<_Tp> > 668 class list 669 : public __cxx1998::list<_Tp, _Alloc>, 670 public __gnu_debug::_Safe_sequence<list<_Tp, _Alloc> > 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 <string> 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 <string> 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<></code> that 798 signals the user's intention to use debugging, and pick up 799 the <code>debug<></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<T></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