1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
|
<?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 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>
<li><a href="#3">The Standard C++ library and multithreading</a></li>
<li><a href="#4"><code><foo></code> vs <code><foo.h></code></a></li>
<li><a href="porting-howto.html">Porting HOWTO</a></li>
<li><a href="#5">Behavior specific to libstdc++-v3</a></li>
<li><a href="#6">Preprocessor macros controlling the library</a></li>
</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.
</p>
<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>
<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.</li>
</ul>
<p> (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.parashift.com/c++-faq-lite/coding-standards.html#faq-26.4">item [26.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:
</p>
<blockquote><dl>
<dt><code>[1.3.5] implementation-defined behavior</code></dt>
<dd>behavior, for a well-formed program construct and correct data, that
depends on the implementation <strong>and that each implementation
shall document</strong>.
</dd>
</dl></blockquote>
<p>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, or call a
<a href="../18_support/howto.html#5">runtime demangler function</a>.
(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 <a href="../22_locale/howto.html">chapter 22 notes</a>
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 />
<h2><a name="6">Preprocessor macros controlling the library</a></h2>
<p>Some of the semantics of the libstdc++-v3 implementation are
controlled by preprocessor macros, both during build/installation and
during compilation of user code. Many of these choices are made when
the library is built and installed (actually, during
<a href="../configopts.html">the configuration step</a>, with the
various --enable/--disable choices being translated to #define/#undef).
</p>
<p>All library macros begin with <code>_GLIBCPP_</code>. The fact that
these symbols start with a leading underscore should give you a clue
that (by default) they aren't meant to be changed by the user. :-)
</p>
<p>These macros are all gathered in the file <code>c++config.h</code>,
which is generated during installation. <strong>You must assume that
these macros cannot be redefined by your own code</strong>, unless we
document otherwise here. Some of the choices control code which has
already been compiled (i.e., 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.
If you want to experiment with different values, you must change the
config headers before building/installing the library.
</p>
<p>Below are macros which, for 3.1 and later, you may change yourself,
in your own code with #define/#undef or with -D/-U compiler flags.
The default state of the symbol is listed. "Configurable"
(or "Not configurable") means that the symbol is initially
chosen (or not) based on --enable/--disable options at configure time.
</p>
<dl>
<dt><code>_GLIBCPP_DEPRECATED</code></dt>
<dd>Undefined by default. Not configurable. Turning this on enables
older ARM-style iostreams code, and other anachronisms. This may be
useful in updating old C++ programs which no longer meet the
requirements of the language.
</dd>
<!--
Can this actually be turned off and still produce a working lib? Must
check. -pme
No, it can't. Hmmm. -pme
<dt><code>_GLIBCPP_RESOLVE_LIB_DEFECTS</code></dt>
<dd>Defined by default. Not configurable. The library follows
corrections and updates from the ISO committee, see
<a href="../faq/index.html#5_2">here</a> and
<a href="../ext/howto.html#5">here</a> for more on this feature.
If you have code which depends on the first version of the standard,
you might try undefining this macro.
</dd>
-->
<dt><code>_GLIBCPP_CONCEPT_CHECKS</code></dt>
<dd>Undefined by default. Configurable. 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></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>
<!-- ####################################################### -->
<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>
|
