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