1<?xml version='1.0'?> 2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" 3 "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" 4[ ]> 5 6<chapter id="manual.intro.using" xreflabel="Using"> 7 <?dbhtml filename="using.html"?> 8 9<title>Using</title> 10 11 12 <sect1 id="manual.intro.using.flags" xreflabel="Flags"> 13 <title>Command Options</title> 14 <para> 15 The set of features available in the GNU C++ library is shaped 16 by 17 several <ulink url="http://gcc.gnu.org/onlinedocs/gcc-4.3.2//gcc/Invoking-GCC.html">GCC 18 Command Options</ulink>. Options that impact libstdc++ are 19 enumerated and detailed in the table below. 20 </para> 21 22 <para> 23 By default, <command>g++</command> is equivalent to <command>g++ -std=gnu++98</command>. The standard library also defaults to this dialect. 24 </para> 25 26 <table frame='all'> 27<title>C++ Command Options</title> 28<tgroup cols='2' align='left' colsep='1' rowsep='1'> 29<colspec colname='c1'></colspec> 30<colspec colname='c2'></colspec> 31 32 <thead> 33 <row> 34 <entry>Option Flags</entry> 35 <entry>Description</entry> 36 </row> 37 </thead> 38 39 <tbody> 40 <row> 41 <entry><literal>-std=c++98</literal></entry> 42 <entry>Use the 1998 ISO C++ standard plus amendments.</entry> 43 </row> 44 45 <row> 46 <entry><literal>-std=gnu++98</literal></entry> 47 <entry>As directly above, with GNU extensions.</entry> 48 </row> 49 50 <row> 51 <entry><literal>-std=c++0x</literal></entry> 52 <entry>Use the working draft of the upcoming ISO C++0x standard.</entry> 53 </row> 54 55 <row> 56 <entry><literal>-std=gnu++0x</literal></entry> 57 <entry>As directly above, with GNU extensions.</entry> 58 </row> 59 60 <row> 61 <entry><literal>-fexceptions</literal></entry> 62 <entry>See <link linkend="intro.using.exception.no">exception-free dialect</link></entry> 63 </row> 64 65 <row> 66 <entry><literal>-frtti</literal></entry> 67 <entry>As above, but RTTI-free dialect.</entry> 68 </row> 69 70 <row> 71 <entry><literal>-pthread</literal> or <literal>-pthreads</literal></entry> 72 <entry>For ISO C++0x <thread>, <future>, 73 <mutex>, or <condition_variable>.</entry> 74 </row> 75 76 <row> 77 <entry><literal>-fopenmp</literal></entry> 78 <entry>For <link linkend="manual.ext.parallel_mode">parallel</link> mode.</entry> 79 </row> 80 </tbody> 81 82</tgroup> 83</table> 84 85 </sect1> 86 87 <sect1 id="manual.intro.using.headers" xreflabel="Headers"> 88 <?dbhtml filename="using_headers.html"?> 89 <title>Headers</title> 90 91 <sect2 id="manual.intro.using.headers.all" xreflabel="Header Files"> 92 <title>Header Files</title> 93 94 <para> 95 The C++ standard specifies the entire set of header files that 96 must be available to all hosted implementations. Actually, the 97 word "files" is a misnomer, since the contents of the 98 headers don't necessarily have to be in any kind of external 99 file. The only rule is that when one <code>#include</code>'s a 100 header, the contents of that header become available, no matter 101 how. 102 </para> 103 104 <para> 105 That said, in practice files are used. 106 </para> 107 108 <para> 109 There are two main types of include files: header files related 110 to a specific version of the ISO C++ standard (called Standard 111 Headers), and all others (TR1, C++ ABI, and Extensions). 112 </para> 113 114 <para> 115 Two dialects of standard headers are supported, corresponding to 116 the 1998 standard as updated for 2003, and the draft of the 117 upcoming 200x standard. 118 </para> 119 120 <para> 121 C++98/03 include files. These are available in the default compilation mode, i.e. <code>-std=c++98</code> or <code>-std=gnu++98</code>. 122 </para> 123 124<table frame='all'> 125<title>C++ 1998 Library Headers</title> 126<tgroup cols='5' align='left' colsep='1' rowsep='1'> 127<colspec colname='c1'></colspec> 128<colspec colname='c2'></colspec> 129<colspec colname='c3'></colspec> 130<colspec colname='c4'></colspec> 131<colspec colname='c5'></colspec> 132<tbody> 133<row> 134<entry><filename class="headerfile">algorithm</filename></entry> 135<entry><filename class="headerfile">bitset</filename></entry> 136<entry><filename class="headerfile">complex</filename></entry> 137<entry><filename class="headerfile">deque</filename></entry> 138<entry><filename class="headerfile">exception</filename></entry> 139</row> 140<row> 141<entry><filename class="headerfile">fstream</filename></entry> 142<entry><filename class="headerfile">functional</filename></entry> 143<entry><filename class="headerfile">iomanip</filename></entry> 144<entry><filename class="headerfile">ios</filename></entry> 145<entry><filename class="headerfile">iosfwd</filename></entry> 146</row> 147<row> 148<entry><filename class="headerfile">iostream</filename></entry> 149<entry><filename class="headerfile">istream</filename></entry> 150<entry><filename class="headerfile">iterator</filename></entry> 151<entry><filename class="headerfile">limits</filename></entry> 152<entry><filename class="headerfile">list</filename></entry> 153</row> 154<row> 155<entry><filename class="headerfile">locale</filename></entry> 156<entry><filename class="headerfile">map</filename></entry> 157<entry><filename class="headerfile">memory</filename></entry> 158<entry><filename class="headerfile">new</filename></entry> 159<entry><filename class="headerfile">numeric</filename></entry> 160</row> 161<row> 162<entry><filename class="headerfile">ostream</filename></entry> 163<entry><filename class="headerfile">queue</filename></entry> 164<entry><filename class="headerfile">set</filename></entry> 165<entry><filename class="headerfile">sstream</filename></entry> 166<entry><filename class="headerfile">stack</filename></entry> 167</row> 168<row> 169<entry><filename class="headerfile">stdexcept</filename></entry> 170<entry><filename class="headerfile">streambuf</filename></entry> 171<entry><filename class="headerfile">string</filename></entry> 172<entry><filename class="headerfile">utility</filename></entry> 173<entry><filename class="headerfile">typeinfo</filename></entry> 174</row> 175<row> 176<entry><filename class="headerfile">valarray</filename></entry> 177<entry><filename class="headerfile">vector</filename></entry> 178</row> 179</tbody> 180</tgroup> 181</table> 182 183<para></para> 184<table frame='all'> 185<title>C++ 1998 Library Headers for C Library Facilities</title> 186<tgroup cols='5' align='left' colsep='1' rowsep='1'> 187<colspec colname='c1'></colspec> 188<colspec colname='c2'></colspec> 189<colspec colname='c3'></colspec> 190<colspec colname='c4'></colspec> 191<colspec colname='c5'></colspec> 192<tbody> 193<row> 194<entry><filename class="headerfile">cassert</filename></entry> 195<entry><filename class="headerfile">cerrno</filename></entry> 196<entry><filename class="headerfile">cctype</filename></entry> 197<entry><filename class="headerfile">cfloat</filename></entry> 198<entry><filename class="headerfile">ciso646</filename></entry> 199</row> 200<row> 201<entry><filename class="headerfile">climits</filename></entry> 202<entry><filename class="headerfile">clocale</filename></entry> 203<entry><filename class="headerfile">cmath</filename></entry> 204<entry><filename class="headerfile">csetjmp</filename></entry> 205<entry><filename class="headerfile">csignal</filename></entry> 206</row> 207<row> 208<entry><filename class="headerfile">cstdarg</filename></entry> 209<entry><filename class="headerfile">cstddef</filename></entry> 210<entry><filename class="headerfile">cstdio</filename></entry> 211<entry><filename class="headerfile">cstdlib</filename></entry> 212<entry><filename class="headerfile">cstring</filename></entry> 213</row> 214<row> 215<entry><filename class="headerfile">ctime</filename></entry> 216<entry><filename class="headerfile">cwchar</filename></entry> 217<entry><filename class="headerfile">cwctype</filename></entry> 218</row> 219</tbody> 220</tgroup> 221</table> 222 223<para> 224C++0x include files. These are only available in C++0x compilation 225mode, i.e. <literal>-std=c++0x</literal> or <literal>-std=gnu++0x</literal>. 226</para> 227 228<para></para> 229<table frame='all'> 230<title>C++ 200x Library Headers</title> 231<tgroup cols='5' align='left' colsep='1' rowsep='1'> 232<colspec colname='c1'></colspec> 233<colspec colname='c2'></colspec> 234<colspec colname='c3'></colspec> 235<colspec colname='c4'></colspec> 236<colspec colname='c5'></colspec> 237<tbody> 238 239<row> 240<entry><filename class="headerfile">algorithm</filename></entry> 241<entry><filename class="headerfile">array</filename></entry> 242<entry><filename class="headerfile">bitset</filename></entry> 243<entry><filename class="headerfile">chrono</filename></entry> 244<entry><filename class="headerfile">complex</filename></entry> 245</row> 246<row> 247<entry><filename class="headerfile">condition_variable</filename></entry> 248<entry><filename class="headerfile">deque</filename></entry> 249<entry><filename class="headerfile">exception</filename></entry> 250<entry><filename class="headerfile">forward_list</filename></entry> 251<entry><filename class="headerfile">fstream</filename></entry> 252</row> 253<row> 254<entry><filename class="headerfile">functional</filename></entry> 255<entry><filename class="headerfile">future</filename></entry> 256<entry><filename class="headerfile">initalizer_list</filename></entry> 257<entry><filename class="headerfile">iomanip</filename></entry> 258<entry><filename class="headerfile">ios</filename></entry> 259</row> 260<row> 261<entry><filename class="headerfile">iosfwd</filename></entry> 262<entry><filename class="headerfile">iostream</filename></entry> 263<entry><filename class="headerfile">istream</filename></entry> 264<entry><filename class="headerfile">iterator</filename></entry> 265<entry><filename class="headerfile">limits</filename></entry> 266</row> 267<row> 268<entry><filename class="headerfile">list</filename></entry> 269<entry><filename class="headerfile">locale</filename></entry> 270<entry><filename class="headerfile">map</filename></entry> 271<entry><filename class="headerfile">memory</filename></entry> 272<entry><filename class="headerfile">mutex</filename></entry> 273</row> 274<row> 275<entry><filename class="headerfile">new</filename></entry> 276<entry><filename class="headerfile">numeric</filename></entry> 277<entry><filename class="headerfile">ostream</filename></entry> 278<entry><filename class="headerfile">queue</filename></entry> 279<entry><filename class="headerfile">random</filename></entry> 280</row> 281<row> 282<entry><filename class="headerfile">ratio</filename></entry> 283<entry><filename class="headerfile">regex</filename></entry> 284<entry><filename class="headerfile">set</filename></entry> 285<entry><filename class="headerfile">sstream</filename></entry> 286<entry><filename class="headerfile">stack</filename></entry> 287</row> 288<row> 289<entry><filename class="headerfile">stdexcept</filename></entry> 290<entry><filename class="headerfile">streambuf</filename></entry> 291<entry><filename class="headerfile">string</filename></entry> 292<entry><filename class="headerfile">system_error</filename></entry> 293<entry><filename class="headerfile">thread</filename></entry> 294</row> 295<row> 296<entry><filename class="headerfile">tuple</filename></entry> 297<entry><filename class="headerfile">type_traits</filename></entry> 298<entry><filename class="headerfile">typeinfo</filename></entry> 299<entry><filename class="headerfile">unordered_map</filename></entry> 300<entry><filename class="headerfile">unordered_set</filename></entry> 301</row> 302<row> 303<entry><filename class="headerfile">utility</filename></entry> 304<entry><filename class="headerfile">valarray</filename></entry> 305<entry><filename class="headerfile">vector</filename></entry> 306</row> 307 308</tbody> 309</tgroup> 310</table> 311 312<para></para> 313 314<table frame='all'> 315<title>C++ 200x Library Headers for C Library Facilities</title> 316<tgroup cols='5' align='left' colsep='1' rowsep='1'> 317<colspec colname='c1'></colspec> 318<colspec colname='c2'></colspec> 319<colspec colname='c3'></colspec> 320<colspec colname='c4'></colspec> 321<colspec colname='c5'></colspec> 322<tbody> 323<row> 324<entry><filename class="headerfile">cassert</filename></entry> 325<entry><filename class="headerfile">ccomplex</filename></entry> 326<entry><filename class="headerfile">cctype</filename></entry> 327<entry><filename class="headerfile">cerrno</filename></entry> 328<entry><filename class="headerfile">cfenv</filename></entry> 329</row> 330<row> 331<entry><filename class="headerfile">cfloat</filename></entry> 332<entry><filename class="headerfile">cinttypes</filename></entry> 333<entry><filename class="headerfile">ciso646</filename></entry> 334<entry><filename class="headerfile">climits</filename></entry> 335<entry><filename class="headerfile">clocale</filename></entry> 336</row> 337<row> 338<entry><filename class="headerfile">cmath</filename></entry> 339<entry><filename class="headerfile">csetjmp</filename></entry> 340<entry><filename class="headerfile">csignal</filename></entry> 341<entry><filename class="headerfile">cstdarg</filename></entry> 342<entry><filename class="headerfile">cstdbool</filename></entry> 343</row> 344<row> 345<entry><filename class="headerfile">cstddef</filename></entry> 346<entry><filename class="headerfile">cstdint</filename></entry> 347<entry><filename class="headerfile">cstdlib</filename></entry> 348<entry><filename class="headerfile">cstdio</filename></entry> 349<entry><filename class="headerfile">cstring</filename></entry> 350</row> 351<row> 352<entry><filename class="headerfile">ctgmath</filename></entry> 353<entry><filename class="headerfile">ctime</filename></entry> 354<entry><filename class="headerfile">cuchar</filename></entry> 355<entry><filename class="headerfile">cwchar</filename></entry> 356<entry><filename class="headerfile">cwctype</filename></entry> 357</row> 358<row> 359<entry><filename class="headerfile">stdatomic.h</filename></entry> 360</row> 361 362</tbody> 363</tgroup> 364</table> 365 366 367<para> 368 In addition, TR1 includes as: 369</para> 370 371<table frame='all'> 372<title>C++ TR 1 Library Headers</title> 373<tgroup cols='5' align='left' colsep='1' rowsep='1'> 374<colspec colname='c1'></colspec> 375<colspec colname='c2'></colspec> 376<colspec colname='c3'></colspec> 377<colspec colname='c4'></colspec> 378<colspec colname='c5'></colspec> 379<tbody> 380 381<row> 382<entry><filename class="headerfile">tr1/array</filename></entry> 383<entry><filename class="headerfile">tr1/complex</filename></entry> 384<entry><filename class="headerfile">tr1/memory</filename></entry> 385<entry><filename class="headerfile">tr1/functional</filename></entry> 386<entry><filename class="headerfile">tr1/random</filename></entry> 387</row> 388<row> 389<entry><filename class="headerfile">tr1/regex</filename></entry> 390<entry><filename class="headerfile">tr1/tuple</filename></entry> 391<entry><filename class="headerfile">tr1/type_traits</filename></entry> 392<entry><filename class="headerfile">tr1/unordered_map</filename></entry> 393<entry><filename class="headerfile">tr1/unordered_set</filename></entry> 394</row> 395<row> 396<entry><filename class="headerfile">tr1/utility</filename></entry> 397</row> 398 399</tbody> 400</tgroup> 401</table> 402 403<para></para> 404 405 406<table frame='all'> 407<title>C++ TR 1 Library Headers for C Library Facilities</title> 408<tgroup cols='5' align='left' colsep='1' rowsep='1'> 409<colspec colname='c1'></colspec> 410<colspec colname='c2'></colspec> 411<colspec colname='c3'></colspec> 412<colspec colname='c4'></colspec> 413<colspec colname='c5'></colspec> 414<tbody> 415 416<row> 417<entry><filename class="headerfile">tr1/ccomplex</filename></entry> 418<entry><filename class="headerfile">tr1/cfenv</filename></entry> 419<entry><filename class="headerfile">tr1/cfloat</filename></entry> 420<entry><filename class="headerfile">tr1/cmath</filename></entry> 421<entry><filename class="headerfile">tr1/cinttypes</filename></entry> 422</row> 423<row> 424<entry><filename class="headerfile">tr1/climits</filename></entry> 425<entry><filename class="headerfile">tr1/cstdarg</filename></entry> 426<entry><filename class="headerfile">tr1/cstdbool</filename></entry> 427<entry><filename class="headerfile">tr1/cstdint</filename></entry> 428<entry><filename class="headerfile">tr1/cstdio</filename></entry> 429</row> 430<row> 431<entry><filename class="headerfile">tr1/cstdlib</filename></entry> 432<entry><filename class="headerfile">tr1/ctgmath</filename></entry> 433<entry><filename class="headerfile">tr1/ctime</filename></entry> 434<entry><filename class="headerfile">tr1/cwchar</filename></entry> 435<entry><filename class="headerfile">tr1/cwctype</filename></entry> 436</row> 437 438</tbody> 439</tgroup> 440</table> 441 442 443<para>Decimal floating-point arithmetic is available if the C++ 444compiler supports scalar decimal floating-point types defined via 445<code>__attribute__((mode(SD|DD|LD)))</code>. 446</para> 447 448<table frame='all'> 449<title>C++ TR 24733 Decimal Floating-Point Header</title> 450<tgroup cols='1' align='left' colsep='1' rowsep='1'> 451<colspec colname='c1'></colspec> 452<tbody> 453<row> 454<entry><filename class="headerfile">decimal/decimal</filename></entry> 455</row> 456</tbody> 457</tgroup> 458</table> 459 460<para> 461 Also included are files for the C++ ABI interface: 462</para> 463 464<table frame='all'> 465<title>C++ ABI Headers</title> 466<tgroup cols='2' align='left' colsep='1' rowsep='1'> 467<colspec colname='c1'></colspec> 468<colspec colname='c2'></colspec> 469<tbody> 470<row><entry><filename class="headerfile">cxxabi.h</filename></entry><entry><filename class="headerfile">cxxabi_forced.h</filename></entry></row> 471</tbody> 472</tgroup> 473</table> 474 475<para> 476 And a large variety of extensions. 477</para> 478 479<table frame='all'> 480<title>Extension Headers</title> 481<tgroup cols='5' align='left' colsep='1' rowsep='1'> 482<colspec colname='c1'></colspec> 483<colspec colname='c2'></colspec> 484<colspec colname='c3'></colspec> 485<colspec colname='c4'></colspec> 486<colspec colname='c5'></colspec> 487<tbody> 488 489<row> 490<entry><filename class="headerfile">ext/algorithm</filename></entry> 491<entry><filename class="headerfile">ext/atomicity.h</filename></entry> 492<entry><filename class="headerfile">ext/array_allocator.h</filename></entry> 493<entry><filename class="headerfile">ext/bitmap_allocator.h</filename></entry> 494<entry><filename class="headerfile">ext/cast.h</filename></entry> 495</row> 496<row> 497<entry><filename class="headerfile">ext/codecvt_specializations.h</filename></entry> 498<entry><filename class="headerfile">ext/concurrence.h</filename></entry> 499<entry><filename class="headerfile">ext/debug_allocator.h</filename></entry> 500<entry><filename class="headerfile">ext/enc_filebuf.h</filename></entry> 501<entry><filename class="headerfile">ext/extptr_allocator.h</filename></entry> 502</row> 503<row> 504<entry><filename class="headerfile">ext/functional</filename></entry> 505<entry><filename class="headerfile">ext/iterator</filename></entry> 506<entry><filename class="headerfile">ext/malloc_allocator.h</filename></entry> 507<entry><filename class="headerfile">ext/memory</filename></entry> 508<entry><filename class="headerfile">ext/mt_allocator.h</filename></entry> 509</row> 510<row> 511<entry><filename class="headerfile">ext/new_allocator.h</filename></entry> 512<entry><filename class="headerfile">ext/numeric</filename></entry> 513<entry><filename class="headerfile">ext/numeric_traits.h</filename></entry> 514<entry><filename class="headerfile">ext/pb_ds/assoc_container.h</filename></entry> 515<entry><filename class="headerfile">ext/pb_ds/priority_queue.h</filename></entry> 516</row> 517<row> 518<entry><filename class="headerfile">ext/pod_char_traits.h</filename></entry> 519<entry><filename class="headerfile">ext/pool_allocator.h</filename></entry> 520<entry><filename class="headerfile">ext/rb_tree</filename></entry> 521<entry><filename class="headerfile">ext/rope</filename></entry> 522<entry><filename class="headerfile">ext/slist</filename></entry> 523</row> 524<row> 525<entry><filename class="headerfile">ext/stdio_filebuf.h</filename></entry> 526<entry><filename class="headerfile">ext/stdio_sync_filebuf.h</filename></entry> 527<entry><filename class="headerfile">ext/throw_allocator.h</filename></entry> 528<entry><filename class="headerfile">ext/typelist.h</filename></entry> 529<entry><filename class="headerfile">ext/type_traits.h</filename></entry> 530</row> 531<row> 532<entry><filename class="headerfile">ext/vstring.h</filename></entry> 533</row> 534 535</tbody> 536</tgroup> 537</table> 538 539<para></para> 540 541<table frame='all'> 542<title>Extension Debug Headers</title> 543<tgroup cols='5' align='left' colsep='1' rowsep='1'> 544<colspec colname='c1'></colspec> 545<colspec colname='c2'></colspec> 546<colspec colname='c3'></colspec> 547<colspec colname='c4'></colspec> 548<colspec colname='c5'></colspec> 549<tbody> 550 551<row> 552<entry><filename class="headerfile">debug/bitset</filename></entry> 553<entry><filename class="headerfile">debug/deque</filename></entry> 554<entry><filename class="headerfile">debug/list</filename></entry> 555<entry><filename class="headerfile">debug/map</filename></entry> 556<entry><filename class="headerfile">debug/set</filename></entry> 557</row> 558 559<row> 560<entry><filename class="headerfile">debug/string</filename></entry> 561<entry><filename class="headerfile">debug/unordered_map</filename></entry> 562<entry><filename class="headerfile">debug/unordered_set</filename></entry> 563<entry><filename class="headerfile">debug/vector</filename></entry> 564</row> 565 566</tbody> 567</tgroup> 568</table> 569 570<para></para> 571 572<table frame='all'> 573<title>Extension Profile Headers</title> 574<tgroup cols='4' align='left' colsep='1' rowsep='1'> 575<colspec colname='c1'></colspec> 576<colspec colname='c2'></colspec> 577<colspec colname='c3'></colspec> 578<colspec colname='c4'></colspec> 579<tbody> 580 581<row> 582<entry><filename class="headerfile">profile/bitset</filename></entry> 583<entry><filename class="headerfile">profile/deque</filename></entry> 584<entry><filename class="headerfile">profile/list</filename></entry> 585<entry><filename class="headerfile">profile/map</filename></entry> 586</row> 587 588<row> 589<entry><filename class="headerfile">profile/set</filename></entry> 590<entry><filename class="headerfile">profile/unordered_map</filename></entry> 591<entry><filename class="headerfile">profile/unordered_set</filename></entry> 592<entry><filename class="headerfile">profile/vector</filename></entry> 593</row> 594 595</tbody> 596</tgroup> 597</table> 598 599<para></para> 600 601<table frame='all'> 602<title>Extension Parallel Headers</title> 603<tgroup cols='2' align='left' colsep='1' rowsep='1'> 604<colspec colname='c1'></colspec> 605<colspec colname='c2'></colspec> 606<tbody> 607<row> 608<entry><filename class="headerfile">parallel/algorithm</filename></entry> 609<entry><filename class="headerfile">parallel/numeric</filename></entry> 610</row> 611</tbody> 612</tgroup> 613</table> 614 615 </sect2> 616 617 <sect2 id="manual.intro.using.headers.mixing" xreflabel="Mixing Headers"> 618 <title>Mixing Headers</title> 619 620<para> A few simple rules. 621</para> 622 623<para>First, mixing different dialects of the standard headers is not 624possible. It's an all-or-nothing affair. Thus, code like 625</para> 626 627<programlisting> 628#include <array> 629#include <functional> 630</programlisting> 631 632<para>Implies C++0x mode. To use the entities in <array>, the C++0x 633compilation mode must be used, which implies the C++0x functionality 634(and deprecations) in <functional> will be present. 635</para> 636 637<para>Second, the other headers can be included with either dialect of 638the standard headers, although features and types specific to C++0x 639are still only enabled when in C++0x compilation mode. So, to use 640rvalue references with <code>__gnu_cxx::vstring</code>, or to use the 641debug-mode versions of <code>std::unordered_map</code>, one must use 642the <code>std=gnu++0x</code> compiler flag. (Or <code>std=c++0x</code>, of course.) 643</para> 644 645<para>A special case of the second rule is the mixing of TR1 and C++0x 646facilities. It is possible (although not especially prudent) to 647include both the TR1 version and the C++0x version of header in the 648same translation unit: 649</para> 650 651<programlisting> 652#include <tr1/type_traits> 653#include <type_traits> 654</programlisting> 655 656<para> Several parts of C++0x diverge quite substantially from TR1 predecessors. 657</para> 658 </sect2> 659 660 <sect2 id="manual.intro.using.headers.cheaders" xreflabel="C Headers and"> 661 <title>The C Headers and <code>namespace std</code></title> 662 663<para> 664 The standard specifies that if one includes the C-style header 665 (<math.h> in this case), the symbols will be available 666 in the global namespace and perhaps in 667 namespace <code>std::</code> (but this is no longer a firm 668 requirement.) On the other hand, including the C++-style 669 header (<cmath>) guarantees that the entities will be 670 found in namespace std and perhaps in the global namespace. 671 </para> 672 673<para> 674Usage of C++-style headers is recommended, as then 675C-linkage names can be disambiguated by explicit qualification, such 676as by <code>std::abort</code>. In addition, the C++-style headers can 677use function overloading to provide a simpler interface to certain 678families of C-functions. For instance in <cmath>, the 679function <code>std::sin</code> has overloads for all the builtin 680floating-point types. This means that <code>std::sin</code> can be 681used uniformly, instead of a combination 682of <code>std::sinf</code>, <code>std::sin</code>, 683and <code>std::sinl</code>. 684</para> 685 </sect2> 686 687 <sect2 id="manual.intro.using.headers.pre" xreflabel="Precompiled Headers"> 688 <title>Precompiled Headers</title> 689 690 691<para>There are three base header files that are provided. They can be 692used to precompile the standard headers and extensions into binary 693files that may the be used to speed compiles that use these headers. 694</para> 695 696 697<itemizedlist> 698<listitem> 699 <para>stdc++.h</para> 700<para>Includes all standard headers. Actual content varies depending on 701language dialect. 702</para> 703</listitem> 704 705<listitem> 706 <para>stdtr1c++.h</para> 707<para>Includes all of <stdc++.h>, and adds all the TR1 headers. 708</para> 709</listitem> 710 711<listitem><para>extc++.h</para> 712<para>Includes all of <stdtr1c++.h>, and adds all the Extension headers. 713</para></listitem> 714</itemizedlist> 715 716<para>How to construct a .gch file from one of these base header files.</para> 717 718<para>First, find the include directory for the compiler. One way to do 719this is:</para> 720 721<programlisting> 722g++ -v hello.cc 723 724#include <...> search starts here: 725 /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0 726... 727End of search list. 728</programlisting> 729 730 731<para>Then, create a precompiled header file with the same flags that 732will be used to compile other projects.</para> 733 734<programlisting> 735g++ -Winvalid-pch -x c++-header -g -O2 -o ./stdc++.h.gch /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/x86_64-unknown-linux-gnu/bits/stdc++.h 736</programlisting> 737 738<para>The resulting file will be quite large: the current size is around 739thirty megabytes. </para> 740 741<para>How to use the resulting file.</para> 742 743<programlisting> 744g++ -I. -include stdc++.h -H -g -O2 hello.cc 745</programlisting> 746 747<para>Verification that the PCH file is being used is easy:</para> 748 749<programlisting> 750g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe 751! ./stdc++.h.gch 752. /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream 753. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string 754</programlisting> 755 756<para>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used, and thus the </para> 757<para></para> 758 759<para> Detailed information about creating precompiled header files can be found in the GCC <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</ulink>. 760</para> 761 762 </sect2> 763 </sect1> 764 765 766 <sect1 id="manual.intro.using.macros" xreflabel="Macros"> 767 <?dbhtml filename="using_macros.html"?> 768 <title>Macros</title> 769 770 <para> 771 All library macros begin with <code>_GLIBCXX_</code>. 772 </para> 773 774 <para> 775 Furthermore, all pre-processor macros, switches, and 776 configuration options are gathered in the 777 file <filename class="headerfile">c++config.h</filename>, which 778 is generated during the libstdc++ configuration and build 779 process. This file is then included when needed by files part of 780 the public libstdc++ API, like <ios>. Most of these macros 781 should not be used by consumers of libstdc++, and are reserved 782 for internal implementation use. <emphasis>These macros cannot 783 be redefined</emphasis>. 784 </para> 785 786 <para> 787 A select handful of macros control libstdc++ extensions and extra 788 features, or provide versioning information for the API. Only 789 those macros listed below are offered for consideration by the 790 general public. 791 </para> 792 793 <para>Below is the macro which users may check for library version 794 information. </para> 795 796 <variablelist> 797 <varlistentry> 798 <term><code>__GLIBCXX__</code></term> 799 <listitem> 800 <para>The current version of 801 libstdc++ in compressed ISO date format, form of an unsigned 802 long. For details on the value of this particular macro for a 803 particular release, please consult this <link linkend="appendix.porting.abi"> 804 document</link>. 805 </para> 806 </listitem> 807 </varlistentry> 808 </variablelist> 809 810 <para>Below are the macros which users may change with #define/#undef or 811 with -D/-U compiler flags. The default state of the symbol is 812 listed.</para> 813 814 <para><quote>Configurable</quote> (or <quote>Not configurable</quote>) means 815 that the symbol is initially chosen (or not) based on 816 --enable/--disable options at library build and configure time 817 (documented <link linkend="manual.intro.setup.configure">here</link>), with the 818 various --enable/--disable choices being translated to 819 #define/#undef). 820 </para> 821 822 <para> <acronym>ABI</acronym> means that changing from the default value may 823 mean changing the <acronym>ABI</acronym> of compiled code. In other words, these 824 choices control code which has already been compiled (i.e., in a 825 binary such as libstdc++.a/.so). If you explicitly #define or 826 #undef these macros, the <emphasis>headers</emphasis> may see different code 827 paths, but the <emphasis>libraries</emphasis> which you link against will not. 828 Experimenting with different values with the expectation of 829 consistent linkage requires changing the config headers before 830 building/installing the library. 831 </para> 832 833 <variablelist> 834 <varlistentry><term><code>_GLIBCXX_DEPRECATED</code></term> 835 <listitem> 836 <para> 837 Defined by default. Not configurable. ABI-changing. Turning this off 838 removes older ARM-style iostreams code, and other anachronisms 839 from the API. This macro is dependent on the version of the 840 standard being tracked, and as a result may give different results for 841 <code>-std=c++98</code> and <code>-std=c++0x</code>. This may 842 be useful in updating old C++ code which no longer meet the 843 requirements of the language, or for checking current code 844 against new language standards. 845 </para> 846 </listitem></varlistentry> 847 848 <varlistentry><term><code>_GLIBCXX_FORCE_NEW</code></term> 849 <listitem> 850 <para> 851 Undefined by default. When defined, memory allocation and 852 allocators controlled by libstdc++ call operator new/delete 853 without caching and pooling. Configurable via 854 <code>--enable-libstdcxx-allocator</code>. ABI-changing. 855 </para> 856 </listitem></varlistentry> 857 858 859 <varlistentry><term><code>_GLIBCXX_CONCEPT_CHECKS</code></term> 860 <listitem> 861 <para> 862 Undefined by default. Configurable via 863 <code>--enable-concept-checks</code>. When defined, performs 864 compile-time checking on certain template instantiations to 865 detect violations of the requirements of the standard. This 866 is described in more detail <link 867 linkend="manual.ext.compile_checks">here</link>. 868 </para> 869 </listitem></varlistentry> 870 871 <varlistentry><term><code>_GLIBCXX_DEBUG</code></term> 872 <listitem> 873 <para> 874 Undefined by default. When defined, compiles user code using 875 the <link linkend="manual.ext.debug_mode">debug mode</link>. 876 </para> 877 </listitem></varlistentry> 878 <varlistentry><term><code>_GLIBCXX_DEBUG_PEDANTIC</code></term> 879 <listitem> 880 <para> 881 Undefined by default. When defined while compiling with 882 the <link linkend="manual.ext.debug_mode">debug mode</link>, makes 883 the debug mode extremely picky by making the use of libstdc++ 884 extensions and libstdc++-specific behavior into errors. 885 </para> 886 </listitem></varlistentry> 887 <varlistentry><term><code>_GLIBCXX_PARALLEL</code></term> 888 <listitem> 889 <para>Undefined by default. When defined, compiles user code 890 using the <link linkend="manual.ext.parallel_mode">parallel 891 mode</link>. 892 </para> 893 </listitem></varlistentry> 894 895 <varlistentry><term><code>_GLIBCXX_PROFILE</code></term> 896 <listitem> 897 <para>Undefined by default. When defined, compiles user code 898 using the <link linkend="manual.ext.profile_mode">profile 899 mode</link>. 900 </para> 901 </listitem></varlistentry> 902 </variablelist> 903 904 </sect1> 905 906 <sect1 id="manual.intro.using.namespaces" xreflabel="Namespaces"> 907 <?dbhtml filename="using_namespaces.html"?> 908 <title>Namespaces</title> 909 910 <sect2 id="manual.intro.using.namespaces.all" xreflabel="Available Namespaces"> 911 <title>Available Namespaces</title> 912 913 914 915<para> There are three main namespaces. 916</para> 917 918<itemizedlist> 919 <listitem><para>std</para> 920<para>The ISO C++ standards specify that "all library entities are defined 921within namespace std." This includes namespaces nested 922within <code>namespace std</code>, such as <code>namespace 923std::tr1</code>. 924</para> 925</listitem> 926<listitem><para>abi</para> 927<para>Specified by the C++ ABI. This ABI specifies a number of type and 928function APIs supplemental to those required by the ISO C++ Standard, 929but necessary for interoperability. 930</para> 931</listitem> 932 933<listitem><para>__gnu_</para> 934<para>Indicating one of several GNU extensions. Choices 935include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>, 936and <code>__gnu_pbds</code>. 937</para></listitem> 938</itemizedlist> 939 940<para> A complete list of implementation namespaces (including namespace contents) is available in the generated source <ulink url="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</ulink>. 941</para> 942 943 944 </sect2> 945 946 <sect2 id="manual.intro.using.namespaces.std" xreflabel="namespace std"> 947 <title>namespace std</title> 948 949 950<para> 951 One standard requirement is that the library components are defined 952 in <code>namespace std::</code>. Thus, in order to use these types or 953 functions, one must do one of two things: 954</para> 955 956<itemizedlist> 957 <listitem><para>put a kind of <emphasis>using-declaration</emphasis> in your source 958(either <code>using namespace std;</code> or i.e. <code>using 959std::string;</code>) This approach works well for individual source files, but 960should not be used in a global context, like header files. 961 </para></listitem> <listitem><para>use a <emphasis>fully 962qualified name</emphasis> for each library symbol 963(i.e. <code>std::string</code>, <code>std::cout</code>) Always can be 964used, and usually enhanced, by strategic use of typedefs. (In the 965cases where the qualified verbiage becomes unwieldy.) 966 </para> 967 </listitem> 968</itemizedlist> 969 970 </sect2> 971 972 <sect2 id="manual.intro.using.namespaces.comp" xreflabel="Using Namespace Composition"> 973 <title>Using Namespace Composition</title> 974 975<para> 976Best practice in programming suggests sequestering new data or 977functionality in a sanely-named, unique namespace whenever 978possible. This is considered an advantage over dumping everything in 979the global namespace, as then name look-up can be explicitly enabled or 980disabled as above, symbols are consistently mangled without repetitive 981naming prefixes or macros, etc. 982</para> 983 984<para>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to 985 adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called 986 <emphasis>namespace composition</emphasis>. This is what happens if 987 a <emphasis>using</emphasis>-declaration is put into a 988 namespace-definition: the imported symbol(s) gets imported into the 989 currently active namespace(s). For example: 990</para> 991<programlisting> 992namespace gtk 993{ 994 using std::string; 995 using std::tr1::array; 996 997 class Window { ... }; 998} 999</programlisting> 1000<para> 1001 In this example, <code>std::string</code> gets imported into 1002 <code>namespace gtk</code>. The result is that use of 1003 <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification. 1004 As an added bonus, 1005 <code>std::string</code> does not get imported into 1006 the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the 1007 <code>using</code>-declarations can wrapped in macros that 1008 are set based on autoconf-tests to either "" or i.e. <code>using 1009 std::string;</code> (depending on whether the system has 1010 libstdc++ in <code>std::</code> or not). (ideas from 1011 Llewelly and Karl Nelson) 1012</para> 1013 1014 1015 </sect2> 1016 </sect1> 1017 1018 <sect1 id="manual.intro.using.linkage" xreflabel="Linkage"> 1019 <?dbhtml filename="using_dynamic_or_shared.html"?> 1020 <title>Linking</title> 1021 1022 <sect2 id="manual.intro.using.linkage.freestanding" xreflabel="Freestanding"> 1023 <title>Almost Nothing</title> 1024 <para> 1025 Or as close as it gets: freestanding. This is a minimal 1026 configuration, with only partial support for the standard 1027 library. Assume only the following header files can be used: 1028 </para> 1029 1030 <itemizedlist> 1031 <listitem> 1032 <para> 1033 <filename class="headerfile">cstdarg</filename> 1034 </para> 1035 </listitem> 1036 1037 <listitem> 1038 <para> 1039 <filename class="headerfile">cstddef</filename> 1040 </para> 1041 </listitem> 1042 1043 <listitem> 1044 <para> 1045 <filename class="headerfile">cstdlib</filename> 1046 </para> 1047 </listitem> 1048 1049 <listitem> 1050 <para> 1051 <filename class="headerfile">exception</filename> 1052 </para> 1053 </listitem> 1054 1055 <listitem> 1056 <para> 1057 <filename class="headerfile">limits</filename> 1058 </para> 1059 </listitem> 1060 1061 <listitem> 1062 <para> 1063 <filename class="headerfile">new</filename> 1064 </para> 1065 </listitem> 1066 1067 <listitem> 1068 <para> 1069 <filename class="headerfile">exception</filename> 1070 </para> 1071 </listitem> 1072 1073 <listitem> 1074 <para> 1075 <filename class="headerfile">typeinfo</filename> 1076 </para> 1077 </listitem> 1078 </itemizedlist> 1079 1080 <para> 1081 In addition, throw in 1082 </para> 1083 1084 <itemizedlist> 1085 <listitem> 1086 <para> 1087 <filename class="headerfile">cxxabi.h</filename>. 1088 </para> 1089 </listitem> 1090 </itemizedlist> 1091 1092 <para> 1093 In the 1094 C++0x <link linkend="manual.intro.using.flags">dialect</link> add 1095 </para> 1096 1097 <itemizedlist> 1098 <listitem> 1099 <para> 1100 <filename class="headerfile">initializer_list</filename> 1101 </para> 1102 </listitem> 1103 <listitem> 1104 <para> 1105 <filename class="headerfile">type_traits</filename> 1106 </para> 1107 </listitem> 1108 </itemizedlist> 1109 1110 <para> There exists a library that offers runtime support for 1111 just these headers, and it is called 1112 <filename class="libraryfile">libsupc++.a</filename>. To use it, compile with <command>gcc</command> instead of <command>g++</command>, like so: 1113 </para> 1114 1115 <para> 1116 <command>gcc foo.cc -lsupc++</command> 1117 </para> 1118 1119 <para> 1120 No attempt is made to verify that only the minimal subset 1121 identified above is actually used at compile time. Violations 1122 are diagnosed as undefined symbols at link time. 1123 </para> 1124 </sect2> 1125 1126 <sect2 id="manual.intro.using.linkage.dynamic" xreflabel="Dynamic and Shared"> 1127 <title>Finding Dynamic or Shared Libraries</title> 1128 1129 <para> 1130 If the only library built is the static library 1131 (<filename class="libraryfile">libstdc++.a</filename>), or if 1132 specifying static linking, this section is can be skipped. But 1133 if building or using a shared library 1134 (<filename class="libraryfile">libstdc++.so</filename>), then 1135 additional location information will need to be provided. 1136 </para> 1137 <para> 1138 But how? 1139 </para> 1140 <para> 1141A quick read of the relevant part of the GCC 1142 manual, <ulink url="http://gcc.gnu.org/onlinedocs/gcc/Invoking-G_002b_002b.html#Invoking-G_002b_002b">Compiling 1143 C++ Programs</ulink>, specifies linking against a C++ 1144 library. More details from the 1145 GCC <ulink url="http://gcc.gnu.org/faq.html#rpath">FAQ</ulink>, 1146 which states <emphasis>GCC does not, by default, specify a 1147 location so that the dynamic linker can find dynamic libraries at 1148 runtime.</emphasis> 1149 </para> 1150 <para> 1151 Users will have to provide this information. 1152 </para> 1153 <para> 1154 Methods vary for different platforms and different styles, and 1155 are printed to the screen during installation. To summarize: 1156 </para> 1157 <itemizedlist> 1158 <listitem> 1159 <para> 1160 At runtime set <literal>LD_LIBRARY_PATH</literal> in your 1161 environment correctly, so that the shared library for 1162 libstdc++ can be found and loaded. Be certain that you 1163 understand all of the other implications and behavior 1164 of <literal>LD_LIBRARY_PATH</literal> first. 1165 </para> 1166 1167 </listitem> 1168 <listitem> 1169 <para> 1170 Compile the path to find the library at runtime into the 1171 program. This can be done by passing certain options to 1172 <command>g++</command>, which will in turn pass them on to 1173 the linker. The exact format of the options is dependent on 1174 which linker you use: 1175 </para> 1176 <itemizedlist> 1177 <listitem> 1178 <para> 1179 GNU ld (default on Linux):<literal>-Wl,--rpath,<filename class="directory">destdir</filename>/lib</literal> 1180 </para> 1181 </listitem> 1182 <listitem> 1183 <para> 1184 IRIX ld:<literal> 1185 -Wl,-rpath,<filename class="directory">destdir</filename>/lib</literal> 1186 </para> 1187 </listitem> 1188 <listitem> 1189 <para> 1190 Solaris ld:<literal>-Wl,-R<filename class="directory">destdir</filename>/lib</literal> 1191 </para> 1192 </listitem> 1193 </itemizedlist> 1194 </listitem> 1195 </itemizedlist> 1196 <para> 1197 Use the <command>ldd</command> utility on the linked executable 1198 to show 1199 which <filename class="libraryfile">libstdc++.so</filename> 1200 library the system will get at runtime. 1201 </para> 1202 <para> 1203 A <filename class="libraryfile">libstdc++.la</filename> file is 1204 also installed, for use with Libtool. If you use Libtool to 1205 create your executables, these details are taken care of for 1206 you. 1207 </para> 1208 </sect2> 1209 </sect1> 1210 1211 1212 <sect1 id="manual.intro.using.concurrency" xreflabel="Concurrency"> 1213 <?dbhtml filename="using_concurrency.html"?> 1214 <title>Concurrency</title> 1215 1216 <para>This section discusses issues surrounding the proper compilation 1217 of multithreaded applications which use the Standard C++ 1218 library. This information is GCC-specific since the C++ 1219 standard does not address matters of multithreaded applications. 1220 </para> 1221 1222 <sect2 id="manual.intro.using.concurrency.prereq" xreflabel="Thread Prereq"> 1223 <title>Prerequisites</title> 1224 1225 <para>All normal disclaimers aside, multithreaded C++ application are 1226 only supported when libstdc++ and all user code was built with 1227 compilers which report (via <code> gcc/g++ -v </code>) the same thread 1228 model and that model is not <emphasis>single</emphasis>. As long as your 1229 final application is actually single-threaded, then it should be 1230 safe to mix user code built with a thread model of 1231 <emphasis>single</emphasis> with a libstdc++ and other C++ libraries built 1232 with another thread model useful on the platform. Other mixes 1233 may or may not work but are not considered supported. (Thus, if 1234 you distribute a shared C++ library in binary form only, it may 1235 be best to compile it with a GCC configured with 1236 --enable-threads for maximal interchangeability and usefulness 1237 with a user population that may have built GCC with either 1238 --enable-threads or --disable-threads.) 1239 </para> 1240 <para>When you link a multithreaded application, you will probably 1241 need to add a library or flag to g++. This is a very 1242 non-standardized area of GCC across ports. Some ports support a 1243 special flag (the spelling isn't even standardized yet) to add 1244 all required macros to a compilation (if any such flags are 1245 required then you must provide the flag for all compilations not 1246 just linking) and link-library additions and/or replacements at 1247 link time. The documentation is weak. Here is a quick summary 1248 to display how ad hoc this is: On Solaris, both -pthreads and 1249 -threads (with subtly different meanings) are honored. On OSF, 1250 -pthread and -threads (with subtly different meanings) are 1251 honored. On Linux/i386, -pthread is honored. On FreeBSD, 1252 -pthread is honored. Some other ports use other switches. 1253 AFAIK, none of this is properly documented anywhere other than 1254 in ``gcc -dumpspecs'' (look at lib and cpp entries). 1255 </para> 1256 1257 </sect2> 1258 1259 <sect2 id="manual.intro.using.concurrency.thread_safety" xreflabel="Thread Safety"> 1260 <title>Thread Safety</title> 1261 1262 1263<para> 1264We currently use the <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI STL</ulink> definition of thread safety. 1265</para> 1266 1267 1268 <para>The library strives to be thread-safe when all of the following 1269 conditions are met: 1270 </para> 1271 <itemizedlist> 1272 <listitem> 1273 <para>The system's libc is itself thread-safe, 1274 </para> 1275 </listitem> 1276 <listitem> 1277 <para> 1278 The compiler in use reports a thread model other than 1279 'single'. This can be tested via output from <code>gcc 1280 -v</code>. Multi-thread capable versions of gcc output 1281 something like this: 1282 </para> 1283<programlisting> 1284%gcc -v 1285Using built-in specs. 1286... 1287Thread model: posix 1288gcc version 4.1.2 20070925 (Red Hat 4.1.2-33) 1289</programlisting> 1290 1291<para>Look for "Thread model" lines that aren't equal to "single."</para> 1292 </listitem> 1293 <listitem> 1294 <para> 1295 Requisite command-line flags are used for atomic operations 1296 and threading. Examples of this include <code>-pthread</code> 1297 and <code>-march=native</code>, although specifics vary 1298 depending on the host environment. See <ulink 1299 url="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine 1300 Dependent Options</ulink>. 1301 </para> 1302 </listitem> 1303 <listitem> 1304 <para> 1305 An implementation of atomicity.h functions 1306 exists for the architecture in question. See the internals documentation for more <link linkend="internals.thread_safety">details</link>. 1307 </para> 1308 </listitem> 1309 1310 </itemizedlist> 1311 <para>The user-code must guard against concurrent method calls which may 1312 access any particular library object's state. Typically, the 1313 application programmer may infer what object locks must be held 1314 based on the objects referenced in a method call. Without getting 1315 into great detail, here is an example which requires user-level 1316 locks: 1317 </para> 1318 <programlisting> 1319 library_class_a shared_object_a; 1320 1321 thread_main () { 1322 library_class_b *object_b = new library_class_b; 1323 shared_object_a.add_b (object_b); // must hold lock for shared_object_a 1324 shared_object_a.mutate (); // must hold lock for shared_object_a 1325 } 1326 1327 // Multiple copies of thread_main() are started in independent threads.</programlisting> 1328 <para>Under the assumption that object_a and object_b are never exposed to 1329 another thread, here is an example that should not require any 1330 user-level locks: 1331 </para> 1332 <programlisting> 1333 thread_main () { 1334 library_class_a object_a; 1335 library_class_b *object_b = new library_class_b; 1336 object_a.add_b (object_b); 1337 object_a.mutate (); 1338 } </programlisting> 1339 <para>All library objects are safe to use in a multithreaded program as 1340 long as each thread carefully locks out access by any other 1341 thread while it uses any object visible to another thread, i.e., 1342 treat library objects like any other shared resource. In general, 1343 this requirement includes both read and write access to objects; 1344 unless otherwise documented as safe, do not assume that two threads 1345 may access a shared standard library object at the same time. 1346 </para> 1347 1348 1349 </sect2> 1350 <sect2 id="manual.intro.using.concurrency.atomics" xreflabel="Atomics"> 1351 <title>Atomics</title> 1352 <para> 1353 </para> 1354 </sect2> 1355 1356 <sect2 id="manual.intro.using.concurrency.io" xreflabel="IO"> 1357 <title>IO</title> 1358 <para>This gets a bit tricky. Please read carefully, and bear with me. 1359 </para> 1360 1361 <sect3 id="concurrency.io.structure" xreflabel="Structure"> 1362 <title>Structure</title> 1363 <para>A wrapper 1364 type called <code>__basic_file</code> provides our abstraction layer 1365 for the <code>std::filebuf</code> classes. Nearly all decisions dealing 1366 with actual input and output must be made in <code>__basic_file</code>. 1367 </para> 1368 <para>A generic locking mechanism is somewhat in place at the filebuf layer, 1369 but is not used in the current code. Providing locking at any higher 1370 level is akin to providing locking within containers, and is not done 1371 for the same reasons (see the links above). 1372 </para> 1373 </sect3> 1374 1375 <sect3 id="concurrency.io.defaults" xreflabel="Defaults"> 1376 <title>Defaults</title> 1377 <para>The __basic_file type is simply a collection of small wrappers around 1378 the C stdio layer (again, see the link under Structure). We do no 1379 locking ourselves, but simply pass through to calls to <code>fopen</code>, 1380 <code>fwrite</code>, and so forth. 1381 </para> 1382 <para>So, for 3.0, the question of "is multithreading safe for I/O" 1383 must be answered with, "is your platform's C library threadsafe 1384 for I/O?" Some are by default, some are not; many offer multiple 1385 implementations of the C library with varying tradeoffs of threadsafety 1386 and efficiency. You, the programmer, are always required to take care 1387 with multiple threads. 1388 </para> 1389 <para>(As an example, the POSIX standard requires that C stdio FILE* 1390 operations are atomic. POSIX-conforming C libraries (e.g, on Solaris 1391 and GNU/Linux) have an internal mutex to serialize operations on 1392 FILE*s. However, you still need to not do stupid things like calling 1393 <code>fclose(fs)</code> in one thread followed by an access of 1394 <code>fs</code> in another.) 1395 </para> 1396 <para>So, if your platform's C library is threadsafe, then your 1397 <code>fstream</code> I/O operations will be threadsafe at the lowest 1398 level. For higher-level operations, such as manipulating the data 1399 contained in the stream formatting classes (e.g., setting up callbacks 1400 inside an <code>std::ofstream</code>), you need to guard such accesses 1401 like any other critical shared resource. 1402 </para> 1403 </sect3> 1404 1405 <sect3 id="concurrency.io.future" xreflabel="Future"> 1406 <title>Future</title> 1407 <para> A 1408 second choice may be available for I/O implementations: libio. This is 1409 disabled by default, and in fact will not currently work due to other 1410 issues. It will be revisited, however. 1411 </para> 1412 <para>The libio code is a subset of the guts of the GNU libc (glibc) I/O 1413 implementation. When libio is in use, the <code>__basic_file</code> 1414 type is basically derived from FILE. (The real situation is more 1415 complex than that... it's derived from an internal type used to 1416 implement FILE. See libio/libioP.h to see scary things done with 1417 vtbls.) The result is that there is no "layer" of C stdio 1418 to go through; the filebuf makes calls directly into the same 1419 functions used to implement <code>fread</code>, <code>fwrite</code>, 1420 and so forth, using internal data structures. (And when I say 1421 "makes calls directly," I mean the function is literally 1422 replaced by a jump into an internal function. Fast but frightening. 1423 *grin*) 1424 </para> 1425 <para>Also, the libio internal locks are used. This requires pulling in 1426 large chunks of glibc, such as a pthreads implementation, and is one 1427 of the issues preventing widespread use of libio as the libstdc++ 1428 cstdio implementation. 1429 </para> 1430 <para>But we plan to make this work, at least as an option if not a future 1431 default. Platforms running a copy of glibc with a recent-enough 1432 version will see calls from libstdc++ directly into the glibc already 1433 installed. For other platforms, a copy of the libio subsection will 1434 be built and included in libstdc++. 1435 </para> 1436 </sect3> 1437 1438 <sect3 id="concurrency.io.alt" xreflabel="Alt"> 1439 <title>Alternatives</title> 1440 <para>Don't forget that other cstdio implementations are possible. You could 1441 easily write one to perform your own forms of locking, to solve your 1442 "interesting" problems. 1443 </para> 1444 </sect3> 1445 1446 </sect2> 1447 1448 <sect2 id="manual.intro.using.concurrency.containers" xreflabel="Containers"> 1449 <title>Containers</title> 1450 1451 <para>This section discusses issues surrounding the design of 1452 multithreaded applications which use Standard C++ containers. 1453 All information in this section is current as of the gcc 3.0 1454 release and all later point releases. Although earlier gcc 1455 releases had a different approach to threading configuration and 1456 proper compilation, the basic code design rules presented here 1457 were similar. For information on all other aspects of 1458 multithreading as it relates to libstdc++, including details on 1459 the proper compilation of threaded code (and compatibility between 1460 threaded and non-threaded code), see Chapter 17. 1461 </para> 1462 <para>Two excellent pages to read when working with the Standard C++ 1463 containers and threads are 1464 <ulink url="http://www.sgi.com/tech/stl/thread_safety.html">SGI's 1465 http://www.sgi.com/tech/stl/thread_safety.html</ulink> and 1466 <ulink url="http://www.sgi.com/tech/stl/Allocators.html">SGI's 1467 http://www.sgi.com/tech/stl/Allocators.html</ulink>. 1468 </para> 1469 <para><emphasis>However, please ignore all discussions about the user-level 1470 configuration of the lock implementation inside the STL 1471 container-memory allocator on those pages. For the sake of this 1472 discussion, libstdc++ configures the SGI STL implementation, 1473 not you. This is quite different from how gcc pre-3.0 worked. 1474 In particular, past advice was for people using g++ to 1475 explicitly define _PTHREADS or other macros or port-specific 1476 compilation options on the command line to get a thread-safe 1477 STL. This is no longer required for any port and should no 1478 longer be done unless you really know what you are doing and 1479 assume all responsibility.</emphasis> 1480 </para> 1481 <para>Since the container implementation of libstdc++ uses the SGI 1482 code, we use the same definition of thread safety as SGI when 1483 discussing design. A key point that beginners may miss is the 1484 fourth major paragraph of the first page mentioned above 1485 (<emphasis>For most clients...</emphasis>), which points out that 1486 locking must nearly always be done outside the container, by 1487 client code (that'd be you, not us). There is a notable 1488 exceptions to this rule. Allocators called while a container or 1489 element is constructed uses an internal lock obtained and 1490 released solely within libstdc++ code (in fact, this is the 1491 reason STL requires any knowledge of the thread configuration). 1492 </para> 1493 <para>For implementing a container which does its own locking, it is 1494 trivial to provide a wrapper class which obtains the lock (as 1495 SGI suggests), performs the container operation, and then 1496 releases the lock. This could be templatized <emphasis>to a certain 1497 extent</emphasis>, on the underlying container and/or a locking 1498 mechanism. Trying to provide a catch-all general template 1499 solution would probably be more trouble than it's worth. 1500 </para> 1501 <para>The library implementation may be configured to use the 1502 high-speed caching memory allocator, which complicates thread 1503 safety issues. For all details about how to globally override 1504 this at application run-time 1505 see <link linkend="manual.intro.using.macros">here</link>. Also 1506 useful are details 1507 on <link linkend="std.util.memory.allocator">allocator</link> 1508 options and capabilities. 1509 </para> 1510 1511 </sect2> 1512</sect1> 1513 1514<!-- Section 0x : Exception policies, expectations, topics --> 1515<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 1516 parse="xml" href="using_exceptions.xml"> 1517</xi:include> 1518 1519<!-- Section 0x : Debug --> 1520<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" 1521 parse="xml" href="debug.xml"> 1522</xi:include> 1523 1524</chapter> 1525