This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

[libstdc++] Doc update


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">&quot;the latest collection&quot;</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
       &quot;interesting&quot; 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
+      &lt;iostream&gt; 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>&lt;iosfwd&gt;</strong> should be included whenever you simply
+      need the <em>name</em> of an I/O-related class, such as
+      &quot;ofstream&quot; or &quot;basic_streambuf&quot;.  Like the name
+      implies, these are forward declarations.  (A word to all you fellow
+      old school programmers:  trying to forward declare classes like
+      &quot;class istream;&quot; won't work.  Look in the iosfwd header if
+      you'd like to know why.)  For example,
+   </p>
+   <pre>
+    #include &lt;iosfwd&gt;
+
+    class MyClass
+    {
+        ....
+        std::ifstream   input_file;
+    };
+
+    extern std::ostream&amp; operator&lt;&lt; (std::ostream&amp;, MyClass&amp;);
+   </pre>
+   <p><strong>&lt;ios&gt;</strong> declares the base classes for the entire
+      I/O stream hierarchy, std::ios_base and std::basic_ios&lt;charT&gt;, 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>&lt;streambuf&gt;</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>&lt;istream&gt;</strong>/<strong>&lt;ostream&gt;</strong> are
+      the headers to include when you are using the &gt;&gt;/&lt;&lt;
+      interface, or any of the other abstract stream formatting functions.
+      For example,
+   </p>
+   <pre>
+    #include &lt;istream&gt;
+
+    std::ostream&amp; operator&lt;&lt; (std::ostream&amp; os, MyClass&amp; c)
+    {
+       return os &lt;&lt; c.data1() &lt;&lt; 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>&lt;iomanip&gt;</strong> provides &quot;extractors and inserters
+      that alter information maintained by class ios_base and its dervied
+      classes,&quot; such as std::setprecision and std::setw.  If you need
+      to write expressions like <code>os &lt;&lt; setw(3);</code> or
+      <code>is &gt;&gt; setbase(8);</code>, you must include &lt;iomanip&gt;.
+   </p>
+   <p><strong>&lt;sstream&gt;</strong>/<strong>&lt;fstream&gt;</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>&lt;iostream&gt;</strong> provides the eight standard
+      global objects (cin, cout, etc).  To do this correctly, this header
+      also provides the contents of the &lt;istream&gt; and &lt;ostream&gt;
+      headers, but nothing else.  The contents of this header look like
+   </p>
+   <pre>
+    #include &lt;ostream&gt;
+    #include &lt;istream&gt;
+
+    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 &lt;iostream&gt; 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 &lt;iostream&gt; 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 />


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]