summaryrefslogtreecommitdiff
path: root/libstdc++-v3/doc/xml/manual/extensions.xml
blob: b93c61f1be266023bdab5cfa0bb540640f9e10fc (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
<part xmlns="http://docbook.org/ns/docbook" version="5.0" 
      xml:id="manual.ext" xreflabel="Extensions">
<?dbhtml filename="extensions.html"?>

<info><title>
  Extensions
  <indexterm><primary>Extensions</primary></indexterm>
</title>
  <keywordset>
    <keyword>
      ISO C++
    </keyword>
    <keyword>
      library
    </keyword>
  </keywordset>
</info>



<preface><info><title/></info>
  
<para>
  Here we will make an attempt at describing the non-Standard extensions to
  the library.  Some of these are from SGI's STL, some of these are GNU's,
  and some just seemed to appear on the doorstep.
</para>
<para><emphasis>Before</emphasis> you leap in and use any of these
extensions, be aware of two things:
</para>
<orderedlist inheritnum="ignore" continuation="restarts">
   <listitem>
     <para>
     Non-Standard means exactly that.
     </para>
     <para>
       The behavior, and the very
       existence, of these extensions may change with little or no
       warning.  (Ideally, the really good ones will appear in the next
       revision of C++.)  Also, other platforms, other compilers, other
       versions of g++ or libstdc++ may not recognize these names, or
       treat them differently, or...
     </para>
   </listitem>
   <listitem>
     <para>
       You should know how to access these headers properly.
     </para>
   </listitem>
</orderedlist>
</preface>

<!-- Chapter 01 : Compile Time Checks -->
<chapter xml:id="manual.ext.compile_checks" xreflabel="Compile Time Checks"><info><title>Compile Time Checks</title></info>
<?dbhtml filename="ext_compile_checks.html"?>
  
  <para>
    Also known as concept checking.
  </para>
   <para>In 1999, SGI added <emphasis>concept checkers</emphasis> to their implementation
      of the STL:  code which checked the template parameters of
      instantiated pieces of the STL, in order to insure that the parameters
      being used met the requirements of the standard.  For example,
      the Standard requires that types passed as template parameters to
      <code>vector</code> be <quote>Assignable</quote> (which means what you think
      it means).  The checking was done during compilation, and none of
      the code was executed at runtime.
   </para>
   <para>Unfortunately, the size of the compiler files grew significantly
      as a result.  The checking code itself was cumbersome.  And bugs
      were found in it on more than one occasion.
   </para>
   <para>The primary author of the checking code, Jeremy Siek, had already
      started work on a replacement implementation.  The new code has been
      formally reviewed and accepted into
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.boost.org/libs/concept_check/concept_check.htm">the
      Boost libraries</link>, and we are pleased to incorporate it into the
      GNU C++ library.
   </para>
   <para>The new version imposes a much smaller space overhead on the generated
      object file.  The checks are also cleaner and easier to read and
      understand.
   </para>
   <para>They are off by default for all versions of GCC from 3.0 to 3.4 (the
      latest release at the time of writing).
      They can be enabled at configure time with
      <link linkend="manual.intro.setup.configure"><literal>--enable-concept-checks</literal></link>.
      You can enable them on a per-translation-unit basis with
      <code>#define _GLIBCXX_CONCEPT_CHECKS</code> for GCC 3.4 and higher
      (or with <code>#define _GLIBCPP_CONCEPT_CHECKS</code> for versions
      3.1, 3.2 and 3.3).
   </para>

   <para>Please note that the upcoming C++ standard has first-class
   support for template parameter constraints based on concepts in the core
   language. This will obviate the need for the library-simulated concept
   checking described above.
   </para>

</chapter>

<!-- Chapter 02 : Debug Mode -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="debug_mode.xml">
</xi:include>

<!-- Chapter 03 : Parallel Mode -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="parallel_mode.xml">
</xi:include>

<!-- Chapter 04 : Profile Mode -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="profile_mode.xml">
</xi:include>


<!-- Chapter 05 : Allocators -->
<chapter xml:id="manual.ext.allocator" xreflabel="Allocators"><info><title>Allocators</title></info>
<?dbhtml filename="ext_allocators.html"?>
  

  <!-- Section 01 : __mt_alloc -->
  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="mt_allocator.xml">
  </xi:include>

  <!-- Section 02 : bitmap_allocator -->
  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="bitmap_allocator.xml">
  </xi:include>

</chapter>

<!-- Chapter 06 : Containers -->
<chapter xml:id="manual.ext.containers" xreflabel="Containers"><info><title>Containers</title></info>
<?dbhtml filename="ext_containers.html"?>
  
  <para>
  </para>
  <section xml:id="manual.ext.containers.pbds" xreflabel="Policy Based Data Structures"><info><title>Policy Based Data Structures</title></info>
    
    <para>
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/ext/pb_ds/index.html">More details here</link>.
    </para>
  </section>

  <section xml:id="manual.ext.containers.sgi" xreflabel="SGI ext"><info><title>HP/SGI</title></info>
    
    <para>
    </para>

<para>A few extensions and nods to backwards-compatibility have been made with
   containers.  Those dealing with older SGI-style allocators are dealt with
   elsewhere.  The remaining ones all deal with bits:
</para>
<para>The old pre-standard <code>bit_vector</code> class is present for
   backwards compatibility.  It is simply a typedef for the
   <code>vector&lt;bool&gt;</code> specialization.
</para>
<para>The <code>bitset</code> class has a number of extensions, described in the
   rest of this item.  First, we'll mention that this implementation of
   <code>bitset&lt;N&gt;</code> is specialized for cases where N number of
   bits will fit into a single word of storage.  If your choice of N is
   within that range (&lt;=32 on i686-pc-linux-gnu, for example), then all
   of the operations will be faster.
</para>
<para>There are
   versions of single-bit test, set, reset, and flip member functions which
   do no range-checking.  If we call them member functions of an instantiation
   of "bitset&lt;N&gt;," then their names and signatures are:
</para>
   <programlisting>
   bitset&lt;N&gt;&amp;   _Unchecked_set   (size_t pos);
   bitset&lt;N&gt;&amp;   _Unchecked_set   (size_t pos, int val);
   bitset&lt;N&gt;&amp;   _Unchecked_reset (size_t pos);
   bitset&lt;N&gt;&amp;   _Unchecked_flip  (size_t pos);
   bool         _Unchecked_test  (size_t pos);
   </programlisting>
   <para>Note that these may in fact be removed in the future, although we have
   no present plans to do so (and there doesn't seem to be any immediate
   reason to).
</para>
<para>The semantics of member function <code>operator[]</code> are not specified
   in the C++ standard.  A long-standing defect report calls for sensible
   obvious semantics, which are already implemented here:  <code>op[]</code>
   on a const bitset returns a bool, and for a non-const bitset returns a
   <code>reference</code> (a nested type).  However, this implementation does
   no range-checking on the index argument, which is in keeping with other
   containers' <code>op[]</code> requirements.  The defect report's proposed
   resolution calls for range-checking to be done.  We'll just wait and see...
</para>
<para>Finally, two additional searching functions have been added.  They return
   the index of the first "on" bit, and the index of the first
   "on" bit that is after <code>prev</code>, respectively:
</para>
   <programlisting>
   size_t _Find_first() const;
   size_t _Find_next (size_t prev) const;</programlisting>
<para>The same caveat given for the _Unchecked_* functions applies here also.
</para>
  </section>


  <section xml:id="manual.ext.containers.deprecated_sgi" xreflabel="SGI ext dep"><info><title>Deprecated HP/SGI</title></info>
    

   <para>
     The SGI hashing classes <classname>hash_set</classname> and
     <classname>hash_set</classname> have been deprecated by the
     unordered_set, unordered_multiset, unordered_map,
     unordered_multimap containers in TR1 and the upcoming C++0x, and
     may be removed in future releases.
   </para>

   <para>The SGI headers</para>
   <programlisting>
     &lt;hash_map&gt;
     &lt;hash_set&gt;
     &lt;rope&gt;
     &lt;slist&gt;
     &lt;rb_tree&gt;
   </programlisting>
   <para>are all here;
      <code>&lt;hash_map&gt;</code> and <code>&lt;hash_set&gt;</code>
      are deprecated but available as backwards-compatible extensions,
      as discussed further below.  <code>&lt;rope&gt;</code> is the
      SGI specialization for large strings ("rope,"
      "large strings," get it? Love that geeky humor.)
      <code>&lt;slist&gt;</code> is a singly-linked list, for when the
      doubly-linked <code>list&lt;&gt;</code> is too much space
      overhead, and <code>&lt;rb_tree&gt;</code> exposes the red-black
      tree classes used in the implementation of the standard maps and
      sets.
   </para>
   <para>Each of the associative containers map, multimap, set, and multiset
      have a counterpart which uses a
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/HashFunction.html">hashing
      function</link> to do the arranging, instead of a strict weak ordering
      function.  The classes take as one of their template parameters a
      function object that will return the hash value; by default, an
      instantiation of
      <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://www.sgi.com/tech/stl/hash.html">hash</link>.
      You should specialize this functor for your class, or define your own,
      before trying to use one of the hashing classes.
   </para>
   <para>The hashing classes support all the usual associative container
      functions, as well as some extra constructors specifying the number
      of buckets, etc.
   </para>
   <para>Why would you want to use a hashing class instead of the
      <quote>normal</quote>implementations?  Matt Austern writes:
   </para>
   <blockquote>
     <para>
       <emphasis>[W]ith a well chosen hash function, hash tables
       generally provide much better average-case performance than
       binary search trees, and much worse worst-case performance.  So
       if your implementation has hash_map, if you don't mind using
       nonstandard components, and if you aren't scared about the
       possibility of pathological cases, you'll probably get better
       performance from hash_map.
     </emphasis>
     </para>
   </blockquote>

  </section>
</chapter>

<!-- Chapter 07 : Utilities -->
<chapter xml:id="manual.ext.util" xreflabel="Utilities"><info><title>Utilities</title></info>
<?dbhtml filename="ext_utilities.html"?>
  
  <para>
    The &lt;functional&gt; header contains many additional functors
    and helper functions, extending section 20.3.  They are
    implemented in the file stl_function.h:
  </para>
  <itemizedlist>
  <listitem>
  <para><code>identity_element</code> for addition and multiplication. *
  </para>
  </listitem>
  <listitem>
    <para>The functor <code>identity</code>, whose <code>operator()</code>
      returns the argument unchanged. *
  </para>
  </listitem>
  <listitem>
    <para>Composition functors <code>unary_function</code> and
      <code>binary_function</code>, and their helpers <code>compose1</code>
      and <code>compose2</code>. *
    </para>
  </listitem>
  <listitem>
  <para><code>select1st</code> and <code>select2nd</code>, to strip pairs. *
  </para>
  </listitem>
  <listitem><para><code>project1st</code> and <code>project2nd</code>. * </para></listitem>
  <listitem><para>A set of functors/functions which always return the same result.  They
      are <code>constant_void_fun</code>, <code>constant_binary_fun</code>,
      <code>constant_unary_fun</code>, <code>constant0</code>,
      <code>constant1</code>, and <code>constant2</code>. * </para></listitem>
  <listitem><para>The class <code>subtractive_rng</code>. * </para></listitem>
  <listitem><para>mem_fun adaptor helpers <code>mem_fun1</code> and
      <code>mem_fun1_ref</code> are provided for backwards compatibility. </para></listitem>
</itemizedlist>
<para>
  20.4.1 can use several different allocators; they are described on the
   main extensions page.
</para>
<para>
  20.4.3 is extended with a special version of
  <code>get_temporary_buffer</code> taking a second argument.  The
  argument is a pointer, which is ignored, but can be used to specify
  the template type (instead of using explicit function template
  arguments like the standard version does).  That is, in addition to
</para>
<programlisting>
get_temporary_buffer&lt;int&gt;(5);
</programlisting>

<para>
you can also use
</para>

<programlisting>
get_temporary_buffer(5, (int*)0);
</programlisting>
<para>
  A class <code>temporary_buffer</code> is given in stl_tempbuf.h. *
</para>
<para>
  The specialized algorithms of section 20.4.4 are extended with
  <code>uninitialized_copy_n</code>. *
</para>

</chapter>

<!-- Chapter 08 : Algorithms -->
<chapter xml:id="manual.ext.algorithms" xreflabel="Algorithms"><info><title>Algorithms</title></info>
<?dbhtml filename="ext_algorithms.html"?>
  
<para>25.1.6 (count, count_if) is extended with two more versions of count
   and count_if.  The standard versions return their results.  The
   additional signatures return void, but take a final parameter by
   reference to which they assign their results, e.g.,
</para>
   <programlisting>
   void count (first, last, value, n);</programlisting>
<para>25.2 (mutating algorithms) is extended with two families of signatures,
   random_sample and random_sample_n.
</para>
<para>25.2.1 (copy) is extended with
</para>
   <programlisting>
   copy_n (_InputIter first, _Size count, _OutputIter result);</programlisting>
<para>which copies the first 'count' elements at 'first' into 'result'.
</para>
<para>25.3 (sorting 'n' heaps 'n' stuff) is extended with some helper
   predicates.  Look in the doxygen-generated pages for notes on these.
</para>
   <itemizedlist>
    <listitem><para><code>is_heap</code> tests whether or not a range is a heap.</para></listitem>
    <listitem><para><code>is_sorted</code> tests whether or not a range is sorted in
	nondescending order.</para></listitem>
   </itemizedlist>
<para>25.3.8 (lexicographical_compare) is extended with
</para>
   <programlisting>
   lexicographical_compare_3way(_InputIter1 first1, _InputIter1 last1,
				 _InputIter2 first2, _InputIter2 last2)</programlisting>
<para>which does... what?
</para>

</chapter>

<!-- Chapter 09 : Numerics -->
<chapter xml:id="manual.ext.numerics" xreflabel="Numerics"><info><title>Numerics</title></info>
<?dbhtml filename="ext_numerics.html"?>
  
<para>26.4, the generalized numeric operations such as accumulate, are extended
   with the following functions:
</para>
   <programlisting>
   power (x, n);
   power (x, n, moniod_operation);</programlisting>
<para>Returns, in FORTRAN syntax, "x ** n" where n&gt;=0.  In the
   case of n == 0, returns the identity element for the
   monoid operation.  The two-argument signature uses multiplication (for
   a true "power" implementation), but addition is supported as well.
   The operation functor must be associative.
</para>
<para>The <code>iota</code> function wins the award for Extension With the
   Coolest Name.  It "assigns sequentially increasing values to a range.
   That is, it assigns value to *first, value + 1 to *(first + 1) and so
   on."  Quoted from SGI documentation.
</para>
   <programlisting>
   void iota(_ForwardIter first, _ForwardIter last, _Tp value);</programlisting>
</chapter>

<!-- Chapter 10 : Iterators -->
<chapter xml:id="manual.ext.iterators" xreflabel="Iterators"><info><title>Iterators</title></info>
<?dbhtml filename="ext_iterators.html"?>
  
<para>24.3.2 describes <code>struct iterator</code>, which didn't exist in the
   original HP STL implementation (the language wasn't rich enough at the
   time).  For backwards compatibility, base classes are provided which
   declare the same nested typedefs:
</para>
   <itemizedlist>
    <listitem><para>input_iterator</para></listitem>
    <listitem><para>output_iterator</para></listitem>
    <listitem><para>forward_iterator</para></listitem>
    <listitem><para>bidirectional_iterator</para></listitem>
    <listitem><para>random_access_iterator</para></listitem>
   </itemizedlist>
<para>24.3.4 describes iterator operation <code>distance</code>, which takes
   two iterators and returns a result.  It is extended by another signature
   which takes two iterators and a reference to a result.  The result is
   modified, and the function returns nothing.
</para>

</chapter>

<!-- Chapter 11 : IO -->
<chapter xml:id="manual.ext.io" xreflabel="IO"><info><title>Input and Output</title></info>
<?dbhtml filename="ext_io.html"?>
  

  <para>
    Extensions allowing <code>filebuf</code>s to be constructed from
    "C" types like  FILE*s and file descriptors.
  </para>

  <section xml:id="manual.ext.io.filebuf_derived" xreflabel="Derived filebufs"><info><title>Derived filebufs</title></info>
    

   <para>The v2 library included non-standard extensions to construct
      <code>std::filebuf</code>s from C stdio types such as
      <code>FILE*</code>s and POSIX file descriptors.
      Today the recommended way to use stdio types with libstdc++
      IOStreams is via the <code>stdio_filebuf</code> class (see below),
      but earlier releases provided slightly different mechanisms.
   </para>
   <itemizedlist>
     <listitem><para>3.0.x <code>filebuf</code>s have another ctor with this signature:
	<code>basic_filebuf(__c_file_type*, ios_base::openmode, int_type);
	</code>
	 This comes in very handy in a number of places, such as
	 attaching Unix sockets, pipes, and anything else which uses file
	 descriptors, into the IOStream buffering classes.  The three
	 arguments are as follows:
	 <itemizedlist>
	  <listitem><para><code>__c_file_type*      F   </code>
	      // the __c_file_type typedef usually boils down to stdio's FILE
	  </para></listitem>
	  <listitem><para><code>ios_base::openmode  M   </code>
	      // same as all the other uses of openmode
	  </para></listitem>
	  <listitem><para><code>int_type            B   </code>
	      // buffer size, defaults to BUFSIZ if not specified
	  </para></listitem>
	 </itemizedlist>
	 For those wanting to use file descriptors instead of FILE*'s, I
	 invite you to contemplate the mysteries of C's <code>fdopen()</code>.
     </para></listitem>
     <listitem><para>In library snapshot 3.0.95 and later, <code>filebuf</code>s bring
	 back an old extension:  the <code>fd()</code> member function.  The
	 integer returned from this function can be used for whatever file
	 descriptors can be used for on your platform.  Naturally, the
	 library cannot track what you do on your own with a file descriptor,
	 so if you perform any I/O directly, don't expect the library to be
	 aware of it.
     </para></listitem>
     <listitem><para>Beginning with 3.1, the extra <code>filebuf</code> constructor and
	 the <code>fd()</code> function were removed from the standard
	 filebuf.  Instead, <code>&lt;ext/stdio_filebuf.h&gt;</code> contains
	 a derived class called
	 <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a00074.html"><code>__gnu_cxx::stdio_filebuf</code></link>.
	 This class can be constructed from a C <code>FILE*</code> or a file
	 descriptor, and provides the <code>fd()</code> function.
     </para></listitem>
   </itemizedlist>
   <para>If you want to access a <code>filebuf</code>'s file descriptor to
      implement file locking (e.g. using the <code>fcntl()</code> system
      call) then you might be interested in Henry Suter's RWLock class.
      <!-- url="http://suter.home.cern.ch/suter/RWLock.html" -->
   </para>

    <para>
    </para>
  </section>
</chapter>

<!-- Chapter 12 : Demangling -->
<chapter xml:id="manual.ext.demangle" xreflabel="Demangling"><info><title>Demangling</title></info>
<?dbhtml filename="ext_demangling.html"?>
  
  <para>
    Transforming C++ ABI identifiers (like RTTI symbols) into the
    original C++ source identifiers is called
    <quote>demangling.</quote>
  </para>
  <para>
    If you have read the <link xmlns:xlink="http://www.w3.org/1999/xlink" xlink:href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/a01115.html">source
    documentation for <code>namespace abi</code></link> then you are
    aware of the cross-vendor C++ ABI in use by GCC.  One of the
    exposed functions is used for demangling,
    <code>abi::__cxa_demangle</code>.
  </para>
  <para>
    In programs like <command>c++filt</command>, the linker, and other tools
    have the ability to decode C++ ABI names, and now so can you.
  </para>
  <para>
    (The function itself might use different demanglers, but that's the
    whole point of abstract interfaces.  If we change the implementation,
    you won't notice.)
  </para>
  <para>
    Probably the only times you'll be interested in demangling at runtime
    are when you're seeing <code>typeid</code> strings in RTTI, or when
    you're handling the runtime-support exception classes.  For example:
  </para>
   <programlisting>
#include &lt;exception&gt;
#include &lt;iostream&gt;
#include &lt;cxxabi.h&gt;

struct empty { };

template &lt;typename T, int N&gt;
  struct bar { };


int main()
{
  int     status;
  char   *realname;

  // exception classes not in &lt;stdexcept&gt;, thrown by the implementation
  // instead of the user
  std::bad_exception  e;
  realname = abi::__cxa_demangle(e.what(), 0, 0, &amp;status);
  std::cout &lt;&lt; e.what() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
  free(realname);


  // typeid
  bar&lt;empty,17&gt;          u;
  const std::type_info  &amp;ti = typeid(u);

  realname = abi::__cxa_demangle(ti.name(), 0, 0, &amp;status);
  std::cout &lt;&lt; ti.name() &lt;&lt; "\t=&gt; " &lt;&lt; realname &lt;&lt; "\t: " &lt;&lt; status &lt;&lt; '\n';
  free(realname);

  return 0;
}
   </programlisting>
   <para>
     This prints
   </para>

   <screen>
   <computeroutput>
      St13bad_exception       =&gt; std::bad_exception   : 0
      3barI5emptyLi17EE       =&gt; bar&lt;empty, 17&gt;       : 0
   </computeroutput>
   </screen>

   <para>
     The demangler interface is described in the source documentation
     linked to above.  It is actually written in C, so you don't need to
     be writing C++ in order to demangle C++.  (That also means we have to
     use crummy memory management facilities, so don't forget to free()
     the returned char array.)
   </para>
</chapter>

<!-- Chapter 13 : Concurrency -->
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="xml" href="concurrency_extensions.xml">
</xi:include>

</part>