libstdc++-v3/doc/xml/manual/extensions.xml

   1 <part xmlns="http://docbook.org/ns/docbook" version="5.0"
   2       xml:id="manual.ext" xreflabel="Extensions">
   3 <?dbhtml filename="extensions.html"?>
   4
   5 <info><title>
   6   Extensions
   7   <indexterm><primary>Extensions</primary></indexterm>
   8 </title>
   9   <keywordset>
  10     <keyword>ISO C++</keyword>
  11     <keyword>library</keyword>
  12   </keywordset>
  13 </info>
  14
  15
  16 <preface xml:id="manual.ext.preface"><info><title/></info>
  17 <?dbhtml filename="ext_preface.html"?>
  18 <para>
  19   Here we will make an attempt at describing the non-Standard
  20   extensions to the library.  Some of these are from older versions of
  21   standard library components, namely SGI's STL, and some of these are
  22   GNU's.
  23 </para>
  24 <para><emphasis>Before</emphasis> you leap in and use any of these
  25 extensions, be aware of two things:
  26 </para>
  27 <orderedlist inheritnum="ignore" continuation="restarts">
  28    <listitem>
  29      <para>
  30      Non-Standard means exactly that.
  31      </para>
  32      <para>
  33        The behavior, and the very
  34        existence, of these extensions may change with little or no
  35        warning.  (Ideally, the really good ones will appear in the next
  36        revision of C++.)  Also, other platforms, other compilers, other
  37        versions of g++ or libstdc++ may not recognize these names, or
  38        treat them differently, or...
  39      </para>
  40    </listitem>
  41    <listitem>
  42      <para>
  43        You should know how to access these headers properly.
  44      </para>
  45    </listitem>
  46 </orderedlist>
  47 </preface>
  48
  49 <!-- Chapter 01 : Compile Time Checks -->
  50 <chapter xml:id="manual.ext.compile_checks" xreflabel="Compile Time Checks"><info><title>Compile Time Checks</title></info>
  51 <?dbhtml filename="ext_compile_checks.html"?>
  52
  53   <para>
  54     Also known as concept checking.
  55   </para>
  56    <para>In 1999, SGI added <emphasis>concept checkers</emphasis> to their implementation
  57       of the STL:  code which checked the template parameters of
  58       instantiated pieces of the STL, in order to insure that the parameters
  59       being used met the requirements of the standard.  For example,
  60       the Standard requires that types passed as template parameters to
  61       <code>vector</code> be <quote>Assignable</quote> (which means what you think
  62       it means).  The checking was done during compilation, and none of
  63       the code was executed at runtime.
  64    </para>
  65    <para>Unfortunately, the size of the compiler files grew significantly
  66       as a result.  The checking code itself was cumbersome.  And bugs
  67       were found in it on more than one occasion.
  68    </para>
  69    <para>The primary author of the checking code, Jeremy Siek, had already
  70       started work on a replacement implementation.  The new code has been
  71       formally reviewed and accepted into
  72       <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the
  73       Boost libraries</link>, and we are pleased to incorporate it into the
  74       GNU C++ library.
  75    </para>
  76    <para>The new version imposes a much smaller space overhead on the generated
  77       object file.  The checks are also cleaner and easier to read and
  78       understand.
  79    </para>
  80    <para>They are off by default for all GCC 3.0 and all later versions.
  81       They can be enabled at configure time with
  82       <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
  83       You can enable them on a per-translation-unit basis with
  84       <link linkend="manual.intro.using.macros"><code>#define
  85       _GLIBCXX_CONCEPT_CHECKS</code></link> for GCC 3.4 and higher
  86       (or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
  87       3.1, 3.2 and 3.3).
  88    </para>
  89
  90    <para>Please note that the concept checks only validate the requirements
  91    of the old C++03 standard and reject some valid code that meets the relaxed
  92    requirements of C++11 and later standards.
  93    C++11 was expected to have first-class support for template parameter
  94    constraints based on concepts in the core language.
  95    This would have obviated the need for the library-simulated concept checking
  96    described above, but was not part of C++11.
  97    C++20 adds a different model of concepts, which is now used to constrain
  98    some new parts of the C++20 library, e.g. the
  99    <filename>&lt;ranges&gt;</filename> header and the new overloads in the
 100    <filename>&lt;algorithm&gt;</filename> header for working with ranges.
 101    The old library-simulated concept checks might be removed at a future date.
 102    </para>
 103
 104 </chapter>
 105
 106 <!-- Chapter 02 : Debug Mode -->
 107 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"
 108             href="debug_mode.xml">
 109 </xi:include>
 110
 111 <!-- Chapter 03 : Parallel Mode -->
 112 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"
 113             href="parallel_mode.xml">
 114 </xi:include>
 115
 116 <!-- XXX -->
 117 <!-- Allocators -->
 118 <!-- Chapter 05 : __mt_alloc -->
 119 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"
 120             href="mt_allocator.xml">
 121 </xi:include>
 122
 123 <!-- Chapter 06 : bitmap_allocator -->
 124 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"
 125             href="bitmap_allocator.xml">
 126 </xi:include>
 127
 128 <!-- Containers -->
 129 <!-- Chapter 07 : Policy-Based Data Structures -->
 130 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml"
 131             href="policy_data_structures.xml">
 132 </xi:include>
 133
 134 <!-- Chapter 08 : HP/SGI -->
 135 <chapter xml:id="manual.ext.containers" xreflabel="Containers">
 136   <info><title>HP/SGI Extensions</title></info>
 137 <?dbhtml filename="ext_containers.html"?>
 138
 139   <section xml:id="manual.ext.containers.sgi" xreflabel="SGI ext">
 140     <info><title>Backwards Compatibility</title></info>
 141
 142     <para>A few extensions and nods to backwards-compatibility have
 143     been made with containers.  Those dealing with older SGI-style
 144     allocators are dealt with elsewhere.  The remaining ones all deal
 145     with bits:
 146     </para>
 147     <para>The old pre-standard <code>bit_vector</code> class is
 148     present for backwards compatibility.  It is simply a typedef for
 149     the <code>vector&lt;bool&gt;</code> specialization.
 150     </para>
 151
 152 <para>The <code>bitset</code> class has a number of extensions, described in the
 153    rest of this item.  First, we'll mention that this implementation of
 154    <code>bitset&lt;N&gt;</code> is specialized for cases where N number of
 155    bits will fit into a single word of storage.  If your choice of N is
 156    within that range (&lt;=32 on i686-pc-linux-gnu, for example), then all
 157    of the operations will be faster.
 158 </para>
 159 <para>There are
 160    versions of single-bit test, set, reset, and flip member functions which
 161    do no range-checking.  If we call them member functions of an instantiation
 162    of <code>bitset&lt;N&gt;</code>, then their names and signatures are:
 163 </para>
 164    <programlisting>
 165    bitset&lt;N&gt;&amp;   _Unchecked_set   (size_t pos);
 166    bitset&lt;N&gt;&amp;   _Unchecked_set   (size_t pos, int val);
 167    bitset&lt;N&gt;&amp;   _Unchecked_reset (size_t pos);
 168    bitset&lt;N&gt;&amp;   _Unchecked_flip  (size_t pos);
 169    bool         _Unchecked_test  (size_t pos);
 170    </programlisting>
 171    <para>Note that these may in fact be removed in the future, although we have
 172    no present plans to do so (and there doesn't seem to be any immediate
 173    reason to).
 174 </para>
 175 <para>The member function <code>operator[]</code> on a const bitset returns
 176    a bool, and for a non-const bitset returns a <code>reference</code> (a
 177    nested type).  No range-checking is done on the index argument, in keeping
 178    with other containers' <code>operator[]</code> requirements.
 179 </para>
 180 <para>Finally, two additional searching functions have been added.  They return
 181    the index of the first "on" bit, and the index of the first
 182    "on" bit that is after <code>prev</code>, respectively:
 183 </para>
 184    <programlisting>
 185    size_t _Find_first() const;
 186    size_t _Find_next (size_t prev) const;</programlisting>
 187 <para>The same caveat given for the _Unchecked_* functions applies here also.
 188 </para>
 189   </section>
 190
 191
 192   <section xml:id="manual.ext.containers.deprecated_sgi" xreflabel="SGI ext dep"><info><title>Deprecated</title></info>
 193     <?dbhtml filename="ext_sgi.html"?>
 194
 195
 196    <para>
 197      The SGI hashing classes <classname>hash_set</classname> and
 198      <classname>hash_set</classname> have been deprecated by the
 199      unordered_set, unordered_multiset, unordered_map,
 200      unordered_multimap containers in TR1 and C++11, and
 201      may be removed in future releases.
 202    </para>
 203
 204    <para>The SGI headers</para>
 205    <programlisting>
 206      &lt;hash_map&gt;
 207      &lt;hash_set&gt;
 208      &lt;rope&gt;
 209      &lt;slist&gt;
 210      &lt;rb_tree&gt;
 211    </programlisting>
 212    <para>are all here;
 213       <filename class="headerfile">&lt;backwards/hash_map&gt;</filename> and
 214       <filename class="headerfile">&lt;backwards/hash_set&gt;</filename>
 215       are deprecated but available as backwards-compatible extensions,
 216       as discussed further below.
 217       <filename class="headerfile">&lt;ext/rope&gt;</filename> is the SGI
 218       specialization for large strings ("rope," "large strings," get it? Love
 219       that geeky humor.)
 220       <filename class="headerfile">&lt;ext/slist&gt;</filename> (superseded in
 221       C++11 by <filename class="headerfile">&lt;forward_list&gt;</filename>)
 222       is a singly-linked list, for when the doubly-linked <code>list&lt;&gt;</code>
 223       is too much space overhead, and
 224       <filename class="headerfile">&lt;ext/rb_tree&gt;</filename> exposes the
 225       red-black tree classes used in the implementation of the standard maps
 226       and sets.
 227    </para>
 228    <para>Each of the associative containers map, multimap, set, and multiset
 229       have a counterpart which uses a
 230       <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/HashFunction.html">hashing
 231       function</link> to do the arranging, instead of a strict weak ordering
 232       function.  The classes take as one of their template parameters a
 233       function object that will return the hash value; by default, an
 234       instantiation of
 235       <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/hash.html">hash</link>.
 236       You should specialize this functor for your class, or define your own,
 237       before trying to use one of the hashing classes.
 238    </para>
 239    <para>The hashing classes support all the usual associative container
 240       functions, as well as some extra constructors specifying the number
 241       of buckets, etc.
 242    </para>
 243    <para>Why would you want to use a hashing class instead of the
 244       <quote>normal</quote>implementations?  Matt Austern writes:
 245    </para>
 246    <blockquote>
 247      <para>
 248        <emphasis>[W]ith a well chosen hash function, hash tables
 249        generally provide much better average-case performance than
 250        binary search trees, and much worse worst-case performance.  So
 251        if your implementation has hash_map, if you don't mind using
 252        nonstandard components, and if you aren't scared about the
 253        possibility of pathological cases, you'll probably get better
 254        performance from hash_map.
 255      </emphasis>
 256      </para>
 257    </blockquote>
 258
 259    <para>
 260       The deprecated hash tables are superseded by the standard unordered
 261       associative containers defined in the ISO C++ 2011 standard in the
 262       headers <filename class="headerfile">&lt;unordered_map&gt;</filename>
 263       and <filename class="headerfile">&lt;unordered_set&gt;</filename>.
 264    </para>
 265
 266   </section>
 267 </chapter>
 268
 269 <!-- Chapter 09 : Utilities -->
 270 <chapter xml:id="manual.ext.util" xreflabel="Utilities"><info><title>Utilities</title></info>
 271 <?dbhtml filename="ext_utilities.html"?>
 272
 273   <para>
 274     The <filename class="headerfile">&lt;functional&gt;</filename> header
 275     contains many additional functors
 276     and helper functions, extending section 20.3.  They are
 277     implemented in the file stl_function.h:
 278   </para>
 279   <itemizedlist>
 280   <listitem>
 281   <para><code>identity_element</code> for addition and multiplication.
 282   </para>
 283   </listitem>
 284   <listitem>
 285     <para>The functor <code>identity</code>, whose <code>operator()</code>
 286       returns the argument unchanged.
 287   </para>
 288   </listitem>
 289   <listitem>
 290     <para>Composition functors <code>unary_function</code> and
 291       <code>binary_function</code>, and their helpers <code>compose1</code>
 292       and <code>compose2</code>.
 293     </para>
 294   </listitem>
 295   <listitem>
 296   <para><code>select1st</code> and <code>select2nd</code>, to strip pairs.
 297   </para>
 298   </listitem>
 299   <listitem><para><code>project1st</code> and <code>project2nd</code>. </para></listitem>
 300   <listitem><para>A set of functors/functions which always return the same result.  They
 301       are <code>constant_void_fun</code>, <code>constant_binary_fun</code>,
 302       <code>constant_unary_fun</code>, <code>constant0</code>,
 303       <code>constant1</code>, and <code>constant2</code>. </para></listitem>
 304   <listitem><para>The class <code>subtractive_rng</code>. </para></listitem>
 305   <listitem><para>mem_fun adaptor helpers <code>mem_fun1</code> and
 306       <code>mem_fun1_ref</code> are provided for backwards compatibility. </para></listitem>
 307 </itemizedlist>
 308 <para>
 309   20.4.1 can use several different allocators; they are described on the
 310    main extensions page.
 311 </para>
 312 <para>
 313   20.4.3 is extended with a special version of
 314   <code>get_temporary_buffer</code> taking a second argument.  The
 315   argument is a pointer, which is ignored, but can be used to specify
 316   the template type (instead of using explicit function template
 317   arguments like the standard version does).  That is, in addition to
 318 </para>
 319 <programlisting>
 320 get_temporary_buffer&lt;int&gt;(5);
 321 </programlisting>
 322
 323 <para>
 324 you can also use
 325 </para>
 326
 327 <programlisting>
 328 get_temporary_buffer(5, (int*)0);
 329 </programlisting>
 330 <para>
 331   A class <code>temporary_buffer</code> is given in stl_tempbuf.h.
 332 </para>
 333 <para>
 334   The specialized algorithms of section 20.4.4 are extended with
 335   <code>uninitialized_copy_n</code>.
 336 </para>
 337
 338 </chapter>
 339
 340 <!-- Chapter 10 : Algorithms -->
 341 <chapter xml:id="manual.ext.algorithms" xreflabel="Algorithms"><info><title>Algorithms</title></info>
 342 <?dbhtml filename="ext_algorithms.html"?>
 343
 344 <para>25.1.6 (count, count_if) is extended with two more versions of count
 345    and count_if.  The standard versions return their results.  The
 346    additional signatures return void, but take a final parameter by
 347    reference to which they assign their results, e.g.,
 348 </para>
 349    <programlisting>
 350    void count (first, last, value, n);</programlisting>
 351 <para>25.2 (mutating algorithms) is extended with two families of signatures,
 352    random_sample and random_sample_n.
 353 </para>
 354 <para>25.2.1 (copy) is extended with
 355 </para>
 356    <programlisting>
 357    copy_n (_InputIter first, _Size count, _OutputIter result);</programlisting>
 358 <para>which copies the first 'count' elements at 'first' into 'result'.
 359 </para>
 360 <para>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
 361    predicates.  Look in the doxygen-generated pages for notes on these.
 362 </para>
 363    <itemizedlist>
 364     <listitem><para><code>is_heap</code> tests whether or not a range is a heap.</para></listitem>
 365     <listitem><para><code>is_sorted</code> tests whether or not a range is sorted in
 366         nondescending order.</para></listitem>
 367    </itemizedlist>
 368 <para>25.3.8 (lexicographical_compare) is extended with
 369 </para>
 370    <programlisting>
 371    lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
 372                                  _InputIter2 first2, _InputIter2 last2)</programlisting>
 373 <para>which does... what?
 374 </para>
 375
 376 </chapter>
 377
 378 <!-- Chapter 11 : Numerics -->
 379 <chapter xml:id="manual.ext.numerics" xreflabel="Numerics"><info><title>Numerics</title></info>
 380 <?dbhtml filename="ext_numerics.html"?>
 381
 382 <para>26.4, the generalized numeric operations such as <code>accumulate</code>,
 383    are extended with the following functions:
 384 </para>
 385    <programlisting>
 386    power (x, n);
 387    power (x, n, monoid_operation);</programlisting>
 388 <para>Returns, in FORTRAN syntax, "<code>x ** n</code>" where
 389    <code>n &gt;= 0</code>.  In the
 390    case of <code>n == 0</code>, returns the identity element for the
 391    monoid operation.  The two-argument signature uses multiplication (for
 392    a true "power" implementation), but addition is supported as well.
 393    The operation functor must be associative.
 394 </para>
 395 <para>The <code>iota</code> function wins the award for Extension With the
 396    Coolest Name (the name comes from Ken Iverson's APL language.)  As
 397    described in the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://web.archive.org/web/20171225062613/http://www.sgi.com/tech/stl/iota.html">SGI
 398    documentation</link>, it "assigns sequentially increasing values to a range.
 399    That is, it assigns <code>value</code> to <code>*first</code>,
 400    <code>value + 1</code> to<code> *(first + 1)</code> and so on."
 401 </para>
 402    <programlisting>
 403    void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting>
 404 <para>The <code>iota</code> function is included in the ISO C++ 2011 standard.
 405 </para>
 406 </chapter>
 407
 408 <!-- Chapter 12 : Iterators -->
 409 <chapter xml:id="manual.ext.iterators" xreflabel="Iterators"><info><title>Iterators</title></info>
 410 <?dbhtml filename="ext_iterators.html"?>
 411
 412 <para>24.3.2 describes <code>struct iterator</code>, which didn't exist in the
 413    original HP STL implementation (the language wasn't rich enough at the
 414    time).  For backwards compatibility, base classes are provided which
 415    declare the same nested typedefs:
 416 </para>
 417    <itemizedlist>
 418     <listitem><para>input_iterator</para></listitem>
 419     <listitem><para>output_iterator</para></listitem>
 420     <listitem><para>forward_iterator</para></listitem>
 421     <listitem><para>bidirectional_iterator</para></listitem>
 422     <listitem><para>random_access_iterator</para></listitem>
 423    </itemizedlist>
 424 <para>24.3.4 describes iterator operation <code>distance</code>, which takes
 425    two iterators and returns a result.  It is extended by another signature
 426    which takes two iterators and a reference to a result.  The result is
 427    modified, and the function returns nothing.
 428 </para>
 429
 430 </chapter>
 431
 432 <!-- Chapter 13 : IO -->
 433 <chapter xml:id="manual.ext.io" xreflabel="IO"><info><title>Input and Output</title></info>
 434 <?dbhtml filename="ext_io.html"?>
 435
 436
 437   <para>
 438     Extensions allowing <code>filebuf</code>s to be constructed from
 439     "C" types like  FILE*s and file descriptors.
 440   </para>
 441
 442   <section xml:id="manual.ext.io.filebuf_derived" xreflabel="Derived filebufs"><info><title>Derived filebufs</title></info>
 443
 444
 445    <para>The v2 library included non-standard extensions to construct
 446       <code>std::filebuf</code>s from C stdio types such as
 447       <code>FILE*</code>s and POSIX file descriptors.
 448       Today the recommended way to use stdio types with libstdc++
 449       IOStreams is via the <code>stdio_filebuf</code> class (see below),
 450       but earlier releases provided slightly different mechanisms.
 451    </para>
 452    <itemizedlist>
 453      <listitem><para>3.0.x <code>filebuf</code>s have another ctor with this signature:
 454         <code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);
 455         </code>
 456          This comes in very handy in a number of places, such as
 457          attaching Unix sockets, pipes, and anything else which uses file
 458          descriptors, into the IOStream buffering classes.  The three
 459          arguments are as follows:
 460          <itemizedlist>
 461           <listitem><para><code>__c_file_type*      F   </code>
 462               // the __c_file_type typedef usually boils down to stdio's FILE
 463           </para></listitem>
 464           <listitem><para><code>ios_base::openmode  M   </code>
 465               // same as all the other uses of openmode
 466           </para></listitem>
 467           <listitem><para><code>int_type            B   </code>
 468               // buffer size, defaults to BUFSIZ if not specified
 469           </para></listitem>
 470          </itemizedlist>
 471          For those wanting to use file descriptors instead of FILE*'s, I
 472          invite you to contemplate the mysteries of C's <code>fdopen()</code>.
 473      </para></listitem>
 474      <listitem><para>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring
 475          back an old extension:  the <code>fd()</code> member function.  The
 476          integer returned from this function can be used for whatever file
 477          descriptors can be used for on your platform.  Naturally, the
 478          library cannot track what you do on your own with a file descriptor,
 479          so if you perform any I/O directly, don't expect the library to be
 480          aware of it.
 481      </para></listitem>
 482      <listitem><para>Beginning with 3.1, the extra
 483          <classname>basic_filebuf</classname> constructor and
 484          the <code>fd()</code> function were removed from the standard
 485          filebuf.  Instead,
 486          <filename class="headerfile">&lt;ext/stdio_filebuf.h&gt;</filename>
 487          contains a derived class template called
 488          <classname>__gnu_cxx::stdio_filebuf</classname>.
 489          This class can be constructed from a C <code>FILE*</code> or a file
 490          descriptor, and provides the <code>fd()</code> function.
 491      </para></listitem>
 492    </itemizedlist>
 493
 494   </section>
 495 </chapter>
 496
 497 <!-- Chapter 14 : Demangling -->
 498 <chapter xml:id="manual.ext.demangle" xreflabel="Demangling"><info><title>Demangling</title></info>
 499 <?dbhtml filename="ext_demangling.html"?>
 500
 501   <para>
 502     Transforming C++ ABI identifiers (like RTTI symbols) into the
 503     original C++ source identifiers is called
 504     <quote>demangling.</quote>
 505   </para>
 506   <para>
 507     If you have read the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="https://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">source
 508     documentation for <code>namespace abi</code></link> then you are
 509     aware of the cross-vendor C++ ABI in use by GCC.  One of the
 510     exposed functions is used for demangling,
 511     <code>abi::__cxa_demangle</code>.
 512   </para>
 513   <para>
 514     In programs like <command>c++filt</command>, the linker, and other tools
 515     have the ability to decode C++ ABI names, and now so can you.
 516   </para>
 517   <para>
 518     (The function itself might use different demanglers, but that's the
 519     whole point of abstract interfaces.  If we change the implementation,
 520     you won't notice.)
 521   </para>
 522   <para>
 523     Probably the only time you'll be interested in demangling at runtime
 524     is when you're seeing <code>typeid</code> strings in RTTI.  For example:
 525   </para>
 526    <programlisting>
 527 #include &lt;iostream&gt;
 528 #include &lt;cstdlib&gt;
 529 #include &lt;cxxabi.h&gt;
 530
 531 struct empty { };
 532
 533 template &lt;typename T, int N&gt;
 534   struct bar { };
 535
 536 int main()
 537 {
 538   int     status;
 539   char   *realname;
 540
 541   // typeid
 542   bar&lt;empty,17&gt;          u;
 543   const std::type_info  &amp;ti = typeid(u);
 544
 545   realname = abi::__cxa_demangle(ti.name(), NULL, NULL, &amp;status);
 546   std::cout &lt;&lt; ti.name() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
 547   std::free(realname);
 548 }
 549    </programlisting>
 550    <para>
 551      This prints
 552    </para>
 553
 554    <screen>
 555    <computeroutput>
 556       3barI5emptyLi17EE       =&gt; bar&lt;empty, 17&gt;       : 0
 557    </computeroutput>
 558    </screen>
 559
 560    <para>
 561      The demangler interface is described in the source documentation
 562      linked to above.  It is actually written in C, so you don't need to
 563      be writing C++ in order to demangle C++.  (That also means we have to
 564      use crummy memory management facilities, so don't forget to
 565      <code>free()</code> the returned char array.)
 566    </para>
 567 </chapter>
 568
 569 <!-- Chapter 15 : Concurrency -->
 570 <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="concurrency_extensions.xml">
 571 </xi:include>
 572
 573 </part>