Skip to content

R
riscv-gcc-1
Commit 664ce870 by Phil Edwards
Options

style.css: Update. 

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.

From-SVN: r59326
parent 840ceb34
Showing with 200 additions and 14 deletions
libstdc++-v3/ChangeLog
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.
2002-11-21 Phil Edwards <pme@gcc.gnu.org>
* docs/doxygen/TODO: Note change in clause 27 docs.
* include/bits/basic_ios.h, include/bits/fpos.h,
include/bits/ios_base.h, include/bits/stl_deque.h,
......
libstdc++-v3/docs/doxygen/style.css
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 }
libstdc++-v3/docs/html/17_intro/howto.html
......@@ -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 />
......
libstdc++-v3/docs/html/27_io/howto.html
......@@ -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 />
......@@ -558,6 +559,138 @@
&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>
<!-- ####################################################### -->
......
libstdc++-v3/docs/html/documentation.html
......@@ -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>
......
libstdc++-v3/docs/html/ext/lwg-defects.html
This source diff could not be displayed because it is too large. You can view the blob instead.
libstdc++-v3/docs/html/faq/index.html
......@@ -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>
......@@ -498,6 +499,18 @@ which is no longer available, thanks deja...-->
</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 />
<h1><a name="4_0">4.0 Known Bugs and Non-Bugs</a></h1>
<em>Note that this section can get rapdily outdated -- such is the
nature of an open-source project. For the latest information, join
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment