OSDN Git Service

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