diff options
Diffstat (limited to 'libstdc++-v3/doc/xml/manual/extensions.xml')
| -rw-r--r-- | libstdc++-v3/doc/xml/manual/extensions.xml | 581 |
1 files changed, 581 insertions, 0 deletions
diff --git a/libstdc++-v3/doc/xml/manual/extensions.xml b/libstdc++-v3/doc/xml/manual/extensions.xml new file mode 100644 index 000000000..b93c61f1b --- /dev/null +++ b/libstdc++-v3/doc/xml/manual/extensions.xml @@ -0,0 +1,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<bool></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<N></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 (<=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<N>," then their names and signatures are: +</para> + <programlisting> + bitset<N>& _Unchecked_set (size_t pos); + bitset<N>& _Unchecked_set (size_t pos, int val); + bitset<N>& _Unchecked_reset (size_t pos); + bitset<N>& _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> + <hash_map> + <hash_set> + <rope> + <slist> + <rb_tree> + </programlisting> + <para>are all here; + <code><hash_map></code> and <code><hash_set></code> + are deprecated but available as backwards-compatible extensions, + as discussed further below. <code><rope></code> is the + SGI specialization for large strings ("rope," + "large strings," get it? Love that geeky humor.) + <code><slist></code> is a singly-linked list, for when the + doubly-linked <code>list<></code> is too much space + overhead, and <code><rb_tree></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 <functional> 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<int>(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>=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><ext/stdio_filebuf.h></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 <exception> +#include <iostream> +#include <cxxabi.h> + +struct empty { }; + +template <typename T, int N> + struct bar { }; + + +int main() +{ + int status; + char *realname; + + // exception classes not in <stdexcept>, thrown by the implementation + // instead of the user + std::bad_exception e; + realname = abi::__cxa_demangle(e.what(), 0, 0, &status); + std::cout << e.what() << "\t=> " << realname << "\t: " << status << '\n'; + free(realname); + + + // typeid + bar<empty,17> u; + const std::type_info &ti = typeid(u); + + realname = abi::__cxa_demangle(ti.name(), 0, 0, &status); + std::cout << ti.name() << "\t=> " << realname << "\t: " << status << '\n'; + free(realname); + + return 0; +} + </programlisting> + <para> + This prints + </para> + + <screen> + <computeroutput> + St13bad_exception => std::bad_exception : 0 + 3barI5emptyLi17EE => bar<empty, 17> : 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> |