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
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
|
<?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), Benjamin Kosnik, Felix Natter" />
<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++ HOWTO: Chapter 17: Library Introduction</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="Next" href="../18_support/howto.html" type="text/html"
title="Library Support" />
<link rel="Copyright" href="license.html" type="text/html" />
<link rel="Help" href="../faq/index.html" type="text/html" title="F.A.Q." />
</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.0">Header Files</a></li>
<li><a href="#3.0">Namespaces</a></li>
<li><a href="#6">Macros</a></li>
<li><a href="#5">Implementation specific behavior</a></li>
<li><a href="#7">Multithreading</a></li>
</ul>
<hr />
<!-- ####################################################### -->
<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 header, the
contents of that header become
available, no matter how.
</p>
<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>
<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</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>
#include <array>
#include <functional>
</pre>
<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>
#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">The C Headers and <code>namespace std</code></a></h2>
<p>
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>
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="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
in <code>namespace std::</code>. Thus, in order to use these types or
functions, one must do one of two things:
</p>
<div class="itemizedlist"><ul type="disc"> <li><p>put a kind of
<span class="emphasis"><i>using-declaration</i></span> in your source
(either <code>using namespace std;</code> or i.e. <code>using
std::string;</code>) This approach works well for individual source files, but
should not be used in a global context, like header files.
</p></li> <li><p>use a <span class="emphasis"><i>fully
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 verbiage becomes unwieldy.)
</p></li>
</ul></div>
<hr />
<h2><a name="3.2">Using namespace composition</a></h2>
<p>
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
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;
using std::tr1::array;
class Window { ... };
}
</pre>
<p>
In this example, <code>std::string</code> gets imported into
<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. 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
<tt><<a href="mailto:llewelly@dbritsch.dsl.xmission.com">llewelly@dbritsch.dsl.xmission.com</a>></tt>, Karl Nelson
<tt><<a href="mailto:kenelson@ece.ucdavis.edu">kenelson@ece.ucdavis.edu</a>></tt>)
</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>
</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++
standard does not address matters of multithreaded applications.
Unless explicitly prefaced, all information in this section is
relevant to the GCC 3.0 release and all later 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#5_6">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++ library has been designed so that it can be used in
multithreaded applications (with libstdc++-v2 this was
only true of the STL parts.) 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. This definition is widely-used and something similar
will be used in the next version of the C++ standard library.
</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="5">Behavior specific to libstdc++</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, Implementation 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>[1.9]/11 #3</strong> If <code>isatty(3)</code> is true, then
interactive stream support is implied.
</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++ 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
problem of <code>what()</code>'s value 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
implementation 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>[27.6.1.1.2]</strong>,<br />
<strong>[27.6.2.3]</strong> The I/O sentry ctor and dtor can perform
additional work than the minimum required. We are not 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>
<!--
<dt><code></code></dt>
<dd>
</dd>
-->
<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>
|
