[libstdc++] Doc update
Phil Edwards
phil@jaj.com
Wed Nov 20 23:16:00 GMT 2002
This imports the latest LWG Issues List.
Doxygen supports some new directives in its input file, so I had it
regenerate ours. It also gave us a new CSS stylesheet, which looks nice.
The new I/O docs point to some of these new notes, and vice versa.
The threading-on-i386 thing is mentioned in the FAQ now.
2002-11-21 Phil Edwards <pme@gcc.gnu.org>
* docs/doxygen/style.css: Update.
* docs/doxygen/user.cfg.in: Update.
* docs/html/documentation.html: Regenerate.
* docs/html/17_intro/howto.html: Tweak I/O sentry entry.
* docs/html/27_io/howto.html: New section on headers.
* docs/html/faq/index.html: Add i386 threading entry.
* docs/html/faq/index.txt: Regenerate.
* docs/html/ext/lwg-active.html, docs/html/ext/lwg-defects.html:
Import R23.
Index: docs/doxygen/style.css
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/style.css,v
retrieving revision 1.3
diff -u -3 -p -r1.3 style.css
--- docs/doxygen/style.css 5 Feb 2002 00:14:35 -0000 1.3
+++ docs/doxygen/style.css 21 Nov 2002 07:12:26 -0000
@@ -1,4 +1,5 @@
H1 { text-align: center; }
+CAPTION { font-weight: bold }
A.qindex {}
A.qindexRef {}
A.el { text-decoration: none; font-weight: bold }
@@ -10,15 +11,39 @@ DL.el { margin-left: -1cm }
DIV.fragment { width: 100%; border: none; background-color: #eeeeee }
DIV.ah { background-color: black; font-weight: bold; color: #ffffff; margin-bottom: 3px; margin-top: 3px }
TD.md { background-color: #f2f2ff; font-weight: bold; }
-TD.mdname1 { background-color: #f2f2ff; font-weight: bold; font-style: italic; }
-TD.mdname { background-color: #f2f2ff; font-weight: bold; font-style: italic; width: 600px; }
+TD.mdname1 { background-color: #f2f2ff; font-weight: bold; color: #602020; }
+TD.mdname { background-color: #f2f2ff; font-weight: bold; color: #602020; width: 600px; }
DIV.groupHeader { margin-left: 16px; margin-top: 12px; margin-bottom: 6px; font-weight: bold }
DIV.groupText { margin-left: 16px; font-style: italic; font-size: smaller }
-FONT.keyword { color: #008000 }
-FONT.keywordtype { color: #604020 }
-FONT.keywordflow { color: #e08000 }
-FONT.comment { color: #800000 }
-FONT.preprocessor { color: #806020 }
-FONT.stringliteral { color: #002080 }
-FONT.charliteral { color: #008080 }
-.smallertext { font-size: smaller }
+BODY { background: white }
+TD.indexkey {
+ background-color: #eeeeff;
+ font-weight: bold;
+ padding-right : 10px;
+ padding-top : 2px;
+ padding-left : 10px;
+ padding-bottom : 2px;
+ margin-left : 0px;
+ margin-right : 0px;
+ margin-top : 2px;
+ margin-bottom : 2px
+}
+TD.indexvalue {
+ background-color: #eeeeff;
+ font-style: italic;
+ padding-right : 10px;
+ padding-top : 2px;
+ padding-left : 10px;
+ padding-bottom : 2px;
+ margin-left : 0px;
+ margin-right : 0px;
+ margin-top : 2px;
+ margin-bottom : 2px
+}
+span.keyword { color: #008000 }
+span.keywordtype { color: #604020 }
+span.keywordflow { color: #e08000 }
+span.comment { color: #800000 }
+span.preprocessor { color: #806020 }
+span.stringliteral { color: #002080 }
+span.charliteral { color: #008080 }
Index: docs/doxygen/user.cfg.in
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/doxygen/user.cfg.in,v
retrieving revision 1.20
diff -u -3 -p -r1.20 user.cfg.in
--- docs/doxygen/user.cfg.in 16 Jun 2002 11:29:50 -0000 1.20
+++ docs/doxygen/user.cfg.in 21 Nov 2002 07:12:26 -0000
@@ -1,4 +1,4 @@
-# Doxyfile 1.2.12
+# Doxyfile 1.2.18
# This file describes the settings to be used by the documentation system
# doxygen (www.doxygen.org) for a project
@@ -43,9 +43,11 @@ OUTPUT_DIRECTORY = @outdir@
# documentation generated by doxygen is written. Doxygen will use this
# information to generate all constant output in the proper language.
# The default language is English, other supported languages are:
-# Brazilian, Chinese, Croatian, Czech, Danish, Dutch, Finnish, French,
-# German, Hungarian, Italian, Japanese, Korean, Norwegian, Polish,
-# Portuguese, Romanian, Russian, Slovak, Slovene, Spanish and Swedish.
+# Brazilian, Catalan, Chinese, Chinese-Traditional, Croatian, Czech, Danish, Dutch,
+# Finnish, French, German, Greek, Hungarian, Italian, Japanese, Japanese-en
+# (Japanese with english messages), Korean, Norwegian, Polish, Portuguese,
+# Romanian, Russian, Serbian, Slovak, Slovene, Spanish, Swedish and Ukrainian.
+
OUTPUT_LANGUAGE = English
@@ -66,6 +68,12 @@ EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
+# If the EXTRACT_LOCAL_CLASSES tag is set to YES classes (and structs)
+# defined locally in source files will be included in the documentation.
+# If set to NO only classes defined in header files are included.
+
+EXTRACT_LOCAL_CLASSES = NO
+
# If the HIDE_UNDOC_MEMBERS tag is set to YES, Doxygen will hide all
# undocumented members of documented classes, files or namespaces.
# If set to NO (the default) these members will be included in the
@@ -81,6 +89,13 @@ HIDE_UNDOC_MEMBERS = YES
HIDE_UNDOC_CLASSES = YES
+# If the HIDE_FRIEND_COMPOUNDS tag is set to YES, Doxygen will hide all
+# friend (class|struct|union) declarations.
+# If set to NO (the default) these declarations will be included in the
+# documentation.
+
+HIDE_FRIEND_COMPOUNDS = NO
+
# If the BRIEF_MEMBER_DESC tag is set to YES (the default) Doxygen will
# include brief member descriptions after the members that are listed in
# the file and class documentation (similar to JavaDoc).
@@ -101,6 +116,14 @@ REPEAT_BRIEF = YES
ALWAYS_DETAILED_SEC = YES
+# If the INLINE_INHERITED_MEMB tag is set to YES, doxygen will show all inherited
+# members of a class in the documentation of that class as if those members were
+# ordinary class members. Constructors, destructors and assignment operators of
+# the base classes will not be shown.
+
+INLINE_INHERITED_MEMB = NO
+# pedwards -- this is useful, but ch27 gets huge
+
# If the FULL_PATH_NAMES tag is set to YES then Doxygen will prepend the full
# path before files name in the file list and in the header files. If set
# to NO the shortest path that makes the file name unique will be used.
@@ -167,6 +190,21 @@ SHOW_INCLUDE_FILES = YES
JAVADOC_AUTOBRIEF = NO
+# The MULTILINE_CPP_IS_BRIEF tag can be set to YES to make Doxygen
+# treat a multi-line C++ special comment block (i.e. a block of //! or ///
+# comments) as a brief description. This used to be the default behaviour.
+# The new default is to treat a multi-line C++ comment block as a detailed
+# description. Set this tag to YES if you prefer the old behaviour instead.
+
+MULTILINE_CPP_IS_BRIEF = YES
+
+# If the DETAILS_AT_TOP tag is set to YES then Doxygen
+# will output the detailed description near the top, like JavaDoc.
+# If set to NO, the detailed description appears after the member
+# documentation.
+
+DETAILS_AT_TOP = NO
+
# If the INHERIT_DOCS tag is set to YES (the default) then an undocumented
# member inherits the documentation from any documented member that it
# reimplements.
@@ -183,7 +221,7 @@ INLINE_INFO = YES
# alphabetically by member name. If set to NO the members will appear in
# declaration order.
-SORT_MEMBER_DOCS = NO
+SORT_MEMBER_DOCS = YES
# If member grouping is used in the documentation and the DISTRIBUTE_GROUP_DOC
# tag is set to YES, then doxygen will reuse the documentation of the first
@@ -215,6 +253,12 @@ GENERATE_TESTLIST = NO
GENERATE_BUGLIST = YES
+# The GENERATE_DEPRECATEDLIST tag can be used to enable (YES) or
+# disable (NO) the deprecated list. This list is created by putting
+# \deprecated commands in the documentation.
+
+GENERATE_DEPRECATEDLIST= YES
+
# This tag can be used to specify a number of aliases that acts
# as commands in the documentation. An alias has the form "name=value".
# For example adding "sideeffect=\par Side Effects:\n" will allow you to
@@ -222,7 +266,8 @@ GENERATE_BUGLIST = YES
# will result in a user defined paragraph with heading "Side Effects:".
# You can put \n's in the value part of an alias to insert newlines.
-ALIASES = "doctodo=@todo\nDoc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more."
+ALIASES = "doctodo=@todo\nDoc me! See docs/doxygen/TODO and http://gcc.gnu.org/ml/libstdc++/2002-02/msg00003.html for more." \
+"isiosfwd=One of the @link s27_2_iosfwd I/O forward declarations @endlink"
# The ENABLED_SECTIONS tag can be used to enable conditional
# documentation sections, marked by \if sectionname ... \endif.
@@ -237,7 +282,7 @@ ENABLED_SECTIONS = @enabled_sectio
# documentation can be controlled using \showinitializer or \hideinitializer
# command in the documentation regardless of this setting.
-MAX_INITIALIZER_LINES = 30
+MAX_INITIALIZER_LINES = 0
# Set the OPTIMIZE_OUTPUT_FOR_C tag to YES if your project consists of C sources
# only. Doxygen will then generate output that is more tailored for C.
@@ -246,6 +291,13 @@ MAX_INITIALIZER_LINES = 30
OPTIMIZE_OUTPUT_FOR_C = NO
+# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java sources
+# only. Doxygen will then generate output that is more tailored for Java.
+# For instance namespaces will be presented as packages, qualified scopes
+# will look different, etc.
+
+OPTIMIZE_OUTPUT_JAVA = NO
+
# Set the SHOW_USED_FILES tag to NO to disable the list of files generated
# at the bottom of the documentation of classes and structs. If set to YES the
# list will mention the files that were used to generate the documentation.
@@ -325,12 +377,18 @@ RECURSIVE = YES
EXCLUDE = Makefile CVS
+# The EXCLUDE_SYMLINKS tag can be used select whether or not files or directories
+# that are symbolic links (a Unix filesystem feature) are excluded from the input.
+
+EXCLUDE_SYMLINKS = NO
+
# If the value of the INPUT tag contains directories, you can use the
# EXCLUDE_PATTERNS tag to specify one or more wildcard patterns to exclude
# certain files from those directories.
EXCLUDE_PATTERNS = CVS \
- stamp-*
+ stamp-* \
+ Makefile
# The EXAMPLE_PATH tag can be used to specify one or more files or
# directories that contain example code fragments that are included (see
@@ -369,7 +427,7 @@ INPUT_FILTER =
# If the FILTER_SOURCE_FILES tag is set to YES, the input filter (if set using
# INPUT_FILTER) will be used to filter the input files when producing source
-# files to browse.
+# files to browse (i.e. when SOURCE_BROWSER is set to YES).
FILTER_SOURCE_FILES = NO
@@ -437,6 +495,12 @@ GENERATE_HTML = @do_html@
HTML_OUTPUT = @html_output_dir@
+# The HTML_FILE_EXTENSION tag can be used to specify the file extension for
+# each generated HTML page (for example: .htm,.php,.asp). If it is left blank
+# doxygen will generate files with .html extension.
+
+HTML_FILE_EXTENSION = .html
+
# The HTML_HEADER tag can be used to specify a personal HTML header for
# each generated HTML page. If it is left blank doxygen will generate a
# standard header.
@@ -469,6 +533,20 @@ HTML_ALIGN_MEMBERS = YES
GENERATE_HTMLHELP = NO
+# If the GENERATE_HTMLHELP tag is set to YES, the CHM_FILE tag can
+# be used to specify the file name of the resulting .chm file. You
+# can add a path in front of the file if the result should not be
+# written to the html output dir.
+
+CHM_FILE =
+
+# If the GENERATE_HTMLHELP tag is set to YES, the HHC_LOCATION tag can
+# be used to specify the location (absolute path including file name) of
+# the HTML help compiler (hhc.exe). If non empty doxygen will try to run
+# the html help compiler on the generated index.hhp.
+
+HHC_LOCATION =
+
# If the GENERATE_HTMLHELP tag is set to YES, the GENERATE_CHI flag
# controls if a separate .chi index file is generated (YES) or that
# it should be included in the master .chm file (NO).
@@ -528,6 +606,17 @@ GENERATE_LATEX = NO
LATEX_OUTPUT = latex
+# The LATEX_CMD_NAME tag can be used to specify the LaTeX command name to
+# be invoked. If left blank `latex' will be used as the default command name.
+
+LATEX_CMD_NAME = latex
+
+# The MAKEINDEX_CMD_NAME tag can be used to specify the command name to
+# generate index for LaTeX. If left blank `makeindex' will be used as the
+# default command name.
+
+MAKEINDEX_CMD_NAME = makeindex
+
# If the COMPACT_LATEX tag is set to YES Doxygen generates more compact
# LaTeX documents. This may be useful for small projects and may help to
# save some trees in general.
@@ -654,6 +743,30 @@ MAN_LINKS = NO
GENERATE_XML = NO
+# The XML_SCHEMA tag can be used to specify an XML schema,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_SCHEMA =
+
+# The XML_DTD tag can be used to specify an XML DTD,
+# which can be used by a validating XML parser to check the
+# syntax of the XML files.
+
+XML_DTD =
+
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+
+# If the GENERATE_AUTOGEN_DEF tag is set to YES Doxygen will
+# generate an AutoGen Definitions (see autogen.sf.net) file
+# that captures the structure of the code including all
+# documentation. Note that this feature is still experimental
+# and incomplete at the moment.
+
+GENERATE_AUTOGEN_DEF = NO
+
#---------------------------------------------------------------------------
# Configuration options related to the preprocessor
#---------------------------------------------------------------------------
@@ -707,6 +820,8 @@ INCLUDE_FILE_PATTERNS =
### completely broken, and the presence of the macros confuses the parser.
PREDEFINED = _GLIBCPP_DEPRECATED \
+ _GLIBCPP_USE_WCHAR_T \
+ _GLIBCPP_USE_LONG_LONG \
__glibcpp_class_requires="//" \
__glibcpp_class_requires2="//" \
__glibcpp_class_requires3="//" \
@@ -745,6 +860,12 @@ GENERATE_TAGFILE =
ALLEXTERNALS = YES
+# If the EXTERNAL_GROUPS tag is set to YES all external groups will be listed
+# in the modules index. If set to NO, only the current project's groups will
+# be listed.
+
+EXTERNAL_GROUPS = YES
+
# The PERL_PATH should be the absolute path and name of the perl script
# interpreter (i.e. the result of `which perl').
@@ -762,6 +883,12 @@ PERL_PATH = /usr/bin/perl
CLASS_DIAGRAMS = YES
+# If set to YES, the inheritance and collaboration graphs will hide
+# inheritance and usage relations if the target is undocumented
+# or is not a class.
+
+HIDE_UNDOC_RELATIONS = YES
+
# If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is
# available from the path. This tool is part of Graphviz, a graph visualization
# toolkit from AT&T and Lucent Bell Labs. The other options in this section
@@ -788,12 +915,6 @@ COLLABORATION_GRAPH = YES
TEMPLATE_RELATIONS = YES
-# If set to YES, the inheritance and collaboration graphs will hide
-# inheritance and usage relations if the target is undocumented
-# or is not a class.
-
-HIDE_UNDOC_RELATIONS = YES
-
# If the ENABLE_PREPROCESSING, SEARCH_INCLUDES, INCLUDE_GRAPH, and HAVE_DOT
# tags are set to YES then doxygen will generate a graph for each documented
# file showing the direct and indirect include dependencies of the file with
@@ -812,6 +933,12 @@ INCLUDED_BY_GRAPH = YES
# will graphical hierarchy of all classes instead of a textual one.
GRAPHICAL_HIERARCHY = YES
+
+# The DOT_IMAGE_FORMAT tag can be used to set the image format of the images
+# generated by dot. Possible values are png, jpg, or gif
+# If left blank png will be used.
+
+DOT_IMAGE_FORMAT = png
# The tag DOT_PATH can be used to specify the path where the dot tool can be
# found. If left blank, it is assumed the dot tool can be found on the path.
Index: docs/html/documentation.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/documentation.html,v
retrieving revision 1.23
diff -u -3 -p -r1.23 documentation.html
--- docs/html/documentation.html 7 Oct 2002 18:11:17 -0000 1.23
+++ docs/html/documentation.html 21 Nov 2002 07:12:26 -0000
@@ -66,7 +66,7 @@
<ul>
<li><a href="libstdc++-html-USERS-3.1/index.html">for the 3.1 release</a>
</li>
- <li><a href="libstdc++-html-USERS-3.2/index.html">for the 3.2 release</a>
+ <li><a href="libstdc++-html-USERS-3.2/index.html">for the 3.2.x release</a>
</li>
<li><a href="latest-doxygen/index.html">"the latest collection"</a>
(for the snapshot or later; see the date on the first page)
@@ -208,6 +208,7 @@
<li><a href="27_io/howto.html#7">More on binary I/O</a></li>
<li><a href="27_io/howto.html#8">Pathetic performance? Ditch C.</a></li>
<li><a href="27_io/howto.html#9">Threads and I/O</a></li>
+ <li><a href="27_io/howto.html#10">Which header?</a></li>
</ul>
</li>
Index: docs/html/17_intro/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/17_intro/howto.html,v
retrieving revision 1.26
diff -u -3 -p -r1.26 howto.html
--- docs/html/17_intro/howto.html 11 Nov 2002 01:10:43 -0000 1.26
+++ docs/html/17_intro/howto.html 21 Nov 2002 07:12:26 -0000
@@ -261,8 +261,9 @@
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
+ <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 />
Index: docs/html/27_io/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/27_io/howto.html,v
retrieving revision 1.21
diff -u -3 -p -r1.21 howto.html
--- docs/html/27_io/howto.html 11 Nov 2002 01:10:44 -0000 1.21
+++ docs/html/27_io/howto.html 21 Nov 2002 07:12:27 -0000
@@ -34,6 +34,7 @@
<li><a href="#7">More on binary I/O</a></li>
<li><a href="#8">Pathetic performance? Ditch C.</a></li>
<li><a href="#9">Threads and I/O</a></li>
+ <li><a href="#10">Which header?</a></li>
</ul>
<hr />
@@ -556,6 +557,138 @@
<p>Don't forget that other cstdio implemenations are possible. You could
easily write one to perform your own forms of locking, to solve your
"interesting" problems.
+ </p>
+
+<hr />
+<h2><a name="10">Which header?</a></h2>
+ <p>To minimize the time you have to wait on the compiler, it's good to
+ only include the headers you really need. Many people simply include
+ <iostream> when they don't need to -- and that can <em>penalize
+ your runtime as well.</em> Here are some tips on which header to use
+ for which situations, starting with the simplest.
+ </p>
+ <p><strong><iosfwd></strong> should be included whenever you simply
+ need the <em>name</em> of an I/O-related class, such as
+ "ofstream" or "basic_streambuf". Like the name
+ implies, these are forward declarations. (A word to all you fellow
+ old school programmers: trying to forward declare classes like
+ "class istream;" won't work. Look in the iosfwd header if
+ you'd like to know why.) For example,
+ </p>
+ <pre>
+ #include <iosfwd>
+
+ class MyClass
+ {
+ ....
+ std::ifstream input_file;
+ };
+
+ extern std::ostream& operator<< (std::ostream&, MyClass&);
+ </pre>
+ <p><strong><ios></strong> declares the base classes for the entire
+ I/O stream hierarchy, std::ios_base and std::basic_ios<charT>, the
+ counting types std::streamoff and std::streamsize, the file
+ positioning type std::fpos, and the various manipulators like
+ std::hex, std::fixed, std::noshowbase, and so forth.
+ </p>
+ <p>The ios_base class is what holds the format flags, the state flags,
+ and the functions which change them (setf(), width(), precision(),
+ etc). You can also store extra data and register callback functions
+ through ios_base, but that has been historically underused. Anything
+ which doesn't depend on the type of characters stored is consolidated
+ here.
+ </p>
+ <p>The template class basic_ios is the highest template class in the
+ hierarchy; it is the first one depending on the character type, and
+ holds all general state associated with that type: the pointer to the
+ polymorphic stream buffer, the facet information, etc.
+ </p>
+ <p><strong><streambuf></strong> declares the template class
+ basic_streambuf, and two standard instantiations, streambuf and
+ wstreambuf. If you need to work with the vastly useful and capable
+ stream buffer classes, e.g., to create a new form of storage
+ transport, this header is the one to include.
+ </p>
+ <p><strong><istream></strong>/<strong><ostream></strong> are
+ the headers to include when you are using the >>/<<
+ interface, or any of the other abstract stream formatting functions.
+ For example,
+ </p>
+ <pre>
+ #include <istream>
+
+ std::ostream& operator<< (std::ostream& os, MyClass& c)
+ {
+ return os << c.data1() << c.data2();
+ }
+ </pre>
+ <p>The std::istream and std::ostream classes are the abstract parents of
+ the various concrete implementations. If you are only using the
+ interfaces, then you only need to use the appropriate interface header.
+ </p>
+ <p><strong><iomanip></strong> provides "extractors and inserters
+ that alter information maintained by class ios_base and its dervied
+ classes," such as std::setprecision and std::setw. If you need
+ to write expressions like <code>os << setw(3);</code> or
+ <code>is >> setbase(8);</code>, you must include <iomanip>.
+ </p>
+ <p><strong><sstream></strong>/<strong><fstream></strong>
+ declare the six stringstream and fstream classes. As they are the
+ standard concrete descendants of istream and ostream, you will already
+ know about them.
+ </p>
+ <p>Finally, <strong><iostream></strong> provides the eight standard
+ global objects (cin, cout, etc). To do this correctly, this header
+ also provides the contents of the <istream> and <ostream>
+ headers, but nothing else. The contents of this header look like
+ </p>
+ <pre>
+ #include <ostream>
+ #include <istream>
+
+ namespace std
+ {
+ extern istream cin;
+ extern ostream cout;
+ ....
+
+ // this is explained below
+ <strong>static ios_base::Init __foo;</strong> // not its real name
+ }
+ </pre>
+ <p>Now, the runtime penalty mentioned previously: the global objects
+ must be initialized before any of your own code uses them; this is
+ guaranteed by the standard. Like any other global object, they must
+ be initialized once and only once. This is typically done with a
+ construct like the one above, and the nested class ios_base::Init is
+ specified in the standard for just this reason.
+ </p>
+ <p>How does it work? Because the header is included before any of your
+ code, the <strong>__foo</strong> object is constructed before any of
+ your objects. (Global objects are built in the order in which they
+ are declared, and destroyed in reverse order.) The first time the
+ constructor runs, the eight stream objects are set up.
+ </p>
+ <p>The <code>static</code> keyword means that each object file compiled
+ from a source file containing <iostream> will have its own
+ private copy of <strong>__foo</strong>. There is no specified order
+ of construction across object files (it's one of those pesky NP
+ problems that make life so interesting), so one copy in each object
+ file means that the stream objects are guaranteed to be set up before
+ any of your code which uses them could run, thereby meeting the
+ requirements of the standard.
+ </p>
+ <p>The penalty, of course, is that after the first copy of
+ <strong>__foo</strong> is constructed, all the others are just wasted
+ processor time. The time spent is merely for an increment-and-test
+ inside a function call, but over several dozen or hundreds of object
+ files, that time can add up. (It's not in a tight loop, either.)
+ </p>
+ <p>The lesson? Only include <iostream> when you need to use one of
+ the standard objects in that source file; you'll pay less startup
+ time. Only include the header files you need to in general; your
+ compile times will go down when there's less parsing work to do.
</p>
Index: docs/html/faq/index.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/faq/index.html,v
retrieving revision 1.46
diff -u -3 -p -r1.46 index.html
--- docs/html/faq/index.html 11 Nov 2002 01:10:44 -0000 1.46
+++ docs/html/faq/index.html 21 Nov 2002 07:12:33 -0000
@@ -70,7 +70,8 @@
<li><a href="#3_5"><code>_XOPEN_SOURCE</code> /
<code>_GNU_SOURCE</code> / etc is always defined</a>
</li>
- <li><a href="#3_6">OS X ctype.h is broken! How can I hack it?</a> </li>
+ <li><a href="#3_6">OS X ctype.h is broken! How can I hack it?</a></li>
+ <li><a href="#3_7">Threading is broken on i386</a></li>
</ol>
</li>
@@ -495,6 +496,18 @@ which is no longer available, thanks dej
the patch is quite simple, and well-known.
<a href="http://gcc.gnu.org/ml/gcc/2002-03/msg00817.html"> Here's a
link to the solution.</a>
+ </p>
+
+<hr />
+ <h2><a name="3_7">Threading is broken on i386</a></h2>
+ <p>Support for atomic integer operations is/was broken on i386
+ platforms. The assembly code accidentally used opcodes that are
+ only available on the i486 and later. So if you configured GCC
+ to target, for example, i386-linux, but actually used the programs
+ on an i686, then you would encounter no problems. Only when
+ actually running the code on a i386 will the problem appear.
+ </p>
+ <p>This is fixed in 3.2.2.
</p>
<hr />
More information about the Gcc-patches
mailing list