mirror of git://gcc.gnu.org/git/gcc.git
286 lines
14 KiB
HTML
286 lines
14 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="AUTHOR" content="pme@gcc.gnu.org (Phil Edwards)">
|
|
<meta name="KEYWORDS" content="HOWTO, libstdc++, gcc, g++, libg++, STL">
|
|
<meta name="DESCRIPTION" content="HOWTO for libstdc++ chapter 17.">
|
|
<meta name="GENERATOR" content="vi and eight fingers">
|
|
<title>libstdc++-v3 HOWTO: Chapter 17</title>
|
|
<link rel="StyleSheet" href="../lib3styles.css">
|
|
</head>
|
|
<body>
|
|
|
|
<h1 class="centered"><a name="top">Chapter 17: Library Introduction</a></h1>
|
|
|
|
<p>Chapter 17 is actually a list of definitions and descriptions used
|
|
in the following chapters of the Standard when describing the actual
|
|
library. Here, we use "Introduction" as an introduction
|
|
to the <em>GNU implementation of</em> the ISO Standard C++ Library.
|
|
</p>
|
|
|
|
|
|
<!-- ####################################################### -->
|
|
<hr>
|
|
<h1>Contents</h1>
|
|
<ul>
|
|
<li><a href="#2">The Standard C++ header files</a>
|
|
<li><a href="#3">The Standard C++ library and multithreading</a>
|
|
<li><a href="#4"><code><foo></code> vs <code><foo.h></code></a>
|
|
<li><a href="porting-howto.html">Porting HOWTO</a>
|
|
<li><a href="#5">Behavior specific to libstdc++-v3</a>
|
|
</ul>
|
|
|
|
<hr>
|
|
|
|
<!-- ####################################################### -->
|
|
|
|
<h2><a name="2">The Standard C++ header files</a></h2>
|
|
<p>The Standard C++ Library specifies 50 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 you <code>#include</code> a certain header, the
|
|
contents of that header, as defined by the Standard, become
|
|
available to you, no matter how.
|
|
</p>
|
|
<p>The names of the headers can be easily seen in
|
|
<a href="headers_cc.txt"><code>testsuite/17_intro/headers.cc</code></a>,
|
|
which is a small testbed we use to make certain that the headers
|
|
all compile and run.
|
|
</p>
|
|
|
|
<hr>
|
|
<h2><a name="3">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++
|
|
standard does not address matters of multithreaded applications.
|
|
Unless explicitly prefaced, all information in this section is
|
|
current as of the gcc 3.0 release and all later point releases.
|
|
</p>
|
|
<p>Earlier gcc releases had a somewhat different approach to
|
|
threading configuration and proper compilation. Before gcc 3.0,
|
|
configuration of the threading model was dictated by compiler
|
|
command-line options and macros (both of which were somewhat
|
|
thread-implementation and port-specific). There were no
|
|
guarantees related to being able to link code compiled with one
|
|
set of options and macro setting with another set. For gcc 3.0,
|
|
configuration of the threading model used with libraries and
|
|
user-code is performed when gcc is configured and built using
|
|
the --enable-threads and --disable-threads options. The ABI is
|
|
stable for symbol name-mangling and limited functional
|
|
compatibility exists between code compiled under different
|
|
threading models.
|
|
</p>
|
|
<p>All normal disclaimers aside, multithreaded C++ application are
|
|
only supported when libstdc++ and all user code was built with
|
|
compilers which report (via <code> gcc/g++ -v </code>) the same thread
|
|
model and that model is not <em>single</em>. As long as your
|
|
final application is actually single-threaded, then it should be
|
|
safe to mix user code built with a thread model of
|
|
<em>single</em> with a libstdc++ and other C++ libraries built
|
|
with another thread model useful on the platform. Other mixes
|
|
may or may not work but are not considered supported. (Thus, if
|
|
you distribute a shared C++ library in binary form only, it may
|
|
be best to compile it with a gcc configured with
|
|
--enable-threads for maximal interchangeability and usefulness
|
|
with a user population that may have built gcc with either
|
|
--enable-threads or --disable-threads.)
|
|
</p>
|
|
<p>When you link a multithreaded application, you will probably
|
|
need to add a library or flag to g++. This is a very
|
|
non-standardized area of GCC across ports. Some ports support a
|
|
special flag (the spelling isn't even standardized yet) to add
|
|
all required macros to a compilation (if any such flags are
|
|
required then you must provide the flag for all compilations not
|
|
just linking) and link-library additions and/or replacements at
|
|
link time. The documentation is weak. Here is a quick summary
|
|
to display how ad hoc this is: On Solaris, both -pthreads and
|
|
-threads (with subtly different meanings) are honored. On OSF,
|
|
-pthread and -threads (with subtly different meanings) are
|
|
honored. On Linux/i386, -pthread is honored. On FreeBSD,
|
|
-pthread is honored. Some other ports use other switches.
|
|
AFAIK, none of this is properly documented anywhere other than
|
|
in ``gcc -dumpspecs'' (look at lib and cpp entries).
|
|
</p>
|
|
<p>See <a href="../faq/index.html#3">FAQ</a> (general overview), <a
|
|
href="../23_containers/howto.html#3">23</a> (containers), and <a
|
|
href="../27_io/howto.html#9">27</a> (I/O) for more information.
|
|
</p>
|
|
<p>The libstdc++-v3 library (unlike libstdc++-v2, all of it, not
|
|
just the STL) has been designed so that multithreaded
|
|
applications using it may be written. The first problem is
|
|
finding a <em>fast</em> method of implementation portable to all
|
|
platforms. Due to historical reasons, some of the library is
|
|
written against per-CPU-architecture spinlocks and other parts
|
|
against the gthr.h abstraction layer which is provided by gcc.
|
|
A minor problem that pops up every so often is different
|
|
interpretations of what "thread-safe" means for a
|
|
library (not a general program). We currently use the <a
|
|
href="http://www.sgi.com/tech/stl/thread_safety.html">same
|
|
definition that SGI</a> uses for their STL subset. However, the
|
|
exception for read-only containers only applies to the STL
|
|
components.
|
|
</p>
|
|
<p>Here is a small link farm to threads (no pun) in the mail archives
|
|
that discuss the threading problem. Each link is to the first
|
|
relevant message in the thread; from there you can use
|
|
"Thread Next" to move down the thread. This farm is in
|
|
latest-to-oldest order.
|
|
<ul>
|
|
<li>Our threading expert Loren gives a breakdown of
|
|
<a href="http://gcc.gnu.org/ml/libstdc++/2001-10/msg00024.html">the
|
|
six situations involving threads</a> for the 3.0 release series.
|
|
<li><a href="http://gcc.gnu.org/ml/libstdc++/2001-05/msg00384.html">
|
|
This message</a> inspired a recent updating of issues with threading
|
|
and the SGI STL library. It also contains some example
|
|
POSIX-multithreaded STL code.
|
|
</ul>
|
|
(A large selection of links to older messages has been removed; many
|
|
of the messages from 1999 were lost in a disk crash, and the few
|
|
people with access to the backup tapes have been too swamped with work
|
|
to restore them. Many of the points have been superseded anyhow.)
|
|
</p>
|
|
<p>This section will be updated as new and interesting issues come
|
|
to light.
|
|
</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="4"><code><foo></code> vs <code><foo.h></code></a></h2>
|
|
<p>The new-style headers are fully supported in libstdc++-v3. The compiler
|
|
itself fully supports namespaces, including <code>std::</code>.
|
|
</p>
|
|
<p>For those of you new to ISO C++98, no, that isn't a typo, the headers
|
|
really have new names. Marshall Cline's C++ FAQ Lite has a good
|
|
explanation in
|
|
<a href="http://www.cerfnet.com/~mpcline/On-Line-C++-FAQ/coding-standards.html#[25.4]">item [25.4]</a>.
|
|
</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">Behavior specific to libstdc++-v3</a></h2>
|
|
<p>The ISO standard defines the following phrase:
|
|
<blockquote><dl>
|
|
<dt><code>[1.3.5] implementation-defined behavior</code>
|
|
<dd>behavior, for a well-formed program construct and correct data, that
|
|
depends on the implementation <strong>and that each implementation
|
|
shall document</strong>.
|
|
</dl></blockquote>
|
|
We do so here, for the C++ library only. Behavior of the compiler,
|
|
linker, runtime loader, and other elements of "the
|
|
implementation" are documented elsewhere. Everything listed in
|
|
Annex B, Implemenation Qualities, are also part of the compiler, not
|
|
the library.
|
|
</p>
|
|
<p>For each entry, we give the section number of the standard, when
|
|
applicable. This list is probably incomplet and inkorrekt.
|
|
</p>
|
|
<p><strong>[17.4.4.5]</strong> Non-reentrant functions are probably best
|
|
discussed in the various sections on multithreading (see above).
|
|
</p>
|
|
<!-- [17.4.4.8]/3 says any function that doesn't have an exception-spec
|
|
can throw whatever we want; see also its footnote. Let's list those
|
|
in the sections where the function itself occurs.
|
|
-->
|
|
<p><strong>[18.1]/4</strong> The type of <code>NULL</code> is described
|
|
<a href="../18_support/howto.html#1">here</a>.
|
|
</p>
|
|
<p><strong>[18.3]/8</strong> Even though it's listed in the library
|
|
sections, libstdc++-v3 has zero control over what the cleanup code hands
|
|
back to the runtime loader. Talk to the compiler people. :-)
|
|
</p>
|
|
<p><strong>[18.4.2.1]/5</strong> (bad_alloc),<br>
|
|
<strong>[18.5.2]/5</strong> (bad_cast),<br>
|
|
<strong>[18.5.3]/5</strong> (bad_typeid),<br>
|
|
<strong>[18.6.1]/8</strong> (exception),<br>
|
|
<strong>[18.6.2.1]/5</strong> (bad_exception): The <code>what()</code>
|
|
member function of class <code>std::exception</code>, and these other
|
|
classes publicly derived from it, simply returns the name of the
|
|
class. But they are the <em>mangled</em> names; you will need to call
|
|
<code>c++filt</code> and pass the names as command-line parameters to
|
|
demangle them.
|
|
(The classes in <code><stdexcept></code> have constructors which
|
|
require an argument to use later for <code>what()</code> calls, so the
|
|
question does not arise in most user-defined exceptions.)
|
|
</p>
|
|
<p><strong>[18.5.1]/7</strong> The return value of
|
|
<code>std::type_info::name()</code> is the mangled type name (see the
|
|
previous entry for more).
|
|
</p>
|
|
<p><strong>[20.1.5]/5</strong> <em>"Implementors are encouraged to
|
|
supply libraries that can accept allocators that encapsulate more
|
|
general memory models and that support non-equal instances. In such
|
|
implementations, any requirements imposed on allocators by containers
|
|
beyond those requirements that appear in Table 32, and the semantics
|
|
of containers and algorithms when allocator instances compare
|
|
non-equal, are implementation-defined."</em> As yet we don't
|
|
have any allocators which compare non-equal, so we can't describe how
|
|
they behave.
|
|
</p>
|
|
<p><strong>[21.1.3.1]/3,4</strong>,<br>
|
|
<strong>[21.1.3.2]/2</strong>,<br>
|
|
<strong>[23.*]'s foo::iterator</strong>,<br>
|
|
<strong>[27.*]'s foo::*_type</strong>,<br>
|
|
<strong>others...</strong>
|
|
Nope, these types are called implementation-defined because you
|
|
shouldn't be taking advantage of their underlying types. Listing them
|
|
here would defeat the purpose. :-)
|
|
</p>
|
|
<p><strong>[21.1.3.1]/5</strong> I don't really know about the mbstate_t
|
|
stuff... see the chapter 22 notes for what does exist.
|
|
</p>
|
|
<p><strong>[22.*]</strong> Anything and everything we have on locale
|
|
implemenation will be described
|
|
<a href="../22_locale/howto.html">over here</a>.
|
|
</p>
|
|
<p><strong>[26.2.8]/9</strong> I have no idea what
|
|
<code>complex<T></code>'s pow(0,0) returns.
|
|
</p>
|
|
<p><strong>[27.4.2.4]/2</strong> Calling
|
|
<code>std::ios_base::sync_with_stdio</code> after I/O has already been
|
|
performed on the standard stream objects will
|
|
flush the buffers, and <!-- this line might go away -->
|
|
destroy and recreate the underlying buffer instances. Whether or not
|
|
the previously-written I/O is destroyed in this process depends mostly
|
|
on the --enable-libio choice: for stdio, if the written data is
|
|
already in the stdio buffer, the data may be completely safe!
|
|
</p>
|
|
<p><strong>I/O sentry ctor/dtor</strong> They can perform additional work
|
|
than the minimum required. I don't think we're currently taking
|
|
advantage of this yet.
|
|
</p>
|
|
<p><strong>[27.7.1.3]/16</strong>,<br>
|
|
<strong>[27.8.1.4]/10</strong>
|
|
The effects of <code>pubsetbuf/setbuf</code> are described
|
|
<a href="../27_io/howto.html#2">in this chapter</a>.
|
|
</p>
|
|
<p><strong>[27.8.1.4]/16</strong> Calling <code>fstream::sync</code> when
|
|
a get area exists will... whatever <code>fflush()</code> does, I think.
|
|
</p>
|
|
<p>Return <a href="#top">to top of page</a> or
|
|
<a href="../faq/index.html">to the FAQ</a>.
|
|
</p>
|
|
|
|
|
|
|
|
<!-- ####################################################### -->
|
|
|
|
<hr>
|
|
<p class="fineprint"><em>
|
|
See <a href="license.html">license.html</a> for copying conditions.
|
|
Comments and suggestions are welcome, and may be sent to
|
|
<a href="mailto:libstdc++@gcc.gnu.org">the libstdc++ mailing list</a>.
|
|
</em></p>
|
|
|
|
|
|
</body>
|
|
</html>
|
|
|
|
|