diff options
| author | bkoz <bkoz@138bc75d-0d04-0410-961f-82ee72b054a4> | 2007-12-10 00:38:36 +0000 |
|---|---|---|
| committer | bkoz <bkoz@138bc75d-0d04-0410-961f-82ee72b054a4> | 2007-12-10 00:38:36 +0000 |
| commit | c3d8729e5fd7bb66c398fd2512211e49f7ececbc (patch) | |
| tree | fd8a2c1f9d4504553b1ef84e02282972137daf4a /libstdc++-v3/docs | |
| parent | c55533c03f79c01037c7a6e0642659b5d67c8f01 (diff) | |
| download | gcc-c3d8729e5fd7bb66c398fd2512211e49f7ececbc.tar.gz | |
2007-12-09 Benjamin Kosnik <bkoz@redhat.com>
* docs/html/ext/howto.html: Update.
* docs/html/ext/sgiexts.html: Same.
* docs/html/ext/concurrence.html: New. Document extensions.
* docs/html/17_intro/api.html: Move some bits...
* docs/html/17_intro/backwards_compatibility.html: here. New. Add
compatibility suggestions, move existing ones.
* docs/html/17_intro/howto.html: Update info.
* docs/html/18_support/howto.html: Tweak.
* docs/html/faq/index.html: Update thread info.
* docs/html/documentation.html: Add links.
* docs/html/20_util/allocator.html: Update info.
* include/precompiled/stdc++.h: Add C++0x includes if appropriate.
* testsuite/17_intro/headers/c++200x/all.cc: Same.
git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@130732 138bc75d-0d04-0410-961f-82ee72b054a4
Diffstat (limited to 'libstdc++-v3/docs')
| -rw-r--r-- | libstdc++-v3/docs/html/17_intro/api.html | 623 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/17_intro/backwards_compatibility.html | 1073 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/17_intro/howto.html | 599 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/18_support/howto.html | 8 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/20_util/allocator.html | 78 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/documentation.html | 35 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/ext/concurrence.html | 342 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/ext/howto.html | 17 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/ext/sgiexts.html | 38 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/faq/index.html | 20 |
10 files changed, 2088 insertions, 745 deletions
diff --git a/libstdc++-v3/docs/html/17_intro/api.html b/libstdc++-v3/docs/html/17_intro/api.html index bfe7b20371d..983d044b7c9 100644 --- a/libstdc++-v3/docs/html/17_intro/api.html +++ b/libstdc++-v3/docs/html/17_intro/api.html @@ -5,8 +5,8 @@ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <head> - <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik), Felix Natter" /> - <meta name="KEYWORDS" content="C++, libstdc++, API, deprecate backward" /> + <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" /> + <meta name="KEYWORDS" content="C++, libstdc++, API, evolution, deprecate" /> <meta name="DESCRIPTION" content="API evolution and deprecation history" /> <meta name="GENERATOR" content="emacs and ten fingers" /> <title>API Evolution and Deprecation History</title> @@ -22,7 +22,7 @@ <p class="fineprint"><em> The latest version of this document is always available at <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/api.html"> - http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/abi.html</a>. + http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/api.html</a>. </em></p> <p><em> @@ -30,565 +30,260 @@ </em></p> <!-- ####################################################### --> + <hr /> <h3 class="left"> - <a name="C++ API v1">First.</a> + <a name="intro">API Evolution, Deprecation, and History of User Visible Changes</a> </h3> -<p>2.72</p> -<p> The first generation GNU C++ library was called libg++. It had a -working relationship with at least two kinds of dinosaur. Sadly, the -details were not pried away from the estate. +<p> A list of user-visible changes, by release version. </p> -<p> +<h3 class="left"> + <a name="3.0">3.0</a> +</h3> +<p> +Extensions moved to <code>include/ext</code>. </p> -<p>Known Issues include many of the limitations of its immediate ancestor.</p> - -<h5>No <code>ios_base</code></h5> - -<p> At least some older implementations don't have <code>std::ios_base</code>, so you should use <code>std::ios::badbit</code>, <code>std::ios::failbit</code> and <code>std::ios::eofbit</code> and <code>std::ios::goodbit</code>. +<p> +Include files from the SGI/HP sources that pre-date the ISO standard +are added. These files are placed into +the <code>include/backward</code> directory and a deprecated warning +is added that notifies on inclusion (<code>-Wno-deprecated</code> +deactivates the warning.) </p> -<h5>No <code>cout</code> in <code>ostream.h</code>, no <code>cin</code> in <code>istream.h</code></h5> - -<p> - In earlier versions of the standard, - <tt><fstream.h></tt>, - <tt><ostream.h></tt> - and <tt><istream.h></tt> - used to define - <code>cout</code>, <code>cin</code> and so on. ISO C++ specifies that one needs to include - <tt><iostream></tt> - explicitly to get the required definitions. - </p> -<p> Some include adjustment may be required.</p> +<p>Deprecated include <backward/strstream> added.</p> +<p>Removal of include <builtinbuf.h>, <indstream.h>, <parsestream.h>, <PlotFile.h>, <SFile.h>, <stdiostream.h>, and <stream.h>.</p> -<p>This project is no longer maintained or supported, and the sources -archived. The code is considered replaced and rewritten. -</p> -<hr /> <h3 class="left"> - <a name="C++ API v1">Second.</a> + <a name="3.1">3.1</a> </h3> -<p> The second generation GNU C++ library was called libstdc++, or -libstdc++-v2. It was a separate GNU project, although reliably paired -with GCC. It spans the time between libg++ and pre-ISO C++. -</p> - -<p>egcs 1.x</p> -<p>2.95</p> -<p>2.96</p> -<p>Portability Notes</p> -<p>Implementation Limitations</p> - -<h5>Namespace <code>std::</code> not supported.</h5> - -<p> - Some care is required to support C++ compiler and or library - implementation that do not have the standard library in - <code>namespace std</code>. - </p> -<p> - The following sections list some possible solutions to support compilers - that cannot ignore <code>std::</code>-qualified names. - </p> - -<p> First, see if the compiler has a flag for this. Namespace - back-portability-issues are generally not a problem for g++ - compilers that do not have libstdc++ in <code>std::</code>, as - the compilers use <code>-fno-honor-std</code> (ignore - <code>std::</code>, <code>:: = std::</code>) by default. That - is, the responsibility for enabling or disabling - <code>std::</code> is on the user; the maintainer does not have - to care about it. This probably applies to some other compilers - as well. - </p> - -<p>Second, experiment with a variety of pre-processor tricks.</p> - -<p> By defining <code>std</code> as a macro, fully-qualified namespace calls become global. Volia. - -<pre class="programlisting"> -#ifdef WICKEDLY_OLD_COMPILER -# define std -#endif -</pre> -(thanks to Juergen Heinzl who posted this solution on gnu.gcc.help) - -<p>Define a macro <code>NAMESPACE_STD</code>, which is defined to -either "" or "std" based on a compile-type -test. On GNU systems, this can be done with autotools by means of an -autoconf test (see below) for <code>HAVE_NAMESPACE_STD</code>, then -using that to set a value for the <code>NAMESPACE_STD</code> macro. -At that point, one is able to use <code>NAMESPACE_STD::string</code>, -which will evaluate to <code>std::string</code> or -<code>::string</code> (ie, in the global namespace on systems that do -not put <code>string</code> in <code>std::</code>). </p> - -<p> -<pre> -dnl @synopsis AC_CXX_HAVE_STD_NAMESPACE -dnl -dnl If the compiler supports the std namespace, define -dnl HAVE_STD_NAMESPACE. -dnl -dnl @category Cxx -dnl @author Todd Veldhuizen -dnl @author Luc Maisonobe <luc@spaceroots.org> -dnl @version 2004-02-04 -dnl @license AllPermissive - -AC_DEFUN([AC_CXX_HAVE_STD_NAMESPACE], -[AC_CACHE_CHECK(whether the compiler supports the std namespace, -ac_cv_cxx_have_std_namespace, -[AC_LANG_SAVE - AC_LANG_CPLUSPLUS - AC_TRY_COMPILE([#include <iostream> - std::istream& is = std::cin; - ],[return 0;], - ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no) - AC_LANG_RESTORE -]) -if test "$ac_cv_cxx_have_std_namespace" = yes; then - AC_DEFINE(HAVE_STD_NAMESPACE,,[define if the compiler supports the std namespace]) -fi -]) -</pre> - -<h5>Illegal iterator usage.</h5> <p> - The following illustrate implementation-allowed illegal iterator - use, and then correct use. <div class="itemizedlist"><ul - type="disc"> <li><p>you cannot do - <code>ostream::operator<<(iterator)</code> to print the - address of the iterator => use <code>operator<< - &*iterator</code> instead ? - </p></li> -<li><p>you cannot clear an iterator's reference - (<code>iterator = 0</code>) => use - <code>iterator = iterator_type();</code> ? - </p></li> -<li><p> -<code>if (iterator)</code> won't work any - more => use <code>if (iterator != iterator_type())</code> - ?</p></li> -</ul> +Extensions from SGI/HP moved from <code>namespace std</code> +to <code>namespace __gnu_cxx</code>. As part of this, the following +new includes are +added: <ext/algorithm>, <ext/functional>, <ext/iterator>, <ext/memory>, and <ext/numeric>. +</p> -<h5><code>isspace</code> from <tt><cctype></tt> is a macro -</h5> +<p> +Extensions to <code>basic_filebuf</code> introduced: <code>__gnu_cxx::enc_filebuf</code>, and <code>__gnu_cxx::stdio_filebuf</code>. +</p> -<p> Glibc 2.0.x and 2.1.x define <tt><ctype.h></tt> -functionality as macros (isspace, isalpha etc.). +<p> +Extensions to tree data structures added in <ext/rb_tree>. </p> <p> -This implementations of libstdc++, however, keep these functions as -macros, and so it is not back-portable to use fully qualified -names. For example: +Removal of <ext/tree>, moved to <backward/tree.h>. </p> -<pre> -#include <cctype> -int main() { std::isspace('X'); } -</pre> -<p>Results in something like this: -</p> +<h3 class="left"> + <a name="3.2">3.2</a> +</h3> +<p>Symbol versioning introduced for shared library.</p> -<pre> -std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ; -</pre> +<p>Removal of include <backward/strstream.h>.</p> +<h3 class="left"> + <a name="3.3">3.3</a> +</h3> +<p>Allocator changes. Change <code>__malloc_alloc</code> to <code>malloc_allocator</code> and <code>__new_alloc</code> to <code>new_allocator</code>. </p> -<p> A solution is to modify a header-file so that the compiler tells -<tt><ctype.h></tt> to define functions instead of macros: -</p> +<p>Error handling in iostreams cleaned up, made consistent. </p> -<pre> -// This keeps isalnum, et al from being propagated as macros. -#if __linux__ -# define __NO_CTYPE 1 -#endif -</pre> -<p>Then, include <ctype.h> +<h3 class="left"> + <a name="3.4">3.4</a> +</h3> +<p> +Large file support. </p> -<p> -Another problem arises if you put a <code>using namespace std;</code> -declaration at the top, and include <tt><ctype.h></tt>. This -will result in ambiguities between the definitions in the global -namespace (<tt><ctype.h></tt>) and the definitions in namespace -<code>std::</code> (<code><cctype></code>). +<p> Extensions for generic characters and <code>char_traits</code> added in <ext/pod_char_traits.h>. </p> -<h5>No <code>vector::at</code>, <code>deque::at</code>, <code>string::at</code></h5> +<p> +Support for <code>wchar_t</code> specializations of <code>basic_filebuf</code> enhanced to support <code>UTF-8</code> and <code>Unicode</code>, depending on host. More hosts support basic <code>wchar_t</code> functionality. +</p> <p> - One solution is to add an autoconf-test for this: -</p> -<pre> -AC_MSG_CHECKING(for container::at) -AC_TRY_COMPILE( -[ -#include <vector> -#include <deque> -#include <string> - -using namespace std; -], -[ -deque<int> test_deque(3); -test_deque.at(2); -vector<int> test_vector(2); -test_vector.at(1); -string test_string("test_string"); -test_string.at(3); -], -[AC_MSG_RESULT(yes) -AC_DEFINE(HAVE_CONTAINER_AT)], -[AC_MSG_RESULT(no)]) -</pre> +Support for <code>char_traits</code> beyond builtin types. +</p> <p> -If you are using other (non-GNU) compilers it might be a good idea -to check for <code>string::at</code> separately. +Conformant <code>allocator</code> class and usage in containers. As +part of this, the following extensions are +added: <ext/bitmap_allocator.h>, <ext/debug_allocator.h>, <ext/mt_allocator.h>, <ext/malloc_allocator.h>,<ext/new_allocator.h>, <ext/pool_allocator.h>. </p> -<h5>No <code>std::char_traits<char>::eof</code></h5> <p> -Use some kind of autoconf test, plus this: -</p> -<pre> -#ifdef HAVE_CHAR_TRAITS -#define CPP_EOF std::char_traits<char>::eof() -#else -#define CPP_EOF EOF -#endif -</pre> - -<h5>No <code>string::clear</code></h5> +Debug mode first appears. +</p> <p> - There are two functions for deleting the contents of a string: - <code>clear</code> and <code>erase</code> (the latter - returns the string). - <pre class="programlisting"> - void - clear() { _M_mutate(0, this->size(), 0); } - </pre> - <pre class="programlisting"> - basic_string& - erase(size_type __pos = 0, size_type __n = npos) - { - return this->replace(_M_check(__pos), _M_fold(__pos, __n), - _M_data(), _M_data()); - } - </pre> - Unfortunately, ut <code>clear</code> is not - implemented in this version, so you should use - <code>erase</code> (which is probably faster than - <code>operator=(charT*)</code>). -</p> - -<h5>Removal of <code>ostream::form</code> and -<code>istream::scan</code> extensions.</h5> - -<p> These are no longer supported. Please use - <a href="#sec-stringstream" title="Using stringstreams"> - stringstreams</a> instead. -</p> - -<h5>No <code>basic_stringbuf</code>, <code>basic_stringstream<code></h5> +PCH support. +</p> <p> - Libstdc++ provides the new - <code>i/ostringstream</code>-classes, (<tt><sstream></tt>), but for compatibility - with older implementations you still have to use - <code>i/ostrstream</code> (<tt><strstream></tt>): - <pre > - #ifdef HAVE_SSTREAM - #include <sstream> - #else - #include <strstream> - #endif - </pre> - <div class="itemizedlist"><ul type="disc"> -<li><p> <code>strstream</code> is considered to be - deprecated - </p></li> -<li><p> <code>strstream</code> is limited to - <code>char</code> - </p></li> -<li><p> with <code>ostringstream</code> you don't - have to take care of terminating the string or freeing its - memory - </p></li> -<li><p> <code>istringstream</code> can be re-filled - (clear(); str(input);) - </p></li> -</ul></div> -<p> - You can then use output-stringstreams like this: - <pre > - #ifdef HAVE_SSTREAM - std::ostringstream oss; - #else - std::ostrstream oss; - #endif - oss << "Name=" << m_name << ", number=" << m_number << std::endl; - ... - #ifndef HAVE_SSTREAM - oss << std::ends; // terminate the char*-string - #endif - // str() returns char* for ostrstream and a string for ostringstream - // this also causes ostrstream to think that the buffer's memory - // is yours - m_label.set_text(oss.str()); - #ifndef HAVE_SSTREAM - // let the ostrstream take care of freeing the memory - oss.freeze(false); - #endif - </pre> -<p> - Input-stringstreams can be used similarly: -</p> - -<pre> -std::string input; -... -#ifdef HAVE_SSTREAM -std::istringstream iss(input); -#else -std::istrstream iss(input.c_str()); -#endif - -int i; -iss >> i; -</pre> - -<p> One (the only?) restriction is that an istrstream cannot be re-filled: -</p> - -<pre > -std::istringstream iss(numerator); -iss >> m_num; -// this is not possible with istrstream -iss.clear(); -iss.str(denominator); -iss >> m_den; - </pre> - -<p> -If you don't care about speed, you can put these conversions in - a template-function: -</p> -<pre > -template <class X> -void fromString(const string& input, X& any) -{ -#ifdef HAVE_SSTREAM -std::istringstream iss(input); -#else -std::istrstream iss(input.c_str()); -#endif -X temp; -iss >> temp; -if (iss.fail()) -throw runtime_error(..) -any = temp; -} -</pre> - -<p> Another example of using stringstreams is in <a href="../21_strings/howto.html" target="_top">this howto</a>. +Macro guard for libstdc++ changed, from _GLIBCPP_ to _GLIBCXX_. </p> -<p> There is additional information in the libstdc++-v2 info files, in -particular "info iostream". +<p> +Extension <ext/stdio_sync_filebuf.h> added. </p> -<h5>Little or no wide character support</h5> - -<h5>No templatized iostreams</h5> - -<h5>Thread safety issues.</h5> - -<p>This project is no longer maintained or supported, and the sources -archived. The code is considered replaced and rewritten. +<p> +Extension <ext/demangle.h> added. </p> -<hr /> <h3 class="left"> - <a name="C++ API v1">Third.</a> + <a name="4.0">4.0</a> </h3> -<p> The third generation GNU C++ library is called libstdc++, or -libstdc++-v3. +<p> +TR1 features first appear. </p> - <p>The subset commonly known as the Standard Template Library - (chapters 23 through 25, mostly) is adapted from the final release - of the SGI STL, with extensive changes. - </p> - - <p>A more formal description of the V3 goals can be found in the - official <a href="../17_intro/DESIGN">design document</a>. - </p> - - -<p>Portability Notes</p> - -<h5>Pre-ISO headers moved to backwards</h5> -<p> The pre-ISO C++ headers (iostream.h etc.) are available, but inclusion - generates a warning that you are using deprecated headers. +<p> +Extension allocator <ext/array_allocator.h> added. </p> - <p>This compatibility layer is constructed by including the - standard C++ headers, and injecting any items in - <code>std::</code> into the global namespace. - </p> - <p>For those of you new to ISO C++ (welcome, time travelers!), no, - that isn't a typo. Yes, the headers really have new names. - Marshall Cline's C++ FAQ Lite has a good explanation in <a - href="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4">item - [27.4]</a>. - </p> - -<p> Some include adjustment may be required.</p> - -<h5>Extension headers hash_map, hash_set moved to ext</h5> +<p> +Extension <code>codecvt</code> specializations moved to <ext/codecvt_specializations.h>. +</p> -<p> Header files <code>hash_map</code> and <code>hash_set</code> -moved to <code>ext/hash_map</code> and <code>ext/hash_set</code>, -respectively. At the same time, all types in these files are enclosed -in <code>namespace __gnu_cxx</code>. +<p> +Removal of <ext/demangle.h>. </p> -<h5> -No <code>ios::nocreate/ios::noreplace</code>. -</h5> +<h3 class="left"> + <a name="4.1">4.1</a> +</h3> -<p> The existence of <code>ios::nocreate</code> being used for -input-streams has been confirmed, most probably because the author -thought it would be more correct to specify nocreate explicitly. So -it can be left out for input-streams. +<p> +Removal of <cassert> from all standard headers: now has to be explicitly included for <code>std::assert</code> calls. </p> -<p>For output streams, "nocreate" is probably the default, -unless you specify <code>std::ios::trunc</code> ? To be safe, you can -open the file for reading, check if it has been opened, and then -decide whether you want to create/replace or not. To my knowledge, -even older implementations support <code>app</code>, <code>ate</code> -and <code>trunc</code> (except for <code>app</code> ?). +<p> Extensions for policy-based data structures first added. New includes, +types, namespace <code>pb_assoc</code>. </p> -<h5> -No <code>stream::attach(int fd)</code>. -</h5> - -<p> - Phil Edwards writes: It was considered and rejected for the ISO - standard. Not all environments use file descriptors. Of those - that do, not all of them use integers to represent them. - </p> -<p> - For a portable solution (among systems which use - filedescriptors), you need to implement a subclass of - <code>std::streambuf</code> (or - <code>std::basic_streambuf<..></code>) which opens a file - given a descriptor, and then pass an instance of this to the - stream-constructor. - </p> - -<p> - An extension is available that implements this. - <code><ext/stdio_filebuf.h></code> contains a derived class called - <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/class____gnu__cxx_1_1stdio__filebuf.html"><code>__gnu_cxx::stdio_filebuf</code></a>. - This class can be constructed from a C <code>FILE*</code> or a file - descriptor, and provides the <code>fd()</code> function. - </p> - -<p> - For another example of this, refer to - <a href="http://www.josuttis.com/cppcode/fdstream.html" target="_top">fdstream example</a> - by Nicolai Josuttis. +<p> Extensions for typelists added in <ext/typelist.h>. </p> -<p><a href="http://gcc.gnu.org/bugzilla/buglist.cgi?cmdtype=runnamed&namedcmd=libstdc%2B%2B">Known Issues</a></p> - -<h5> -container iterator types are not necessarily container value_type* -</h5> - -<p>API History, User Visible Changes</p> +<p> Extension for policy-based <code>basic_string</code> first added: <code>__gnu_cxx::__versa_string</code> in <ext/vstring.h>. +</p> -<p>3.0.0</p> +<h3 class="left"> + <a name="4.2">4.2</a> +</h3> +<p> Default visibility attributes applied to <code>namespace std</code>. Support for <code>-fvisibility</code>. +</p> -<p>3.1.0</p> -<p>3.2.0</p> -<p>3.3.0</p> +<p>TR1 <random>, <complex>, and C compatibility headers added.</p> +<p> Extensions for concurrent programming consolidated +into <ext/concurrence.h> and <ext/atomicity.h>, +including change of namespace to <code>__gnu_cxx</code> in some +cases. Added types +include <code>_Lock_policy</code>, <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__mutex</code>, <code>__scoped_lock</code>.</p> -<p>3.4.0</p> +<p> Extensions for type traits consolidated +into <ext/type_traits.h>. Additional traits are added +(<code>__conditional_type</code>, <code>__enable_if</code>, others.) +</p> -Macro guard for libstdc++ changed, from _GLIBCPP_ to _GLIBCXX_, to -accomodate a request from the C Pre Processor maintainer. +<p> Extensions for policy-based data structures revised. New includes, +types, namespace moved to <code>__pb_ds</code>. +</p> -<p>4.0.0</p> -<p>4.1.0</p> +<p> Extensions for debug mode modified: now nested in <code>namespace +std::__debug</code> and extensions in <code>namespace +__gnu_cxx::__debug</code>.</p> -<cassert> how has to be explicitly included for <code>std::assert</code> calls. +<p> Extensions added: <ext/typelist.h> +and <ext/throw_allocator.h>. +</p> -<p>4.2.0</p> +<h3 class="left"> + <a name="4.3">4.3</a> +</h3> -<p>4.3.0</p> +<p> +C++0X features first appear. +</p> -Header streamlining. +<p>TR1 <regex> and <cmath>'s mathematical special function added.</p> +<p> Backward include edit. +</p> +<ul> + <li> Removed: <algobase.h> <algo.h> <alloc.h> <bvector.h> <complex.h> +defalloc.h> <deque.h> <fstream.h> <function.h> <hash_map.h> <hash_set.h> +hashtable.h> <heap.h> <iomanip.h> <iostream.h> <istream.h> <iterator.h> +list.h> <map.h> <multimap.h> <multiset.h> <new.h> <ostream.h> <pair.h> <queue.h> +rope.h> <set.h> <slist.h> <stack.h> <streambuf.h> <stream.h> <tempbuf.h> +<tree.h> <vector.h> + </li> + <li> Added: <hash_map> and <hash_set></li> + <li> Added in C++0x: <auto_ptr.h> and <binders.h></li> +</ul> -PCH files built but not installed. - -Namespace pb_ds moved to __gnu_pb_ds. +<p> +Header dependency streamlining. +</p> -C++OX features appear. +<ul> + <li><algorithm> no longer includes <climits>, <cstring>, or <iosfwd> </li> + <li><bitset> no longer includes <istream> or <ostream>, adds <iosfwd> </li> + <li><functional> no longer includes <cstddef></li> + <li><iomanip> no longer includes <istream>, <istream>, or <functional>, adds <ioswd> </li> + <li><numeric> no longer includes <iterator></li> + <li><string> no longer includes <algorithm> or <memory></li> + + <li><valarray> no longer includes <numeric> or <cstdlib></li> + <li><tr1/hashtable> no longer includes <memory> or <functional></li> + <li><tr1/memory> no longer includes <algorithm></li> + <li><tr1/random> no longer includes <algorithm> or <fstream></li> +</ul> -<hr /> -<h3 class="left"> - <a name="C++ API v1">Fourth, and future</a> -</h3> +<p> +Debug mode for <unordered_map> and <unordered_set>. +</p> -<hr /> -<h3 class="left"> - <a name="Deprecation">Deprecation and Backwards Compatibility</a> -</h3> +<p> +Parallel mode first appears. +</p> -<hr /> -<h3 class="left"> - <a name="Links">Links</a> -</h3> +<p>Variadic template implementations of items in <tuple> and + <functional>. +</p> -<p> -<a href="http://www.kegel.com/gcc/gcc4.html">Migrating to gcc-4.1</a>, by Dan Kegel. +<p>Default <code>what</code> implementations give more elaborate + exception strings for <code>bad_cast</code>, + <code>bad_typeid</code>, <code>bad_exception</code>, and + <code>bad_alloc</code>. </p> <p> -<a href="http://lists.debian.org/debian-gcc/2006/03/msg00405.html">Building the whole Debian archive with GCC 4.1: a summary</a>, by Martin Michlmayr +PCH binary files no longer installed. Instead, the source files are installed. </p> <p> -<a href="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html">Migration guide for GCC-3.2</a> +Namespace pb_ds moved to __gnu_pb_ds. </p> </body> diff --git a/libstdc++-v3/docs/html/17_intro/backwards_compatibility.html b/libstdc++-v3/docs/html/17_intro/backwards_compatibility.html new file mode 100644 index 00000000000..bc1497bdde0 --- /dev/null +++ b/libstdc++-v3/docs/html/17_intro/backwards_compatibility.html @@ -0,0 +1,1073 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> + <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik), Felix Natter" /> + <meta name="KEYWORDS" content="C++, libstdc++, API, backward, compatibility" /> + <meta name="DESCRIPTION" content="Backwards Compatibility" /> + <meta name="GENERATOR" content="emacs and ten fingers" /> + <title>Backwards Compatibility</title> +<link rel="StyleSheet" href="lib3styles.css" type="text/css" /> +<link rel="Start" href="documentation.html" type="text/html" + title="GNU C++ Standard Library" /> +<link rel="Copyright" href="17_intro/license.html" type="text/html" /> +</head> +<body> + +<h1 class="centered"><a name="top">Backwards Compatibility</a></h1> + +<p class="fineprint"><em> + The latest version of this document is always available at + <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/backwards_compatibility.html"> + http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/backwards_compatibility.html</a>. +</em></p> + +<p><em> + To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++ homepage</a>. +</em></p> + +<!-- ####################################################### --> +<hr /> +<h3 class="left"> + <a name="v1">First.</a> +</h3> + +<p> The first generation GNU C++ library was called libg++. It was a +separate GNU project, although reliably paired with GCC. Rumors imply +that it had a working relationship with at least two kinds of +dinosaur. +</p> + +<p>Known Issues include many of the limitations of its immediate ancestor.</p> + +<p>Portability notes and known implementation limitations are as follows.</p> + +<h5>No <code>ios_base</code></h5> + +<p> At least some older implementations don't have <code>std::ios_base</code>, so you should use <code>std::ios::badbit</code>, <code>std::ios::failbit</code> and <code>std::ios::eofbit</code> and <code>std::ios::goodbit</code>. +</p> + +<h5>No <code>cout</code> in <code>ostream.h</code>, no <code>cin</code> in <code>istream.h</code></h5> + +<p> + In earlier versions of the standard, + <tt><fstream.h></tt>, + <tt><ostream.h></tt> + and <tt><istream.h></tt> + used to define + <code>cout</code>, <code>cin</code> and so on. ISO C++ specifies that one needs to include + <tt><iostream></tt> + explicitly to get the required definitions. + </p> +<p> Some include adjustment may be required.</p> + + +<p>This project is no longer maintained or supported, and the sources +archived. The code is considered replaced and rewritten. +</p> + +<hr /> +<h3 class="left"> + <a name="v2">Second.</a> +</h3> +<p> The second generation GNU C++ library was called libstdc++, or +libstdc++-v2. It spans the time between libg++ and pre-ISO C++ +standardization and is usually associated with the following GCC +releases: egcs 1.x, gcc 2.95, and gcc 2.96. +</p> + +<p> The STL portions of this library are based on SGI/HP STL release 3.11. +</p> + +<p>Portability notes and known implementation limitations are as follows.</p> + +<h5>Namespace <code>std::</code> not supported</h5> + +<p> + Some care is required to support C++ compiler and or library + implementation that do not have the standard library in + <code>namespace std</code>. + </p> +<p> + The following sections list some possible solutions to support compilers + that cannot ignore <code>std::</code>-qualified names. + </p> + +<p> First, see if the compiler has a flag for this. Namespace + back-portability-issues are generally not a problem for g++ + compilers that do not have libstdc++ in <code>std::</code>, as + the compilers use <code>-fno-honor-std</code> (ignore + <code>std::</code>, <code>:: = std::</code>) by default. That + is, the responsibility for enabling or disabling + <code>std::</code> is on the user; the maintainer does not have + to care about it. This probably applies to some other compilers + as well. + </p> + +<p>Second, experiment with a variety of pre-processor tricks.</p> + +<p> By defining <code>std</code> as a macro, fully-qualified namespace calls become global. Volia. </p> + +<pre> +#ifdef WICKEDLY_OLD_COMPILER +# define std +#endif +</pre> +(thanks to Juergen Heinzl who posted this solution on gnu.gcc.help) + +<p>Another pre-processor based approach is to define a +macro <code>NAMESPACE_STD</code>, which is defined to either +"" or "std" based on a compile-type test. On GNU +systems, this can be done with autotools by means of an autoconf test +(see below) for <code>HAVE_NAMESPACE_STD</code>, then using that to +set a value for the <code>NAMESPACE_STD</code> macro. At that point, +one is able to use <code>NAMESPACE_STD::string</code>, which will +evaluate to <code>std::string</code> or +<code>::string</code> (ie, in the global namespace on systems that do +not put <code>string</code> in <code>std::</code>). </p> + +<pre style="background: #c0c0c0"> +dnl @synopsis AC_CXX_NAMESPACE_STD +dnl +dnl If the compiler supports namespace std, define +dnl HAVE_NAMESPACE_STD. +dnl +dnl @category Cxx +dnl @author Todd Veldhuizen +dnl @author Luc Maisonobe <luc@spaceroots.org> +dnl @version 2004-02-04 +dnl @license AllPermissive +AC_DEFUN([AC_CXX_NAMESPACE_STD], [ + AC_CACHE_CHECK(if g++ supports namespace std, + ac_cv_cxx_have_std_namespace, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([#include <iostream> + std::istream& is = std::cin;],, + ac_cv_cxx_have_std_namespace=yes, ac_cv_cxx_have_std_namespace=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_have_std_namespace" = yes; then + AC_DEFINE(HAVE_NAMESPACE_STD,,[Define if g++ supports namespace std. ]) + fi +]) +</pre> + +<h5>Illegal iterator usage</h5> +<p> + The following illustrate implementation-allowed illegal iterator + use, and then correct use. +</p> + +<ul> <li><p>you cannot do + <code>ostream::operator<<(iterator)</code> to print the + address of the iterator => use <code>operator<< + &*iterator</code> instead + </p></li> +<li><p>you cannot clear an iterator's reference + (<code>iterator = 0</code>) => use + <code>iterator = iterator_type();</code> + </p></li> +<li><p> +<code>if (iterator)</code> won't work any + more => use <code>if (iterator != iterator_type())</code> + </p></li> +</ul> + +<h5><code>isspace</code> from <tt><cctype></tt> is a macro +</h5> + +<p> Glibc 2.0.x and 2.1.x define <tt><ctype.h></tt> +functionality as macros (isspace, isalpha etc.). +</p> + +<p> +This implementations of libstdc++, however, keep these functions as +macros, and so it is not back-portable to use fully qualified +names. For example: +</p> + +<pre> +#include <cctype> +int main() { std::isspace('X'); } +</pre> + +<p>Results in something like this: +</p> + +<pre> +std:: (__ctype_b[(int) ( ( 'X' ) )] & (unsigned short int) _ISspace ) ; +</pre> + + +<p> A solution is to modify a header-file so that the compiler tells +<tt><ctype.h></tt> to define functions instead of macros: +</p> + +<pre> +// This keeps isalnum, et al from being propagated as macros. +#if __linux__ +# define __NO_CTYPE 1 +#endif +</pre> + +<p>Then, include <ctype.h> +</p> + +<p> +Another problem arises if you put a <code>using namespace std;</code> +declaration at the top, and include <tt><ctype.h></tt>. This +will result in ambiguities between the definitions in the global +namespace (<tt><ctype.h></tt>) and the definitions in namespace +<code>std::</code> (<code><cctype></code>). +</p> + +<h5>No <code>vector::at</code>, <code>deque::at</code>, <code>string::at</code></h5> + +<p> + One solution is to add an autoconf-test for this: +</p> +<pre style="background: #c0c0c0"> +AC_MSG_CHECKING(for container::at) +AC_TRY_COMPILE( +[ +#include <vector> +#include <deque> +#include <string> + +using namespace std; +], +[ +deque<int> test_deque(3); +test_deque.at(2); +vector<int> test_vector(2); +test_vector.at(1); +string test_string("test_string"); +test_string.at(3); +], +[AC_MSG_RESULT(yes) +AC_DEFINE(HAVE_CONTAINER_AT)], +[AC_MSG_RESULT(no)]) +</pre> + +<p> +If you are using other (non-GNU) compilers it might be a good idea +to check for <code>string::at</code> separately. +</p> + +<h5>No <code>std::char_traits<char>::eof</code></h5> + +<p> +Use some kind of autoconf test, plus this: +</p> +<pre> +#ifdef HAVE_CHAR_TRAITS +#define CPP_EOF std::char_traits<char>::eof() +#else +#define CPP_EOF EOF +#endif +</pre> + +<h5>No <code>string::clear</code></h5> + +<p> + There are two functions for deleting the contents of a string: + <code>clear</code> and <code>erase</code> (the latter + returns the string). +</p> + +<pre> +void +clear() { _M_mutate(0, this->size(), 0); } +</pre> +<pre> +basic_string& +erase(size_type __pos = 0, size_type __n = npos) +{ + return this->replace(_M_check(__pos), _M_fold(__pos, __n), + _M_data(), _M_data()); +} +</pre> + +<p> + Unfortunately, ut <code>clear</code> is not + implemented in this version, so you should use + <code>erase</code> (which is probably faster than + <code>operator=(charT*)</code>). +</p> + +<h5>Removal of <code>ostream::form</code> and +<code>istream::scan</code> extensions</h5> + +<p> These are no longer supported. Please use + <a href="#sec-stringstream" title="Using stringstreams"> + stringstreams</a> instead. +</p> + +<h5>No <code>basic_stringbuf</code>, <code>basic_stringstream</code></h5> + +<p> +Although the ISO standard +<code>i/ostringstream</code>-classes are provided, (<tt><sstream></tt>), for compatibility with older implementations the pre-ISO <code>i/ostrstream</code> (<tt><strstream></tt>) interface is also provided, with these caveats: +</p> + + <div class="itemizedlist"><ul type="disc"> +<li><p> <code>strstream</code> is considered to be + deprecated + </p></li> +<li><p> <code>strstream</code> is limited to + <code>char</code> + </p></li> +<li><p> with <code>ostringstream</code> you don't + have to take care of terminating the string or freeing its + memory + </p></li> +<li><p> <code>istringstream</code> can be re-filled + (clear(); str(input);) + </p></li> +</ul></div> +<p> + You can then use output-stringstreams like this: +</p> + +<pre> +#ifdef HAVE_SSTREAM +# include <sstream> +#else +# include <strstream> +#endif + +#ifdef HAVE_SSTREAM + std::ostringstream oss; +#else + std::ostrstream oss; +#endif + +oss << "Name=" << m_name << ", number=" << m_number << std::endl; +... +#ifndef HAVE_SSTREAM + oss << std::ends; // terminate the char*-string +#endif + +// str() returns char* for ostrstream and a string for ostringstream +// this also causes ostrstream to think that the buffer's memory +// is yours +m_label.set_text(oss.str()); +#ifndef HAVE_SSTREAM + // let the ostrstream take care of freeing the memory + oss.freeze(false); +#endif +</pre> + +<p> + Input-stringstreams can be used similarly: +</p> + +<pre> +std::string input; +... +#ifdef HAVE_SSTREAM +std::istringstream iss(input); +#else +std::istrstream iss(input.c_str()); +#endif + +int i; +iss >> i; +</pre> + +<p> One (the only?) restriction is that an istrstream cannot be re-filled: +</p> + +<pre> +std::istringstream iss(numerator); +iss >> m_num; +// this is not possible with istrstream +iss.clear(); +iss.str(denominator); +iss >> m_den; + </pre> + +<p> +If you don't care about speed, you can put these conversions in + a template-function: +</p> +<pre> +template <class X> +void fromString(const string& input, X& any) +{ +#ifdef HAVE_SSTREAM +std::istringstream iss(input); +#else +std::istrstream iss(input.c_str()); +#endif +X temp; +iss >> temp; +if (iss.fail()) +throw runtime_error(..) +any = temp; +} +</pre> + +<p> Another example of using stringstreams is in <a href="../21_strings/howto.html" target="_top">this howto</a>. +</p> + +<p> There is additional information in the libstdc++-v2 info files, in +particular "info iostream". +</p> + +<h5>Little or no wide character support</h5> + +<h5>No templatized iostreams</h5> + +<h5>Thread safety issues</h5> + +<p>This project is no longer maintained or supported, and the sources +archived. The code is considered replaced and rewritten. +</p> + + +<hr /> +<h3 class="left"> + <a name="v3">Third.</a> +</h3> +<p> The third generation GNU C++ library is called libstdc++, or +libstdc++-v3. +</p> + + <p>The subset commonly known as the Standard Template Library + (chapters 23 through 25, mostly) is adapted from the final release + of the SGI STL (version 3.3), with extensive changes. + </p> + + <p>A more formal description of the V3 goals can be found in the + official <a href="../17_intro/DESIGN">design document</a>. + </p> + +<p>Portability notes and known implementation limitations are as follows.</p> + +<h5>Pre-ISO headers moved to backwards or removed</h5> + +<p> The pre-ISO C++ headers + (<code>iostream.h</code>, <code>defalloc.h</code> etc.) are + available, unlike previous libstdc++ versions, but inclusion + generates a warning that you are using deprecated headers. +</p> + + <p>This compatibility layer is constructed by including the + standard C++ headers, and injecting any items in + <code>std::</code> into the global namespace. + </p> + <p>For those of you new to ISO C++ (welcome, time travelers!), no, + that isn't a typo. Yes, the headers really have new names. + Marshall Cline's C++ FAQ Lite has a good explanation in <a + href="http://www.parashift.com/c++-faq-lite/coding-standards.html#faq-27.4">item + [27.4]</a>. + </p> + +<p> Some include adjustment may be required. What follows is an +autoconf test that defines <code>PRE_STDCXX_HEADERS</code> when they +exist.</p> + +<pre style="background: #c0c0c0"> +# AC_HEADER_PRE_STDCXX +AC_DEFUN([AC_HEADER_PRE_STDCXX], [ + AC_CACHE_CHECK(for pre-ISO C++ include files, + ac_cv_cxx_pre_stdcxx, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -Wno-deprecated" + + # Omit defalloc.h, as compilation with newer compilers is problematic. + AC_TRY_COMPILE([ + #include <new.h> + #include <iterator.h> + #include <alloc.h> + #include <set.h> + #include <hashtable.h> + #include <hash_set.h> + #include <fstream.h> + #include <tempbuf.h> + #include <istream.h> + #include <bvector.h> + #include <stack.h> + #include <rope.h> + #include <complex.h> + #include <ostream.h> + #include <heap.h> + #include <iostream.h> + #include <function.h> + #include <multimap.h> + #include <pair.h> + #include <stream.h> + #include <iomanip.h> + #include <slist.h> + #include <tree.h> + #include <vector.h> + #include <deque.h> + #include <multiset.h> + #include <list.h> + #include <map.h> + #include <algobase.h> + #include <hash_map.h> + #include <algo.h> + #include <queue.h> + #include <streambuf.h> + ],, + ac_cv_cxx_pre_stdcxx=yes, ac_cv_cxx_pre_stdcxx=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_pre_stdcxx" = yes; then + AC_DEFINE(PRE_STDCXX_HEADERS,,[Define if pre-ISO C++ header files are present. ]) + fi +]) +</pre> + +<p>Porting between pre-ISO headers and ISO headers is simple: headers +like <vector.h> can be replaced with <vector> and a using +directive <code>using namespace std;</code> can be put at the global +scope. This should be enough to get this code compiling, assuming the +other usage is correct. +</p> + +<h5>Extension headers hash_map, hash_set moved to ext or backwards</h5> + +<p> Header files <code>hash_map</code> and <code>hash_set</code> moved +to <code>ext/hash_map</code> and <code>ext/hash_set</code>, +respectively. At the same time, all types in these files are enclosed +in <code>namespace __gnu_cxx</code>. Later versions move deprecate +these files, and suggest using TR1's <code>unordered_map</code> +and <code>unordered_set</code> instead. +</p> + +<p>The following autoconf tests check for working HP/SGI hash containers. +</p> + +<pre style="background: #c0c0c0"> +# AC_HEADER_EXT_HASH_MAP +AC_DEFUN([AC_HEADER_EXT_HASH_MAP], [ + AC_CACHE_CHECK(for ext/hash_map, + ac_cv_cxx_ext_hash_map, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -Werror" + AC_TRY_COMPILE([#include <ext/hash_map>], [using __gnu_cxx::hash_map;], + ac_cv_cxx_ext_hash_map=yes, ac_cv_cxx_ext_hash_map=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_ext_hash_map" = yes; then + AC_DEFINE(HAVE_EXT_HASH_MAP,,[Define if ext/hash_map is present. ]) + fi +]) +</pre> + +<pre style="background: #c0c0c0"> +# AC_HEADER_EXT_HASH_SET +AC_DEFUN([AC_HEADER_EXT_HASH_SET], [ + AC_CACHE_CHECK(for ext/hash_set, + ac_cv_cxx_ext_hash_set, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -Werror" + AC_TRY_COMPILE([#include <ext/hash_set>], [using __gnu_cxx::hash_set;], + ac_cv_cxx_ext_hash_set=yes, ac_cv_cxx_ext_hash_set=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_ext_hash_set" = yes; then + AC_DEFINE(HAVE_EXT_HASH_SET,,[Define if ext/hash_set is present. ]) + fi +]) +</pre> + + +<h5> +No <code>ios::nocreate/ios::noreplace</code>. +</h5> + +<p> The existence of <code>ios::nocreate</code> being used for +input-streams has been confirmed, most probably because the author +thought it would be more correct to specify nocreate explicitly. So +it can be left out for input-streams. +</p> + +<p>For output streams, "nocreate" is probably the default, +unless you specify <code>std::ios::trunc</code> ? To be safe, you can +open the file for reading, check if it has been opened, and then +decide whether you want to create/replace or not. To my knowledge, +even older implementations support <code>app</code>, <code>ate</code> +and <code>trunc</code> (except for <code>app</code> ?). +</p> + + +<h5> +No <code>stream::attach(int fd)</code> +</h5> + +<p> + Phil Edwards writes: It was considered and rejected for the ISO + standard. Not all environments use file descriptors. Of those + that do, not all of them use integers to represent them. + </p> + +<p> + For a portable solution (among systems which use + filedescriptors), you need to implement a subclass of + <code>std::streambuf</code> (or + <code>std::basic_streambuf<..></code>) which opens a file + given a descriptor, and then pass an instance of this to the + stream-constructor. + </p> + +<p> + An extension is available that implements this. + <code><ext/stdio_filebuf.h></code> contains a derived class called + <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/class____gnu__cxx_1_1stdio__filebuf.html"><code>__gnu_cxx::stdio_filebuf</code></a>. + This class can be constructed from a C <code>FILE*</code> or a file + descriptor, and provides the <code>fd()</code> function. + </p> + +<p> + For another example of this, refer to + <a href="http://www.josuttis.com/cppcode/fdstream.html" target="_top">fdstream example</a> + by Nicolai Josuttis. +</p> + +<h5> +Support for C++98 dialect. +</h5> + +<p>Check for complete library coverage of the C++1998/2003 standard. +</p> + +<pre style="background: #c0c0c0"> + +# AC_HEADER_STDCXX_98 +AC_DEFUN([AC_HEADER_STDCXX_98], [ + AC_CACHE_CHECK(for ISO C++ 98 include files, + ac_cv_cxx_stdcxx_98, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([ + #include <cassert> + #include <cctype> + #include <cerrno> + #include <cfloat> + #include <ciso646> + #include <climits> + #include <clocale> + #include <cmath> + #include <csetjmp> + #include <csignal> + #include <cstdarg> + #include <cstddef> + #include <cstdio> + #include <cstdlib> + #include <cstring> + #include <ctime> + + #include <algorithm> + #include <bitset> + #include <complex> + #include <deque> + #include <exception> + #include <fstream> + #include <functional> + #include <iomanip> + #include <ios> + #include <iosfwd> + #include <iostream> + #include <istream> + #include <iterator> + #include <limits> + #include <list> + #include <locale> + #include <map> + #include <memory> + #include <new> + #include <numeric> + #include <ostream> + #include <queue> + #include <set> + #include <sstream> + #include <stack> + #include <stdexcept> + #include <streambuf> + #include <string> + #include <typeinfo> + #include <utility> + #include <valarray> + #include <vector> + ],, + ac_cv_cxx_stdcxx_98=yes, ac_cv_cxx_stdcxx_98=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_stdcxx_98" = yes; then + AC_DEFINE(STDCXX_98_HEADERS,,[Define if ISO C++ 1998 header files are present. ]) + fi +]) +</pre> + + +<h5> +Support for C++TR1 dialect. +</h5> + +<p>Check for library coverage of the TR1 standard. +</p> + +<pre style="background: #c0c0c0"> + +# AC_HEADER_STDCXX_TR1 +AC_DEFUN([AC_HEADER_STDCXX_TR1], [ + AC_CACHE_CHECK(for ISO C++ TR1 include files, + ac_cv_cxx_stdcxx_tr1, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([ + #include <tr1/array> + #include <tr1/ccomplex> + #include <tr1/cctype> + #include <tr1/cfenv> + #include <tr1/cfloat> + #include <tr1/cinttypes> + #include <tr1/climits> + #include <tr1/cmath> + #include <tr1/complex> + #include <tr1/cstdarg> + #include <tr1/cstdbool> + #include <tr1/cstdint> + #include <tr1/cstdio> + #include <tr1/cstdlib> + #include <tr1/ctgmath> + #include <tr1/ctime> + #include <tr1/cwchar> + #include <tr1/cwctype> + #include <tr1/functional> + #include <tr1/memory> + #include <tr1/random> + #include <tr1/regex> + #include <tr1/tuple> + #include <tr1/type_traits> + #include <tr1/unordered_set> + #include <tr1/unordered_map> + #include <tr1/utility> + ],, + ac_cv_cxx_stdcxx_tr1=yes, ac_cv_cxx_stdcxx_tr1=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_stdcxx_tr1" = yes; then + AC_DEFINE(STDCXX_TR1_HEADERS,,[Define if ISO C++ TR1 header files are present. ]) + fi +]) +</pre> + +<p>An alternative is to check just for specific TR1 includes, such as <unordered_map> and <unordered_set>. +</p> + +<pre style="background: #c0c0c0"> +# AC_HEADER_TR1_UNORDERED_MAP +AC_DEFUN([AC_HEADER_TR1_UNORDERED_MAP], [ + AC_CACHE_CHECK(for tr1/unordered_map, + ac_cv_cxx_tr1_unordered_map, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([#include <tr1/unordered_map>], [using std::tr1::unordered_map;], + ac_cv_cxx_tr1_unordered_map=yes, ac_cv_cxx_tr1_unordered_map=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_tr1_unordered_map" = yes; then + AC_DEFINE(HAVE_TR1_UNORDERED_MAP,,[Define if tr1/unordered_map is present. ]) + fi +]) +</pre> + +<pre style="background: #c0c0c0"> +# AC_HEADER_TR1_UNORDERED_SET +AC_DEFUN([AC_HEADER_TR1_UNORDERED_SET], [ + AC_CACHE_CHECK(for tr1/unordered_set, + ac_cv_cxx_tr1_unordered_set, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([#include <tr1/unordered_set>], [using std::tr1::unordered_set;], + ac_cv_cxx_tr1_unordered_set=yes, ac_cv_cxx_tr1_unordered_set=no) + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_tr1_unordered_set" = yes; then + AC_DEFINE(HAVE_TR1_UNORDERED_SET,,[Define if tr1/unordered_set is present. ]) + fi +]) +</pre> + + + +<h5> +Support for C++0x dialect. +</h5> + +<p>Check for baseline language coverage in the compiler for the C++0xstandard. +</p> + +<pre style="background: #c0c0c0"> +# AC_COMPILE_STDCXX_OX +AC_DEFUN([AC_COMPILE_STDCXX_0X], [ + AC_CACHE_CHECK(if g++ supports C++0x features without additional flags, + ac_cv_cxx_compile_cxx0x_native, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + AC_TRY_COMPILE([ + template <typename T> + struct check + { + static_assert(sizeof(int) <= sizeof(T), "not big enough"); + }; + + typedef check<check<bool>> right_angle_brackets; + + int a; + decltype(a) b; + + typedef check<int> check_type; + check_type c; + check_type&& cr = c;],, + ac_cv_cxx_compile_cxx0x_native=yes, ac_cv_cxx_compile_cxx0x_native=no) + AC_LANG_RESTORE + ]) + + AC_CACHE_CHECK(if g++ supports C++0x features with -std=c++0x, + ac_cv_cxx_compile_cxx0x_cxx, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=c++0x" + AC_TRY_COMPILE([ + template <typename T> + struct check + { + static_assert(sizeof(int) <= sizeof(T), "not big enough"); + }; + + typedef check<check<bool>> right_angle_brackets; + + int a; + decltype(a) b; + + typedef check<int> check_type; + check_type c; + check_type&& cr = c;],, + ac_cv_cxx_compile_cxx0x_cxx=yes, ac_cv_cxx_compile_cxx0x_cxx=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + + AC_CACHE_CHECK(if g++ supports C++0x features with -std=gnu++0x, + ac_cv_cxx_compile_cxx0x_gxx, + [AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + AC_TRY_COMPILE([ + template <typename T> + struct check + { + static_assert(sizeof(int) <= sizeof(T), "not big enough"); + }; + + typedef check<check<bool>> right_angle_brackets; + + int a; + decltype(a) b; + + typedef check<int> check_type; + check_type c; + check_type&& cr = c;],, + ac_cv_cxx_compile_cxx0x_gxx=yes, ac_cv_cxx_compile_cxx0x_gxx=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + + if test "$ac_cv_cxx_compile_cxx0x_native" = yes || + test "$ac_cv_cxx_compile_cxx0x_cxx" = yes || + test "$ac_cv_cxx_compile_cxx0x_gxx" = yes; then + AC_DEFINE(HAVE_STDCXX_0X,,[Define if g++ supports C++0x features. ]) + fi +]) +</pre> + + +<p>Check for library coverage of the C++0xstandard. +</p> + +<pre style="background: #c0c0c0"> + +# AC_HEADER_STDCXX_0X +AC_DEFUN([AC_HEADER_STDCXX_0X], [ + AC_CACHE_CHECK(for ISO C++ 0x include files, + ac_cv_cxx_stdcxx_0x, + [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) + AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + + AC_TRY_COMPILE([ + #include <cassert> + #include <ccomplex> + #include <cctype> + #include <cerrno> + #include <cfenv> + #include <cfloat> + #include <cinttypes> + #include <ciso646> + #include <climits> + #include <clocale> + #include <cmath> + #include <csetjmp> + #include <csignal> + #include <cstdarg> + #include <cstdbool> + #include <cstddef> + #include <cstdint> + #include <cstdio> + #include <cstdlib> + #include <cstring> + #include <ctgmath> + #include <ctime> + #include <cwchar> + #include <cwctype> + + #include <algorithm> + #include <array> + #include <bitset> + #include <complex> + #include <deque> + #include <exception> + #include <fstream> + #include <functional> + #include <iomanip> + #include <ios> + #include <iosfwd> + #include <iostream> + #include <istream> + #include <iterator> + #include <limits> + #include <list> + #include <locale> + #include <map> + #include <memory> + #include <new> + #include <numeric> + #include <ostream> + #include <queue> + #include <random> + #include <regex> + #include <set> + #include <sstream> + #include <stack> + #include <stdexcept> + #include <streambuf> + #include <string> + #include <tuple> + #include <typeinfo> + #include <type_traits> + #include <unordered_map> + #include <unordered_set> + #include <utility> + #include <valarray> + #include <vector> + ],, + ac_cv_cxx_stdcxx_0x=yes, ac_cv_cxx_stdcxx_0x=no) + AC_LANG_RESTORE + CXXFLAGS="$ac_save_CXXFLAGS" + ]) + if test "$ac_cv_cxx_stdcxx_0x" = yes; then + AC_DEFINE(STDCXX_0X_HEADERS,,[Define if ISO C++ 0x header files are present. ]) + fi +]) +</pre> + +<p>As is the case for TR1 support, these autoconf macros can be made for a finer-grained, per-header-file check. For <unordered_map> +</p> + +<pre style="background: #c0c0c0"> + +# AC_HEADER_UNORDERED_MAP +AC_DEFUN([AC_HEADER_UNORDERED_MAP], [ + AC_CACHE_CHECK(for unordered_map, + ac_cv_cxx_unordered_map, + [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) + AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + AC_TRY_COMPILE([#include <unordered_map>], [using std::unordered_map;], + ac_cv_cxx_unordered_map=yes, ac_cv_cxx_unordered_map=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_unordered_map" = yes; then + AC_DEFINE(HAVE_UNORDERED_MAP,,[Define if unordered_map is present. ]) + fi +]) +</pre> + +<pre style="background: #c0c0c0"> +# AC_HEADER_UNORDERED_SET +AC_DEFUN([AC_HEADER_UNORDERED_SET], [ + AC_CACHE_CHECK(for unordered_set, + ac_cv_cxx_unordered_set, + [AC_REQUIRE([AC_COMPILE_STDCXX_0X]) + AC_LANG_SAVE + AC_LANG_CPLUSPLUS + ac_save_CXXFLAGS="$CXXFLAGS" + CXXFLAGS="$CXXFLAGS -std=gnu++0x" + AC_TRY_COMPILE([#include <unordered_set>], [using std::unordered_set;], + ac_cv_cxx_unordered_set=yes, ac_cv_cxx_unordered_set=no) + CXXFLAGS="$ac_save_CXXFLAGS" + AC_LANG_RESTORE + ]) + if test "$ac_cv_cxx_unordered_set" = yes; then + AC_DEFINE(HAVE_UNORDERED_SET,,[Define if unordered_set is present. ]) + fi +]) +</pre> + + +<h5> +Container iterator_type is not necessarily container value_type* +</h5> + + +<hr /> +<h3 class="left"> + <a name="v4">Fourth, and future</a> +</h3> + +<hr /> +<h3 class="left"> + <a name="Links">Links</a> +</h3> + +<p> +<a href="http://www.kegel.com/gcc/gcc4.html">Migrating to gcc-4.1</a>, by Dan Kegel. +</p> + +<p> +<a href="http://lists.debian.org/debian-gcc/2006/03/msg00405.html">Building the whole Debian archive with GCC 4.1: a summary</a>, by Martin Michlmayr +</p> + +<p> +<a href="http://annwm.lbl.gov/~leggett/Atlas/gcc-3.2.html">Migration guide for GCC-3.2</a> +</p> + +</body> +</html> + diff --git a/libstdc++-v3/docs/html/17_intro/howto.html b/libstdc++-v3/docs/html/17_intro/howto.html index d3bd6dfe393..3e1bba08acb 100644 --- a/libstdc++-v3/docs/html/17_intro/howto.html +++ b/libstdc++-v3/docs/html/17_intro/howto.html @@ -34,123 +34,309 @@ <hr /> <h1>Contents</h1> <ul> - <li><a href="#2.1">Header Files</a></li> - <li><a href="#5">Implementation specific behavior</a></li> + <li><a href="#2.0">Header Files</a></li> + <li><a href="#3.0">Namespaces</a></li> <li><a href="#6">Macros</a></li> - <li><a href="#3">Multithreading</a></li> + <li><a href="#5">Implementation specific behavior</a></li> + <li><a href="#7">Multithreading</a></li> </ul> <hr /> <!-- ####################################################### --> -<h2><a name="2.1">Header Files</a></h2> - <p>The C++ standard specifies 50 header files that must be +<h2><a name="2.0">Header Files</a></h2> + <p>The C++ standard specifies the entire set of header files that must be available to all hosted implementations. Actually, the word "files" is a misnomer, since the contents of the headers don't necessarily have to be in any kind of external file. The - only rule is that when one <code>#include</code>'s a certain header, the - contents of that header, as defined by the Standard, become + only rule is that when one <code>#include</code>'s a header, the + contents of that header become available, no matter how. </p> -<p>C++98/03 include files: +<p>That said, in practice files are used.</p> + +<p> There are two main types of include files: header files related to +a specific version of the ISO C++ standard (called Standard Headers), +and all others (TR1, C++ ABI, and Extensions).</p> + +<p>Two dialects of standard headers are supported, corresponding to +the 1998 standard as updated for 2003, and the draft of the upcoming +200x standard. +</p> + +<p>C++98/03 include files. These are available in the default compilation mode, ie <code>-std=c++98</code> or <code>-std=gnu++98</code>. </p> -<pre> -C++ Library Headers -algorithm ios new stack -bitset iosfwd numeric stdexcept -complex iostream ostream streambuf - istream queue string -deque iterator -exception limits typeinfo -fstream list set -functional locale map -iomanip memory sstream - -C++ Headers for C Library Facilities -cassert cfloat cmath cstddef -ccomplex csetjmp cstdio ctime -cctype ciso646 csignal -cerrno climits cstdarg cstdlib cwchar - clocale cstring cwctype -</pre> -<p>C++0x include files: +<center><table border="1"><caption>C++98 Library Headers</caption> +<tr><td><algorithm></td><td><iomanip></td><td><list></td><td><ostream></td><td><streambuf></td></tr> +<tr><td><bitset></td><td><ios></td><td><locale></td><td><queue></td><td><string></td></tr> +<tr><td><complex></td><td><iosfwd></td><td><map></td><td><set></td><td><typeinfo></td></tr> +<tr><td><deque></td><td><iostream></td><td><memory></td><td><sstream></td><td><utility></td></tr> +<tr><td><exception></td><td><istream></td><td><new></td><td><stack></td><td><valarray></td></tr> +<tr><td><fstream></td><td><iterator></td><td><numeric></td><td><stdexcept></td><td><vector></td></tr> +<tr><td><functional></td><td><limits></td></tr> +</table></center> + +<p></p> + +<center><table border="1"><caption>C++98 Headers for C Library Facilities</caption> +<tr><td><cassert></td><td><ciso646></td><td><csetjmp></td><td><cstdio></td><td><ctime></td></tr> +<tr><td><cctype></td><td><climits></td><td><csignal></td><td><cstdlib></td><td><cwchar></td></tr> +<tr><td><cerrno></td><td><clocale></td><td><cstdarg></td><td><cstring></td><td><cwctype></td></tr> +<tr><td><cfloat></td><td><cmath></td><td><cstddef></td></tr> +</table></center> + +<p>C++0x include files. These are only available in C++0x compilation mode, ie <code>-std=c++0x</code> or <code>-std=gnu++0x</code>. </p> + +<center><table border="1"><caption>C++0x Library Headers</caption> +<tr><td><algorithm></td><td><iomanip></td><td><locale></td><td><regex></td><td><tuple></td></tr> +<tr><td><array></td><td><ios></td><td><map></td><td><set></td><td><typeinfo></td></tr> +<tr><td><bitset></td><td><iosfwd></td><td><memory></td><td><sstream></td><td><type_traits></td></tr> +<tr><td><complex></td><td><iostream></td><td><new></td><td><stack></td><td><unordered_map></td></tr> +<tr><td><deque></td><td><istream></td><td><numeric></td><td><stdexcept></td><td><unordered_set></td></tr> +<tr><td><exception></td><td><iterator></td><td><ostream></td><td><streambuf></td><td><utility></td></tr> +<tr><td><fstream></td><td><limits></td><td><queue></td><td><string></td><td><valarray></td></tr> +<tr><td><functional></td><td><list></td><td><random></td><td><system_error></td><td><vector></td></tr> +</table></center> + +<p></p> + +<center><table border="1"><caption>C++0x Headers for C Library Facilities</caption> +<tr><td><cassert></td><td><cfloat></td><td><cmath></td><td><cstddef></td><td><ctgmath></td></tr> +<tr><td><ccomplex></td><td><cinttypes></td><td><csetjmp></td><td><cstdint></td><td><ctime></td></tr> +<tr><td><cctype></td><td><ciso646></td><td><csignal></td><td><cstdio></td><td><cuchar></td></tr> +<tr><td><cerrno></td><td><climits></td><td><cstdarg></td><td><cstdlib></td><td><cwchar></td></tr> +<tr><td><cfenv></td><td><clocale></td><td><cstdbool></td><td><cstring></td><td><cwctype></td></tr> +</table></center> + + +<p>In addition, TR1 includes as: +</p> + +<center><table border="1"><caption>TR1 Library Headers</caption> +<tr><td><tr1/array></td><td><tr1/memory></td><td><tr1/regex></td><td><tr1/type_traits></td><td><tr1/unordered_set></td></tr> +<tr><td><tr1/complex></td><td><tr1/random></td><td><tr1/tuple></td><td><tr1/unordered_map></td><td><tr1/utility></td></tr> +<tr><td><tr1/functional></td></tr> +</table></center> + +<p></p> + +<center><table border="1"><caption>TR1 Headers for C Library Facilities</caption> +<tr><td><tr1/cmath></td><td><tr1/cfloat></td><td><tr1/cstdarg></td><td><tr1/cstdio></td><td><tr1/ctime></td></tr> +<tr><td><tr1/ccomplex></td><td><tr1/cinttypes></td><td><tr1/cstdbool></td><td><tr1/cstdlib></td><td><tr1/cwchar></td></tr> +<tr><td><tr1/cfenv></td><td><tr1/climits></td><td><tr1/cstdint></td><td><tr1/ctgmath></td><td><tr1/cwctype><td></tr> +</table></center> + +<p>Also included are files for the C++ ABI interface: +</p> +<center><table border="1"><caption>C++ ABI Headers</caption> +<tr><td><cxxabi.h></td><td><cxxabi_forced.h></td></tr> +</table></center> + +<p>And a large variety of extensions. +</p> + +<center><table border="1"><caption>Extension Headers</caption> +<tr><td><ext/algorithm></td><td><ext/debug_allocator.h></td><td><ext/mt_allocator.h></td><td><ext/pod_char_traits.h></td><td><ext/stdio_sync_filebuf.h></td></tr> +<tr><td><ext/array_allocator.h></td><td><ext/enc_filebuf.h></td><td><ext/new_allocator.h></td><td><ext/pool_allocator.h></td><td><ext/throw_allocator.h></td></tr> +<tr><td><ext/atomicity.h></td><td><ext/functional></td><td><ext/numeric></td><td><ext/rb_tree></td><td><ext/typelist.h><td></tr> +<tr><td><ext/bitmap_allocator.h></td><td><ext/iterator></td><td><ext/numeric_traits.h></td><td><ext/rope></td><td><ext/type_traits.h></td></tr> +<tr><td><ext/codecvt_specializations.h></td><td><ext/malloc_allocator.h></td><td><ext/pb_ds/assoc_container.h></td><td><ext/slist></td><td><ext/vstring.h></td></tr> +<tr><td><ext/concurrence.h></td><td><ext/memory></td><td><ext/pb_ds/priority_queue.h></td><td><ext/stdio_filebuf.h></td></tr> +</table></center> + +<p></p> + +<center><table border="1"><caption>Extension Debug Headers</caption> +<tr><td><debug/bitset></td><td><debug/list></td><td><debug/set></td><td><debug/unordered_map></td><td><debug/vector></td></tr> +<tr><td><debug/deque></td><td><debug/map></td><td><debug/string></td><td><debug/unordered_set></td></tr> +</table></center> + +<p></p> + +<center><table border="1"><caption>Extension Parallel Headers</caption> +<tr><td><parallel/algorithm></td><td><parallel/numeric></td></tr> +</table></center> + +<hr /> +<h2><a name="2.1">Recipes for mixing headers</code></a></h2> + +<p> A few simple rules. +</p> + +<p>First, mixing different dialects of the standard headers is not +possible. It's an all-or-nothing affair. Thus, code like +</p> + <pre> -C++ Library Headers -algorithm ios new stack -array iosfwd numeric stdexcept -bitset iostream ostream streambuf -complex istream queue string -deque iterator random system_error -exception limits regex tuple -fstream list set type_traits -functional locale map typeinfo -iomanip memory sstream - -C++ Headers for C Library Facilities -cassert cfloat cmath cstddef ctgmath -ccomplex cinttypes csetjmp cstdio ctime -cctype ciso646 csignal cstdint cuchar -cerrno climits cstdarg cstdlib cwchar -cfenv clocale cstdbool cstring cwctype +#include <array> +#include <functional> </pre> -<p>In addition, TR1 includes as: +<p>Implies C++0x mode. To use the entities in <array>, the C++0x +compilation mode must be used, which implies the C++0x functionality +(and deprecations) in <functional> will be present. +</p> + +<p>Second, the other headers can be included with either dialect of +the standard headers, although features and types specific to C++0x +are still only enabled when in C++0x compilation mode. So, to use +rvalue references with <code>__gnu_cxx::vstring</code>, or to use the +debug-mode versions of <code>std::unordered_map</code>, one must use +the <code>std=gnu++0x</code> compiler flag. (Or <code>std=c++0x</code>, of course.) </p> + +<p>A special case of the second rule is the mixing of TR1 and C++0x +facilities. It is possible (although not especially prudent) to +include both the TR1 version and the C++0x version of header in the +same translation unit: +</p> + <pre> -C++ Library Headers -tr1/array, tr1/complex, tr1/functional, tr1/memory, tr1/random, -tr1/regex, tr1/tuple, tr1/type_traits, tr1/unordered_map, -tr1/unordered_set, tr1/utility - -C++ Headers for C Library Facilities -tr1/cmath, tr1/ccomplex, tr1/cfenv, tr1/cfloat, tr1/cinttypes, -tr1/climits, tr1/cstdarg, tr1/cstdbool, tr1/cstdint, tr1/cstdio, -tr1/cstdlib, tr1/ctgmath, tr1/ctime, tr1/cwchar, tr1/cwctype - -C++ Compatibility Headers for C Library Facilities -tr1/complex.h, tr1/ctype.h, tr1/float.h, tr1/limits.h, tr1/math.h, -tr1/stdarg.h, tr1/stdbool.h, tr1/stdint.h, tr1/stdio.h, tr1/stdlib.h, -tr1/tgmath.h, tr1/wchar.h, tr1/wctype.h +#include <tr1/type_traits> +#include <type_traits> </pre> +<p> Several parts of C++0x diverge quite substantially from TR1 predecessors. +</p> + + <hr /> -<h2><a name="2.2">Headers and <code>namespace std::</code></a></h2> +<h2><a name="2.2">The C Headers and <code>namespace std</code></a></h2> <p> - You should not use the C-headers (except for system-level - headers) from C++ programs. Instead, you should use a set of - headers that are named by prepending 'c' and, as usual, - omitting the extension (.h). For example, instead of using - <tt><math.h></tt>, you - should use <tt><cmath></tt>. In some cases this has - the advantage that the C++-header is more standardized than - the C-header (i.e. <tt><ctime></tt> (almost) - corresponds to either <tt><time.h></tt> or <tt><sys/time.h></tt>). - - The standard specifies that if you include the C-style header - (<tt><math.h></tt> in - this case), the symbols will be available both in the global - namespace and in namespace <code>std::</code> (but - libstdc++ does not yet have fully compliant headers) On the - other hand, if you include only the new header (i.e. <tt><cmath></tt>), the symbols - will only be defined in namespace <code>std::</code> - (and macros will be converted to inline-functions). + The standard specifies that if one includes the C-style header + (<math.h> in this case), the symbols will be available + in the global namespace and perhaps in + namespace <code>std::</code> (but this is no longer a firm + requirement.) One the other hand, including the C++-style + header (<cmath>) guarantees that the entities will be + found in namespace std and perhaps in the global namespace. </p> -<p>FIXME: this is no longer accurate.</p> - <p> - For more information on this, and for information on how the - GNU C++ implementation might reuse ("shadow") the C - library-functions, have a look at <a href="http://www.cantrip.org/cheaders.html" target="_top"> - www.cantrip.org</a>. - </p> +Usage of C++-style headers is recommended, as then +C-linkage names can be disambiguated by explicit qualification, such +as by <code>std::abort</code>. In addition, the C++-style headers can +use function overloading to provide a simpler interface to certain +families of C-functions. For instance in <cmath>, the +function <code>std::sin</code> has overloads for all the builtin +floating-point types. This means that <code>std::sin</code> can be +used uniformly, instead of a combination +of <code>std::sinf</code>, <code>std::sin</code>, +and <code>std::sinl</code>. +</p> + +<hr /> +<h2><a name="2.3">Precompiled Headers</a></h2> + +<p>There are three base header files that are provided. They can be +used to precompile the standard headers and extensions into binary +files that may the be used to speed compiles that use these headers. +</p> + + +<ul> +<li>stdc++.h +<p>Includes all standard headers. Actual content varies depending on +language dialect. +</p> +</li> + +<li>stdtr1c++.h +<p>Includes all of <stdc++.h>, and adds all the TR1 headers. +</p> +</li> + +<li>extc++.h +<p>Includes all of <stdtr1c++.h>, and adds all the Extension headers. +</p></li> +</ul> + +<p>How to construct a .gch file from one of these base header files.</p> + +<p>First, find the include directory for the compiler. One way to do +this is:</p> + +<pre> +g++ -v hello.cc + +#include <...> search starts here: + /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0 +... +End of search list. +</pre> + + +<p>Then, create a precompiled header file with the same flags that +will be used to compile other projects.</p> + +<pre> +g++ -Winvalid-pch -x c++-header -g -O2 -o ./stdc++.h.gch /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/x86_64-unknown-linux-gnu/bits/stdc++.h +</pre> + +<p>The resulting file will be quite large: the current size is around +thirty megabytes. </p> + +<p>How to use the resulting file.</p> + +<pre> +g++ -I. -include stdc++.h -H -g -O2 hello.cc +</pre> + +<p>Verification that the PCH file is being used is easy:</p> + +<pre> +g++ -Winvalid-pch -I. -include stdc++.h -H -g -O2 hello.cc -o test.exe +! ./stdc++.h.gch +. /mnt/share/bld/H-x86-gcc.20071201/include/c++/4.3.0/iostream +. /mnt/share/bld/H-x86-gcc.20071201include/c++/4.3.0/string +</pre> + +<p>The exclamation point to the left of the <code>stdc++.h.gch</code> listing means that the generated PCH file was used, and thus the </p> +<p></p> + +<p> Detailed information about creating precompiled header files can be found in the GCC <a href="http://gcc.gnu.org/onlinedocs/gcc/Precompiled-Headers.html">documentation</a>. +</p> + <hr /> -<h2><a name="2.5">Namespace <code>std::</code></a></h2> +<h2><a name="3.0">Namespaces</a></h2> + + +<p> There are three main namespaces. +</p> + +<ul> +<li>std +<p>The ISO C++ standards specify that "all library entities are defined +within namespace std." This includes namepaces nested +within <code>namespace std</code>, such as <code>namespace +std::tr1</code>. +</p> +</li> +<li>abi +<p>Specified by the C++ ABI. This ABI specifies a number of type and +function APIs supplemental to those required by the ISO C++ Standard, +but necessary for interoperability. +</p> +</li> + +<li>__gnu_ +<p>Indicating one of several GNU extensions. Choices +include <code>__gnu_cxx</code>, <code>__gnu_debug</code>, <code>__gnu_parallel</code>, +and <code>__gnu_pbds</code>. +</p></li> +</ul> + +<p> A complete list of implementation namespaces (including namespace contents) is available in the generated source <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/namespaces.html">documentation</a>. +</p> + + +<hr /> +<h2><a name="3.1">Namespace <code>std::</code></a></h2> <p> One standard requirement is that the library components are defined @@ -167,37 +353,46 @@ should not be used in a global context, like header files. qualified name</i></span> for each library symbol (i.e. <code>std::string</code>, <code>std::cout</code>) Always can be used, and usually enhanced, by strategic use of typedefs. (In the -cases where the qualified verbage becomes unweidly.) +cases where the qualified verbiage becomes unwieldy.) </p></li> </ul></div> <hr /> -<h2><a name="2.6">Using namespace composition</a></h2> +<h2><a name="3.2">Using namespace composition</a></h2> <p> - <a href="http://gtkmm.sourceforge.net" target="_top">Gtk--</a> defines - most of its classes in namespace Gtk::. Thus, it was possible to - adapt Gtk-- to namespace std:: by using a C++-feature called +Best practice in programming suggests sequestering new data or +functionality in a sanely-named, unique namespace whenever +possible. This is considered an advantage over dumping everything in +the global namespace, as then name look-up can be explicitly enabled or +disabled as above, symbols are consistently mangled without repetitive +naming prefixes or macros, etc. +</p> + +<p>For instance, consider a project that defines most of its classes in <code>namespace gtk</code>. It is possible to + adapt <code>namespace gtk</code> to <code>namespace std</code> by using a C++-feature called <span class="emphasis"><i>namespace composition</i></span>. This is what happens if - you put a <span class="emphasis"><i>using</i></span>-declaration into a + a <span class="emphasis"><i>using</i></span>-declaration is put into a namespace-definition: the imported symbol(s) gets imported into the currently active namespace(s). For example: </p> - <pre class="programlisting"> - namespace Gtk { - using std::string; - class Window { ... } - } - </pre> +<pre class="programlisting"> +namespace gtk +{ + using std::string; + using std::tr1::array; + + class Window { ... }; +} +</pre> <p> In this example, <code>std::string</code> gets imported into - namespace Gtk::. The result is that you don't have to use - <code>std::string</code> in this header, but still + <code>namespace gtk</code>. The result is that use of + <code>std::string</code> inside namespace gtk can just use <code>string</code>, without the explicit qualification. + As an added bonus, <code>std::string</code> does not get imported into - the global namespace (::) unless the user does - <code>using namespace Gtk;</code> (which is not recommended - practice for Gtk--, so it is not a problem). Additionally, the - <code>using</code>-declarations are wrapped in macros that + the global namespace. Additionally, a more elaborate arrangement can be made for backwards compatibility and portability, whereby the + <code>using</code>-declarations can wrapped in macros that are set based on autoconf-tests to either "" or i.e. <code>using std::string;</code> (depending on whether the system has libstdc++ in <code>std::</code> or not). (ideas from @@ -206,7 +401,103 @@ cases where the qualified verbage becomes unweidly.) </p> <hr /> -<h2><a name="3">The Standard C++ library and multithreading</a></h2> +<h2><a name="6">Macros for libstdc++</a></h2> + + <p>All pre-processor switches and configurations are all gathered + in the file <code>c++config.h</code>, which is generated during + the libstdc++ configuration and build process, and included by + files part of the public libstdc++ API. Most of these macros + should not be used by consumers of libstdc++, and are reserved + for internal implementation use. <strong>These macros cannot be + redefined</strong>. However, a select handful of these macro + control libstdc++ extensions and extra features, or provide + versioning information for the API, and are able to be used. + </p> + + <p>All library macros begin with <code>_GLIBCXX_</code> (except for + versions 3.1.x to 3.3.x, which use <code>_GLIBCPP_</code>). + </p> + + <p>Below is the macro which users may check for library version + information. </p> + + <dl> + <dt><code>__GLIBCXX__</code></dt> <dd>The current version of + libstdc++ in compressed ISO date format, form of an unsigned + long. For details on the value of this particular macro for a + particular release, please consult this <a href="abi.html"> + document</a>.</dd> </dl> + + <p>Below are the macros which users may change with #define/#undef or + with -D/-U compiler flags. The default state of the symbol is + listed.</p> + + <p>"Configurable" (or "Not configurable") means + that the symbol is initially chosen (or not) based on + --enable/--disable options at library build and configure time + (documented <a href="../configopts.html">here</a>), with the + various --enable/--disable choices being translated to + #define/#undef). + </p> + + <p> "ABI" means that changing from the default value may + mean changing the ABI of compiled code. In other words, these + choices control code which has already been compiled (i.e., in a + binary such as libstdc++.a/.so). If you explicitly #define or + #undef these macros, the <em>headers</em> may see different code + paths, but the <em>libraries</em> which you link against will not. + Experimenting with different values with the expectation of + consistent linkage requires changing the config headers before + building/installing the library. + </p> + + <dl> + <dt><code>_GLIBCXX_DEPRECATED</code></dt> + <dd>Defined by default. Not configurable. ABI-changing. Turning this off + removes older ARM-style iostreams code, and other anachronisms + from the API. This macro is dependent on the version of the + standard being tracked, and as a result may give different results for + <code>-std=c++98</code> and <code>-std=c++0x</code>. This may + be useful in updating old C++ code which no longer meet the + requirements of the language, or for checking current code + against new language standards. </dd> + + <dt><code>_GLIBCXX_FORCE_NEW</code></dt> <dd>Undefined by + default. When defined, memory allocation and allocators controlled + by libstdc++ call operator new/delete without caching and + pooling. Configurable via + <code>--enable-libstdcxx-allocator</code>. ABI-changing. + </dd> + + + <dt><code>_GLIBCXX_CONCEPT_CHECKS</code></dt> <dd>Undefined by + default. Configurable via <code>--enable-concept-checks</code>. + When defined, performs compile-time checking on certain template + instantiations to detect violations of the requirements of the + standard. This is described in more detail <a + href="../19_diagnostics/howto.html#3">here</a>.</dd> + + <dt><code>_GLIBCXX_DEBUG</code></dt> + <dd>Undefined by default. When defined, compiles + user code using the <a href="../ext/debug.html#safe">libstdc++ debug + mode</a>. + </dd> + <dt><code>_GLIBCXX_DEBUG_PEDANTIC</code></dt> + <dd>Undefined by default. When defined while + compiling with the <a href="../ext/debug.html#safe">libstdc++ debug + mode</a>, makes the debug mode extremely picky by making the use + of libstdc++ extensions and libstdc++-specific behavior into + errors. + </dd> + <dt><code>_GLIBCXX_PARALLEL</code></dt> + <dd>Undefined by default. When defined, compiles + user code using the <a href="../ext/parallel_mode.html">libstdc++ parallel + mode</a>. + </dd> + </dl> + +<hr /> +<h2><a name="7">The Standard C++ library and multithreading</a></h2> <p>This section discusses issues surrounding the proper compilation of multithreaded applications which use the Standard C++ library. This information is GCC-specific since the C++ @@ -419,107 +710,11 @@ cases where the qualified verbage becomes unweidly.) <a href="../faq/index.html">to the FAQ</a>. </p> -<hr /> -<h2><a name="6">Macros for libstdc++</a></h2> - - <p>All pre-processor switches and configurations are all gathered - in the file <code>c++config.h</code>, which is generated during - the libstdc++ configuration and build process, and included by - files part of the public libstdc++ API. Most of these macros - should not be used by consumers of libstdc++, and are reserved - for internal implementation use. <strong>These macros cannot be - redefined</strong>. However, a select handful of these macro - control libstdc++ extensions and extra features, or provide - versioning information for the API, and are able to be used. - </p> - - <p>All library macros begin with <code>_GLIBCXX_</code> (except for - versions 3.1.x to 3.3.x, which use <code>_GLIBCPP_</code>). - </p> - - <p>Below is the macro which users may check for library version - information. </p> - - <dl> - <dt><code>__GLIBCXX__</code></dt> <dd>The current version of - libstdc++ in compressed ISO date format, form of an unsigned - long. For details on the value of this particular macro for a - particular release, please consult this <a href="abi.html"> - document</a>.</dd> </dl> - - <p>Below are the macros which users may change with #define/#undef or - with -D/-U compiler flags. The default state of the symbol is - listed.</p> - - <p>"Configurable" (or "Not configurable") means - that the symbol is initially chosen (or not) based on - --enable/--disable options at library build and configure time - (documented <a href="../configopts.html">here</a>), with the - various --enable/--disable choices being translated to - #define/#undef). - </p> - - <p> "ABI" means that changing from the default value may - mean changing the ABI of compiled code. In other words, these - choices control code which has already been compiled (i.e., in a - binary such as libstdc++.a/.so). If you explicitly #define or - #undef these macros, the <em>headers</em> may see different code - paths, but the <em>libraries</em> which you link against will not. - Experimenting with different values with the expectation of - consistent linkage requires changing the config headers before - building/installing the library. - </p> - - <dl> - <dt><code>_GLIBCXX_DEPRECATED</code></dt> - <dd>Defined by default. Not configurable. ABI-changing. Turning this off - removes older ARM-style iostreams code, and other anachronisms - from the API. This macro is dependent on the version of the - standard being tracked, and as a result may give different results for - <code>-std=c++98</code> and <code>-std=c++0x</code>. This may - be useful in updating old C++ code which no longer meet the - requirements of the language, or for checking current code - against new language standards. </dd> - - <dt><code>_GLIBCXX_FORCE_NEW</code></dt> <dd>Undefined by - default. When defined, memory allocation and allocators controlled - by libstdc++ call operator new/delete without caching and - pooling. Configurable via - <code>--enable-libstdcxx-allocator</code>. ABI-changing. - </dd> - - - <dt><code>_GLIBCXX_CONCEPT_CHECKS</code></dt> <dd>Undefined by - default. Configurable via <code>--enable-concept-checks</code>. - When defined, performs compile-time checking on certain template - instantiations to detect violations of the requirements of the - standard. This is described in more detail <a - href="../19_diagnostics/howto.html#3">here</a>.</dd> - - <dt><code>_GLIBCXX_DEBUG</code></dt> - <dd>Undefined by default. When defined, compiles - user code using the <a href="../ext/debug.html#safe">libstdc++ debug - mode</a>. - </dd> - <dt><code>_GLIBCXX_DEBUG_PEDANTIC</code></dt> - <dd>Undefined by default. When defined while - compiling with the <a href="../ext/debug.html#safe">libstdc++ debug - mode</a>, makes the debug mode extremely picky by making the use - of libstdc++ extensions and libstdc++-specific behavior into - errors. - </dd> - <dt><code>_GLIBCXX_PARALLEL</code></dt> - <dd>Undefined by default. When defined, compiles - user code using the <a href="../ext/parallel_mode.html">libstdc++ parallel - mode</a>. - </dd> - <!-- <dt><code></code></dt> <dd> </dd> --> - </dl> <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> diff --git a/libstdc++-v3/docs/html/18_support/howto.html b/libstdc++-v3/docs/html/18_support/howto.html index 87dd8a5342e..dc5bc2a067d 100644 --- a/libstdc++-v3/docs/html/18_support/howto.html +++ b/libstdc++-v3/docs/html/18_support/howto.html @@ -281,9 +281,6 @@ </p> <pre> std::set_terminate(std::abort);</pre> - <p>Return <a href="#top">to top of page</a> or - <a href="../faq/index.html">to the FAQ</a>. - </p> <p> This function will attempt to write to stderr. If your application @@ -292,6 +289,11 @@ unspecified manner. </p> + <p>Return <a href="#top">to top of page</a> or + <a href="../faq/index.html">to the FAQ</a>. + </p> + + <hr /> <h2><a name="5">Dynamic memory management</a></h2> <p>There are six flavors each of <code>new</code> and diff --git a/libstdc++-v3/docs/html/20_util/allocator.html b/libstdc++-v3/docs/html/20_util/allocator.html index 409c08b870c..951c12df36d 100644 --- a/libstdc++-v3/docs/html/20_util/allocator.html +++ b/libstdc++-v3/docs/html/20_util/allocator.html @@ -84,34 +84,47 @@ </h3> <p>The easiest way of fulfilling the requirements is to call operator new each time a container needs memory, and to call operator delete each - time the container releases memory. <strong>BUT</strong> - <a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">this - method is horribly slow</a>. - </p> - <p>Or we can keep old memory around, and reuse it in a pool to save time. - The old libstdc++-v2 used a memory pool, and so do we. As of 3.0, - <a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00136.html">it's - on by default</a>. The pool is shared among all the containers in the - program: when your program's std::vector<int> gets cut in half - and frees a bunch of its storage, that memory can be reused by the - private std::list<WonkyWidget> brought in from a KDE library - that you linked against. And we don't have to call operators new and - delete to pass the memory on, either, which is a speed bonus. - <strong>BUT</strong>... - </p> - <p>What about threads? No problem: in a threadsafe environment, the - memory pool is manipulated atomically, so you can grow a container in - one thread and shrink it in another, etc. <strong>BUT</strong> what - if threads in libstdc++ aren't set up properly? - <a href="../faq/index.html#5_6">That's been answered already</a>. - </p> - <p><strong>BUT</strong> what if you want to use your own allocator? What - if you plan on using a runtime-loadable version of malloc() which uses - shared telepathic anonymous mmap'd sections serializable over a - network, so that memory requests <em>should</em> go through malloc? - And what if you need to debug it? - </p> + time the container releases memory. This method may be + <a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00105.html">slower</a> + than caching the allocations and re-using previously-allocated + memory, but has the advantage of working correctly across a wide + variety of hardware and operating systems, including large + clusters. The <code>__gnu_cxx::new_allocator</code> implements + the simple operator new and operator delete semantics, while <code>__gnu_cxx::malloc_allocator</code> implements much the same thing, only with the C language functions <code>std::malloc</code> and <code>std::free</code>. + </p> + +<p> Another approach is to use intelligence within the allocator class +to cache allocations. This extra machinery can take a variety of +forms: a bitmap index, an index into an exponentially increasing +power-of-two-sized buckets, or simpler fixed-size pooling cache. The +cache is shared among all the containers in the program: when your +program's std::vector<int> gets cut in half and frees a bunch of +its storage, that memory can be reused by the private +std::list<WonkyWidget> brought in from a KDE library that you +linked against. And operators new and delete are not always called to +pass the memory on, either, which is a speed bonus. Examples of +allocators that use these techniques +are <code>__gnu_cxx::bitmap_allocator</code>, <code>__gnu_cxx::pool_allocator</code>, +and <code>__gnu_cxx::__mt_alloc</code>. +</p> +<p>Depending on the implementation techniques used, the underlying +operating system, and compilation environment, scaling caching +allocators can be tricky. In particular, order-of-destruction and +order-of-creation for memory pools may be difficult to pin down with +certainty, which may create problems when used with plugins or loading +and unloading shared objects in memory. As such, using caching +allocators on systems that do not +support <code>abi::__cxa_atexit</code> is not recommended. +</p> + + <p>Versions of libstdc++ prior to 3.4 cache allocations in a memory + pool, instead of passing through to call the global allocation + operators (ie, <code>__gnu_cxx::pool_allocator</code>). More + recent versions default to the + simpler <code>__gnu_cxx::new_allocator</code>. + </p> + <h3 class="left"> <a name="stdallocator">Implementation details of <code>std::allocator</code></a> </h3> @@ -335,6 +348,11 @@ <td><ext/array_allocator.h></td> <td>4.0.0</td> </tr> + <tr> + <td>__gnu_cxx::throw_allocator<T></td> + <td><ext/throw_allocator.h></td> + <td>4.2.0</td> + </tr> </table> <p>More details on each of these extension allocators follows. </p> @@ -371,6 +389,12 @@ size is checked, and assert() is used to guarantee they match. </p> </li> + <li><code>throw_allocator</code> + <p> Includes memory tracking and marking abilities as well as hooks for + throwing exceptinos at configurable intervals (including random, + all, none). + </p> + </li> <li><code>__pool_alloc</code> <p> A high-performance, single pool allocator. The reusable memory is shared among identical instantiations of this type. diff --git a/libstdc++-v3/docs/html/documentation.html b/libstdc++-v3/docs/html/documentation.html index 92ce87b065a..d2a736fb5d2 100644 --- a/libstdc++-v3/docs/html/documentation.html +++ b/libstdc++-v3/docs/html/documentation.html @@ -26,7 +26,7 @@ href="http://gcc.gnu.org/libstdc++">project</a> to implement the ISO annex D, extensions as described by TR1, and future C++ library standards still in progress. For those who want to see exactly how far the project has come, or just want the latest bleeding-edge code, the -up-to-date source is always publically available over anonymous SVN, +up-to-date source is always publicly available over anonymous SVN, and can be browsed over the <a href="http://gcc.gnu.org/svn.html">web</a>. </p> @@ -34,13 +34,6 @@ href="http://gcc.gnu.org/svn.html">web</a>. <p>Stable versions of libstdc++ are included with releases of <a href="http://gcc.gnu.org/releases.html">the GCC compilers</a>. </p> -<!-- - The list below is automatically generated. To make changes in the text, - edit the appropriate HOWTO file and run "make" in this directory. In - those files, you may reorder entries as you like, but DO NOT change the - "#number"s in anchors, for they are used elsewhere and in bookmarks. ---> -<!-- beginlist --> <ul> <li>Introduction <ul> @@ -77,26 +70,27 @@ href="http://gcc.gnu.org/svn.html">web</a>. <ul> <li>Header Files <ul> - <li><a href="17_intro/howto.html#2.1">Available headers</a></li> - <li><a href="17_intro/howto.html#2.2">Headers and <code>namespace std</code></a></li> - <li>Pre-compiled headers</li> + <li><a href="17_intro/howto.html#2.0">Available headers</a></li> + <li><a href="17_intro/howto.html#2.1">Mixing headers</a></li> + <li><a href="17_intro/howto.html#2.2">The C Headers and <code>namespace std</code></a></li> + <li><a href="17_intro/howto.html#2.3">Precompiled Headers</a></li> </ul> </li> <li>Namespaces <ul> - <li><a href="17_intro/howto.html#2.5">Namespace <code>std::</code></a></li> - <li><a href="17_intro/howto.html#2.6">Using namespace composition</a></li> + <li><a href="17_intro/howto.html#3.0">Available namespaces</li> + <li><a href="17_intro/howto.html#3.1">Namespace <code>std::</code></a></li> + <li><a href="17_intro/howto.html#3.2">Using namespace composition</a></li> </ul> </li> <li><a href="17_intro/howto.html#6">Macros</a></li> + <li>Command line options</li> <li>Concurrency <ul> - <li>Atomic Operations</li> - <li><a href="17_intro/howto.html#3">Thread safety overview</a></li> - <li><a href="faq/index.html#5_6">Is it thread safe?</a></li> + <li><a href="17_intro/howto.html#7">Thread safety history and evolution</a></li> <li><a href="23_containers/howto.html#3">Containers</a></li> <li><a href="27_io/howto.html#9">IO</a></li> </ul> @@ -122,8 +116,15 @@ href="http://gcc.gnu.org/svn.html">web</a>. <li>Diagnostics <ul> + <li>Exceptions + + <ul> <li>Exception class hierarchy</li> <li><a href="19_diagnostics/howto.html#1">Adding data to exceptions</a></li> + <li>Cancellation</li> + </ul> + </li> + <li><a href="19_diagnostics/howto.html#3">Concept checking</a></li> </ul> </li> @@ -248,6 +249,7 @@ href="http://gcc.gnu.org/svn.html">web</a>. </ul> </li> <li><a href="ext/../18_support/howto.html#6">Demangling</a></li> + <li><a href="ext/concurrence.html">Concurrency: Threads and Atomics</a></li> </ul> </li> @@ -277,6 +279,7 @@ href="http://gcc.gnu.org/svn.html">web</a>. <li><a href="17_intro/porting.html">Porting to new hardware or operating systems.</a></li> <li><a href="17_intro/abi.html">ABI Policy and Guidelines</a></li> <li><a href="17_intro/api.html">API Evolution and Deprecation History</a></li> + <li><a href="17_intro/backwards_compatibility.html">Backwards Compatibility</a></li> </ul> </li> diff --git a/libstdc++-v3/docs/html/ext/concurrence.html b/libstdc++-v3/docs/html/ext/concurrence.html new file mode 100644 index 00000000000..e621bc90f12 --- /dev/null +++ b/libstdc++-v3/docs/html/ext/concurrence.html @@ -0,0 +1,342 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html + PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> + <meta name="AUTHOR" content="bkoz@gcc.gnu.org (Benjamin Kosnik)" /> + <meta name="KEYWORDS" content="C++, libstdc++, MT, thread, pthread, mutex, loc, atomic" /> + <meta name="DESCRIPTION" content="Concurrency Support" /> + <meta name="GENERATOR" content="emacs and ten fingers" /> + <title>Concurrency Support</title> +<link rel="StyleSheet" href="lib3styles.css" type="text/css" /> +<link rel="Start" href="documentation.html" type="text/html" + title="GNU C++ Standard Library" /> +<link rel="Copyright" href="17_intro/license.html" type="text/html" /> +</head> +<body> + +<h1 class="centered"><a name="top">Concurrency Support</a></h1> + +<p class="fineprint"><em> + The latest version of this document is always available at + <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/concurrence.html"> + http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/concurrence.html</a>. +</em></p> + +<p><em> + To the <a href="http://gcc.gnu.org/libstdc++/">libstdc++ homepage</a>. +</em></p> + + +<!-- ####################################################### --> + +<hr /> + + +<p>The interface for concurrency support is divided into two files: +<ext/atomicity.h> which provides support for atomic operations, +and <ext/concurrence.h>, which provides mutex and lock objects +as well as compile-time data structures for querying thread +support.</p> + +<p>It is expected that support for concurrence will evolve into what +is specified in the draft C++0x standard.</p> + +<h3 class="left"> + <a name="atomic_api">Atomics Interface</a> +</h3> + +<p> +Two functions and one type form the base of atomic support. +</p> + + +<p>The type <code>_Atomic_word</code> is a signed integral type +supporting atomic operations. +</p> + +<p> +The two functions functions are: +</p> + +<pre> +_Atomic_word +__exchange_and_add_dispatch(volatile _Atomic_word*, int); + +void +__atomic_add_dispatch(volatile _Atomic_word*, int); +</pre> + +<p>Both of these functions are declared in the header file +<ext/atomicity.h>, and are in <code>namespace __gnu_cxx</code>. +</p> + +<ul> +<li> +<code> +__exchange_and_add_dispatch +</code> +<p>Adds the second argument's value to the first argument. Returns the old value. +</p> +</li> +<li> +<code> +__atomic_add_dispatch +</code> +<p>Adds the second argument's value to the first argument. Has no return value. +</p> +</li> +</ul> + +</p> +These functions forward to one of several specialized helper +functions, depending on the circumstances. For instance, +</p> + +<p> +<code> +__exchange_and_add_dispatch +</code> +</p> + +<p> +Calls through to either of: +</p> + +<ul> +<li><code>__exchange_and_add</code> +<p>Multi-thread version. Inlined if compiler-generated builtin atomics +can be used, otherwise resolved at link time to a non-builtin code +sequence. +</p> +</li> + +<li><code>__exchange_and_add_single</code> +<p>Single threaded version. Inlined.</p> +</li> +</ul> + +<p>However, only <code>__exchange_and_add_dispatch</code> +and <code>__atomic_add_dispatch</code> should be used. These functions +can be used in a portable manner, regardless of the specific +environment. They are carefully designed to provide optimum efficiency +and speed, abstracting out atomic accesses when they are not required +(even on hosts that support compiler intrinsics for atomic +operations.) +</p> + +<p> +In addition, there are two macros +</p> + +<p> +<code> +_GLIBCXX_READ_MEM_BARRIER +</code> +</p> +<p> +<code> +GLIBCXX_WRITE_MEM_BARRIER +</code> +</p> + +<p> +Which expand to the appropriate write and read barrier required by the +host hardware and operating system. +</p> + +<h3 class="left"> + <a name="pthread_api">Pthread Interface</a> +</h3> + +<p>A thin layer above IEEE 1003.1 (ie pthreads) is used to abastract +the thread interface for GCC. This layer is called "gthread," and is +comprised of one header file that wraps the host's default thread layer with +a POSIX-like interfaces. +</p> + +<p> The file <gthr-default.h> points to the deduced wrapper for +the current host. In libstdc++ implementation files, +<bits/gthr.h> is used to select the proper gthreads file. +</p> + +<p>Within libstdc++ sources, all calls to underlying thread functionality +use this layer. More detail as to the specific interface can be found in the source <a href="http://gcc.gnu.org/onlinedocs/libstdc++/latest-doxygen/gthr_8h-source.html">documentation</a>. +</p> + +<p>By design, the gthread layer is interoperable with the types, +functions, and usage found in the usual <pthread.h> file, +including <code>pthread_t</code>, <code>pthread_once_t</code>, <code>pthread_create</code>, +etc. +</p> + +<h3 class="left"> + <a name="concur_api">Concurrence Interface</a> +</h3> + +<p>The file <ext/concurrence.h> contains all the higher-level +constructs for playing with threads. In contrast to the atomics layer, +the concurrence layer consists largely of types. All types are defined within <code>namespace __gnu_cxx</code>. +</p> + +<p> +These types can be used in a portable manner, regardless of the +specific environment. They are carefully designed to provide optimum +efficiency and speed, abstracting out underlying thread calls and +accesses when compiling for single-threaded situations (even on hosts +that support multiple threads.) +</p> + +<p>The enumerated type <code>_Lock_policy</code> details the set of +available locking +policies: <code>_S_single</code>, <code>_S_mutex</code>, +and <code>_S_atomic</code>. +</p> + +<ul> +<li><code>_S_single</code> +<p>Indicates single-threaded code that does not need locking. +</p> + +</li> +<li><code>_S_mutex</code> +<p>Indicates multi-threaded code using thread-layer abstractions. +</p> +</li> +<li><code>_S_atomic</code> +<p>Indicates multi-threaded code using atomic operations. +</p> +</li> +</ul> + +<p>The compile-time constant <code>__default_lock_policy</code> is set +to one of the three values above, depending on characteristics of the +host environment and the current compilation flags. +</p> + +<p>Two more datatypes make up the rest of the +interface: <code>__mutex</code>, and <code>__scoped_lock</code>. +</p> + +<p> +</p> + +<p>The scoped lock idiom is well-discussed within the C++ +community. This version takes a <code>__mutex</code> reference, and +locks it during construction of <code>__scoped_locke</code> and +unlocks it during destruction. This is an efficient way of locking +critical sections, while retaining exception-safety. +</p> + +<p>Typical usage of the last two constructs is demonstrated as follows: +</p> + +<pre> +#include <ext/concurrence.h> + +namespace +{ + __gnu_cxx::__mutex safe_base_mutex; +} // anonymous namespace + +namespace other +{ + void + foo() + { + __gnu_cxx::__scoped_lock sentry(safe_base_mutex); + for (int i = 0; i < max; ++i) + { + _Safe_iterator_base* __old = __iter; + __iter = __iter->_M_next; + __old->_M_detach_single(); + } +} +</pre> + +<p>In this sample code, an anonymous namespace is used to keep +the <code>__mutex</code> private to the compilation unit, +and <code>__scoped_lock</code> is used to guard access to the critical +section within the for loop, locking the mutex on creation and freeing +the mutex as control moves out of this block. +</p> + +<p>Several exception classes are used to keep track of +concurrence-related errors. These classes +are: <code>__concurrence_lock_error</code>, <code>__concurrence_unlock_error</code>, <code>__concurrence_wait_error</code>, +and <code>__concurrence_broadcast_error</code>. +</p> + + + +<h3 class="left"> + <a name="atomic_impl">Details on builtin atomic support and library fallbacks</a> +</h3> + +<p>The functions for atomic operations described above are either +implemented via compiler intrinsics (if the underlying host is +capable) or by library fallbacks.</p> + +<p>Compiler intrinsics (builtins) are always preferred. However, as +the compiler builtins for atomics are not universally implemented, +using them directly is problematic, and can result in undefined +function calls. (An example of an undefined symbol from the use +of <code>__sync_fetch_and_add</code> on an unsupported host is a +missing reference to <code>__sync_fetch_and_add_4</code>.) +</p> + +<p>In addition, on some hosts the compiler intrinsics are enabled +conditionally, via the <code>-march</code> command line flag. This makes +usage vary depending on the target hardware and the flags used during +compile. +</p> + +<p> If builtins are possible, <code>_GLIBCXX_ATOMIC_BUILTINS</code> +will be defined. +</p> + + +<p>For the following hosts, intrinsics are enabled by default. +</p> + +<ul> + <li>alpha</li> + <li>ia64</li> + <li>powerpc</li> + <li>s390</li> +</ul> + +<p>For others, some form of <code>-march</code> may work. On +non-ancient x86 hardware, <code>-march=native</code> usually does the +trick.</p> + +<p> For hosts without compiler intrinsics, but with capable +hardware, hand-crafted assembly is selected. This is the case for the following hosts: +</p> + +<ul> + <li>cris</li> + <li>hppa</li> + <li>i386</li> + <li>i486</li> + <li>m48k</li> + <li>mips</li> + <li>sparc</li> +</ul> + +<p>And for the rest, a simulated atomic lock via pthreads. +</p> + +<p> Detailed information about compiler intrinsics for atomic operations can be found in the GCC <a href="http://gcc.gnu.org/onlinedocs/gcc/Atomic-Builtins.html"> documentation</a>. +</p> + +<p> More details on the library fallbacks from the porting <a href="http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/porting.html#Thread%20safety">section</a>. +</p> + + + +</body> +</html> + diff --git a/libstdc++-v3/docs/html/ext/howto.html b/libstdc++-v3/docs/html/ext/howto.html index 3171355ff87..2e88c660a61 100644 --- a/libstdc++-v3/docs/html/ext/howto.html +++ b/libstdc++-v3/docs/html/ext/howto.html @@ -74,18 +74,13 @@ 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 those SGI folks). + "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. </p> - <p>Okay, about those hashing classes... these classes 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. - </p> <p>Each of the associative containers map, multimap, set, and multiset have a counterpart which uses a <a href="http://www.sgi.com/tech/stl/HashFunction.html">hashing @@ -111,11 +106,13 @@ components, and if you aren't scared about the possibility of pathological cases, you'll probably get better performance from hash_map.</em></blockquote> - <p>(Side note: for those of you wondering, <strong>"Why wasn't a hash - table included in the Standard in the first #!$@ place?"</strong> - I'll give a quick answer: it was proposed, but too late and in too - unorganized a fashion.) + + <p>Okay, about the SGI hashing classes... these classes 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. </p> + <p>Return <a href="#top">to top of page</a> or <a href="../faq/index.html">to the FAQ</a>. </p> diff --git a/libstdc++-v3/docs/html/ext/sgiexts.html b/libstdc++-v3/docs/html/ext/sgiexts.html index 7f9b8c0c56d..64b8e3138c1 100644 --- a/libstdc++-v3/docs/html/ext/sgiexts.html +++ b/libstdc++-v3/docs/html/ext/sgiexts.html @@ -9,7 +9,7 @@ <meta name="KEYWORDS" content="libstdc++, libstdc++, GCC, g++, STL, SGI" /> <meta name="DESCRIPTION" content="SGI extensions preserved in libstdc++." /> <meta name="GENERATOR" content="vi and eight fingers" /> - <title>SGI extensions to the library in libstdc++</title> + <title>HP/SGI STL extensions</title> <link rel="StyleSheet" href="../lib3styles.css" type="text/css" /> <link rel="Start" href="../documentation.html" type="text/html" title="GNU C++ Standard Library" /> @@ -19,29 +19,29 @@ </head> <body> -<h1 class="centered"><a name="top">SGI extensions to the library in -libstdc++</a></h1> +<h1 class="centered"><a name="top">HP/SGI STL extensions</a></h1> -<p>This page describes the extensions that SGI made to their version of the - STL subset of the Standard C++ Library. For a time we - <a href="../faq/index.html#5_3">tracked and imported changes and updates - from most of the SGI STL</a>, up through their (apparently) final release. - Their extensions were mostly preserved. +<p>This page describes the extensions that SGI made to the STL subset + of the Standard C++ Library, which also includes work from the + originating HP codebase. This work is the basis for much of + libstdc++, and where possible these extensions have been + preserved. </p> -<p>They are listed according to the chapters of the library that they - extend (see <a href="../documentation.html#3">the chapter-specific notes</a> - for a description). Not every chapter may have extensions, and the - extensions may come and go. Also, this page is incomplete because the - author is pressed for time. Check back often; the latest change was on - $Date: 2003/04/16 17:02:47 $ (UTC). +<p>What follows is a listing of these extensions, according to the + chapters of the library that they extend + (see <a href="../documentation.html#3">the chapter-specific + notes</a> for a description). Not every chapter has extensions, + and existing extensions may be removed (or moved) as their + functionality is standardized. </p> -<p>Descriptions range from the scanty to the verbose. You should also check - the <a href="../documentation.html#4">generated documentation</a> for notes - and comments, especially for entries marked with '*'. For more complete - doumentation, see the SGI website. For <em>really</em> complete - documentation, buy a copy of Matt Austern's book. *grin* +<p>Descriptions range from the scanty to the verbose. Also check + the <a href="../documentation.html#4">generated documentation</a> + for notes and comments, especially for entries marked with '*'. + For more complete doumentation, see the SGI website. + For <em>really</em> complete documentation, consider perusing a + copy of Matt Austern's book "Generic Programming and the STL." </p> <p>Back to the <a href="howto.html">libstdc++ extensions</a>. diff --git a/libstdc++-v3/docs/html/faq/index.html b/libstdc++-v3/docs/html/faq/index.html index e353a1f2f52..ff6cd65c9a6 100644 --- a/libstdc++-v3/docs/html/faq/index.html +++ b/libstdc++-v3/docs/html/faq/index.html @@ -1052,14 +1052,26 @@ http://clisp.cons.org/~haible/gccinclude-glibc-2.2-compat.diff <hr /> <h2><a name="5_6">5.6 Is libstdc++ thread-safe?</a></h2> - <p>libstdc++ strives to be thread-safe when all of the following + <p>The library strives to be thread-safe when all of the following conditions are met: </p> <ul> <li>The system's libc is itself thread-safe,</li> - <li><code>gcc -v</code> reports a thread model other than 'single',</li> - <li>[pre-3.3 only] a non-generic implementation of atomicity.h - exists for the architecture in question.</li> + <li>The compiler in use reports a thread model other than 'single'. This can be tested via output from <code>gcc -v</code>. Multi-thread capable versions of gcc output something like this: +<pre> +%gcc -v +Using built-in specs. +... +Thread model: posix +gcc version 4.1.2 20070925 (Red Hat 4.1.2-33) +</pre> + +<p>Look for "Thread model" lines that aren't equal to "single."</p> + </li> + <li>Requisite command-line flags are used for atomic operations and threading. Examples of this include <code>-pthread</code> and <code>-march=native</code>, although specifics vary depending on the host environment. See <a href="http://gcc.gnu.org/onlinedocs/gcc/Option-Summary.html">Machine Dependent Options</a>.</li> + <li>An implementation of atomicity.h functions + exists for the architecture in question. See the internals documentation for more <a href="../ext/concurrence.html">details</a>.</li> + </ul> <p>The user-code must guard against concurrent method calls which may access any particular library object's state. Typically, the |