+2001-07-09 Phil Edwards <pme@sources.redhat.com>
+
+ * docs/html/explanations.html: New file.
+ * docs/html/configopts.html: Link to it to provide more notes
+ on cstdio. Minor markup and spacing fixes.
+ * docs/html/27_io/howto.html: Talk about sync_with_stdio.
+
2001-07-09 Kriang Lerdsuwanakij <lerdsuwa@users.sourceforge.net>
* include/bits/valarray_meta.h (_Expr::operator+): Use qualified id
<META NAME="GENERATOR" CONTENT="vi and eight fingers">
<TITLE>libstdc++-v3 HOWTO: Chapter 27</TITLE>
<LINK REL=StyleSheet HREF="../lib3styles.css">
-<!-- $Id: howto.html,v 1.4 2001/04/03 00:26:56 pme Exp $ -->
+<!-- $Id: howto.html,v 1.5 2001/05/30 21:55:03 pme Exp $ -->
</HEAD>
<BODY>
<LI><A HREF="#5">What is this <sstream>/stringstreams thing?</A>
<LI><A HREF="#6">Deriving a stream buffer</A>
<LI><A HREF="#7">More on binary I/O</A>
+ <LI><A HREF="#8">Pathetic performance? Ditch C.</A>
</UL>
<HR>
a portable binary format.
</P>
+<HR>
+<H2><A NAME="8">Pathetic performance? Ditch C.</A></H2>
+ <P>It sounds like a flame on C, but it isn't. Really. Calm down.
+ I'm just saying it to get your attention.
+ </P>
+ <P>Because the C++ library includes the C library, both C-style and
+ C++-style I/O have to work at the same time. For example:
+ <PRE>
+ #include <iostream>
+ #include <cstdio>
+
+ std::cout << "Hel";
+ std::printf ("lo, worl");
+ std::cout << "d!\n";
+ </PRE>
+ This must do what you think it does.
+ </P>
+ <P>Alert members of the audience will immediately notice that buffering
+ is going to make a hash of the output unless special steps are taken.
+ </P>
+ <P>The special steps taken by libstdc++, at least for version 3.0,
+ involve doing very little buffering for the standard streams, leaving
+ most of the buffering to the underlying C library. (This kind of
+ thing is <A HREF="../explanations.html#cstdio">tricky to get right</A>.)
+ The upside is that correctness is insured. The downside is that
+ writing through <TT>cout</TT> can quite easily lead to awful
+ performance when the C++ I/O library is layered on top of the C I/O
+ library (as it is for 3.0 by default). Some patches are in the
+ works which should improve the situation for 3.1.
+ </P>
+ <P>However, the C and C++ standard streams only need to be kept in sync
+ when both libraries' facilities are in use. If your program only uses
+ C++ I/O, then there's no need to sync with the C streams. The right
+ thing to do in this case is to call
+ <PRE>
+ #include <EM>any of the I/O headers such as ios, iostream, etc</EM>
+
+ std::sync_with_stdio(false);
+ </PRE>
+ </P>
+ <P>You must do this before performing any I/O via the C++ stream objects.
+ Once you call this, the C++ streams will operate independantly of the
+ (unused) C streams. For GCC 3.0, this means that <TT>cout</TT> and
+ company will become fully buffered on their own.
+ </P>
+ <P>Note, by the way, that the synchronization requirement only applies to
+ the standard streams (cin, cout, cerr, clog, and thier wide-character
+ counterparts). File stream objects that you create yourself have no
+ such requirement and are fully buffered.
+ </P>
+
<!-- ####################################################### -->
-<HR>
+<HR><BR><BR><BR><BR><BR><BR><BR><BR>
<P CLASS="fineprint"><EM>
Comments and suggestions are welcome, and may be sent to
<A HREF="mailto:libstdc++@gcc.gnu.org">the mailing list</A>.
-<BR> $Id: howto.html,v 1.4 2001/04/03 00:26:56 pme Exp $
+<BR> $Id: howto.html,v 1.5 2001/05/30 21:55:03 pme Exp $
</EM></P>
<META NAME="GENERATOR" CONTENT="vi and eight fingers">
<TITLE>libstdc++-v3 configure options</TITLE>
<LINK REL=StyleSheet HREF="lib3styles.css">
-<!-- $Id: configopts.html,v 1.9 2001/04/06 01:47:11 bkoz Exp $ -->
+<!-- $Id: configopts.html,v 1.10 2001/04/20 08:59:25 bkoz Exp $ -->
</HEAD>
<BODY>
I/O package (from
<A HREF="http://sources.redhat.com/glibc/">glibc</A>, the
GNU C library), or 'stdio' to use a generic "C"
- abstraction. The default is 'stdio'.
+ abstraction. The default is 'stdio'. A longer explanation
+ is <A HREF="explanations.html#cstdio">here</A>.
</P>
- <DT><TT>--enable-sjlj-exceptions </TT>
- <DD><P> Forces old, short-jump/long-jump exception handling model. If
- at all possible, the new, frame unwinding exception handling routines
- should be used instead, as they significantly reduce both runtime
- memory usage and executable size.
+ <DT><TT>--enable-sjlj-exceptions </TT>
+ <DD><P>Forces old, short-jump/long-jump exception handling model. If
+ at all possible, the new, frame unwinding exception handling routines
+ should be used instead, as they significantly reduce both runtime
+ memory usage and executable size.
</P>
-
<DT><TT>--enable-clocale </TT>
<DD><P>This is an abbreviated form of <TT>'--enable-clocale=generic'</TT>
(described next).
</P>
- <DT><TT>--enable-clocale=MODEL </TT> <DD><P>Select a target-specific
- underlying locale package. The choices are 'gnu' to specify an X/Open
- (IEEE Std. 1003.1-200x) model based on langinfo/iconv (from <A
- HREF="http://sources.redhat.com/glibc/">glibc</A>, the GNU C
- library), or 'generic' to use a generic "C" abstraction
- which consists of "C" locale info. The default is
- 'generic'.
+ <DT><TT>--enable-clocale=MODEL </TT>
+ <DD><P>Select a target-specific underlying locale package. The choices
+ are 'gnu' to specify an X/Open (IEEE Std. 1003.1-200x) model based
+ on langinfo/iconv (from
+ <A HREF="http://sources.redhat.com/glibc/">glibc</A>, the GNU C
+ library), or 'generic' to use a generic "C" abstraction
+ which consists of "C" locale info. The default is 'generic'.
</P>
<DT><TT>--enable-c99 </TT>
<DD><P>The "long long" type was introduced in C99, along
- with bunches of other functions for wide characters, and math
- classification macros, etc. If enabled, all C99 functions not
- specified by the C++ standard will be put into namespace c99,
- and then all names in the c99 namespace will be injected into
- namespace std, so that C99 functions can be used "as if" they
- were in the C++ standard (as they will eventually be in some
- future revision of the standard, without a doubt.) By default,
- C99 support is on, assuming the configure probes find all the
- necessary functions and bits necessary.
+ with bunches of other functions for wide characters, and math
+ classification macros, etc. If enabled, all C99 functions not
+ specified by the C++ standard will be put into <TT>namespace
+ c99</TT>, and then all names in the c99 namespace will be injected
+ into namespace std, so that C99 functions can be used "as
+ if" they were in the C++ standard (as they will eventually
+ be in some future revision of the standard, without a doubt).
+ By default, C99 support is on, assuming the configure probes find
+ all the necessary functions and bits necessary.
</P>
<DT><TT>--enable-long-long </TT>
<DD><P>The "long long" type was introduced in C99. It is
provided as a GNU extension to C++98 in g++. This flag builds
- support for "long long" into the library
- (specialized templates and the like for iostreams). This
- option is on by default: if enabled, users will have to either
- use the new-style "C" headers by default (ie cmath
- not math.h) or add appropriate compile-time flags to all
- compile lines to allow "C" visibility of this
- feature (on GNU/Linux, the flag is -D_ISOC99_SOURCE, which is
- added automatically via CPLUSPLUS_CPP_SPEC's addition of
- _GNU_SOURCE).
+ support for "long long" into the library (specialized
+ templates and the like for iostreams). This option is on by default:
+ if enabled, users will have to either use the new-style "C"
+ headers by default (i.e., <cmath> not <math.h>)
+ or add appropriate compile-time flags to all compile lines to
+ allow "C" visibility of this feature (on GNU/Linux,
+ the flag is -D_ISOC99_SOURCE, which is added automatically via
+ CPLUSPLUS_CPP_SPEC's addition of _GNU_SOURCE).
</P>
<DT><TT>--enable-cheaders=OPTION </TT>
<DT><TT>--enable-version-specific-runtime-libs </TT>
<DD><P>Specify that run-time libraries should be installed in the
- compiler-specific subdirectory (i.e.,
- <TT>$(libdir)/gcc-lib/$(target_alias)/$(gcc_version)</TT>)
- instead of <TT>$(libdir)</TT>. This option is useful if you
- intend to use several versions of gcc in parallel. In addition,
- libstdc++'s include files will be installed in
- <TT>$(libdir)/gcc-lib/$(target_alias)/$(gcc_version)/include/g++</TT>,
- unless you also specify
- <TT>--with-gxx-include-dir=_dirname_</TT> during configuration.
+ compiler-specific subdirectory (i.e.,
+ <TT>${libdir}/gcc-lib/${target_alias}/${gcc_version}</TT>)
+ instead of <TT>${libdir}</TT>. This option is useful if you
+ intend to use several versions of gcc in parallel. In addition,
+ libstdc++'s include files will be installed in
+ <TT>${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++</TT>,
+ unless you also specify
+ <TT>--with-gxx-include-dir=<EM>dirname</EM></TT> during configuration.
</P>
<DT><TT>--with-gxx-include-dir=<include-files dir></TT>
<HR>
<P CLASS="fineprint"><EM>
-$Id: configopts.html,v 1.9 2001/04/06 01:47:11 bkoz Exp $
+$Id: configopts.html,v 1.10 2001/04/20 08:59:25 bkoz Exp $
</EM></P>
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0//EN">
+<HTML>
+<HEAD>
+ <META NAME="AUTHOR" CONTENT="pme@sources.redhat.com (Phil Edwards)">
+ <META NAME="KEYWORDS" CONTENT="libstdc++, libstdc++-v3, GCC, g++">
+ <META NAME="DESCRIPTION" CONTENT="Explanatory notes about libstdc++-v3.">
+ <META NAME="GENERATOR" CONTENT="vi and eight fingers">
+ <TITLE>Explanatory notes about libstdc++-v3 design</TITLE>
+<LINK REL=StyleSheet HREF="lib3styles.css">
+<!-- $Id: configopts.html,v 1.10 2001/04/20 08:59:25 bkoz Exp $ -->
+</HEAD>
+<BODY>
+
+<H1 CLASS="centered"><A NAME="top">Explanatory notes about libstdc++-v3
+design</A></H1>
+
+<P>The latest version of this document is always available at
+ <A HREF="http://gcc.gnu.org/onlinedocs/libstdc++/explanations.html">
+ http://gcc.gnu.org/onlinedocs/libstdc++/explanations.html</A>.
+</P>
+
+<P>To the <A HREF="http://gcc.gnu.org/libstdc++/">libstdc++-v3 homepage</A>.
+
+
+<!-- ####################################################### -->
+<HR>
+<A NAME="cstdio"><H3>"I/O packages", <TT>--enable-cstdio</TT></H3></A>
+<P>In addition to all the nifty things which C++ can do for I/O, its library
+ also includes all of the I/O capabilites of C. Making them work together
+ can be a challenge, not only
+ <A HREF="27_io/howto.html#8">for the programmer</A> but for the
+ implementors as well.
+</P>
+<P>There are two ways to do a C++ library: the cool way, and the easy way.
+ More specifically, the cool-but-easy-to-get-wrong way, and the
+ easy-to-guarantee-correct-behavior way. For 3.0, the easy way is used.
+</P>
+<P>Choosing 'stdio' is the easy way. It builds a C++ library which forwards
+ all operations to the C library. Many of the C++ I/O functions are
+ specified in the standard 'as if' they called a certain C function; the
+ easiest way to get it correct is to actually call that function. The
+ disadvantage is that the C++ code will run slower (fortunately, the layer
+ is thin).
+</P>
+<P>Choosing 'libio' is the cool way; it allows C++ and C to share some
+ buffers. It's disabled because of tricky synchronization issues. Other
+ cool ways (various methods of sharing resources between C and C++
+ facilities, instead of layering) are possible. This approach can speed
+ up I/O significantly.
+</P>
+<P>Other packages are possible. For a new package, a header must be
+ written to provide types like streamsize (usually just a typedef), as
+ well as some internal types like<TT> __c_file_type </TT> and
+ <TT> __c_lock </TT> (for the stdio case, these are FILE (as in
+ "FILE*") and a simple POSIX mutex, respectively). An
+ interface class called <TT> __basic_file </TT> must also be filled in;
+ as an example, for the stdio case, these member functions are all
+ inline calles to fread, fwrite, etc.
+</P>
+<P>Return <A HREF="#top">to the top of the page</A> or
+ <A HREF="http://gcc.gnu.org/libstdc++/">to the homepage</A>.
+</P>
+
+
+<!-- ####################################################### -->
+
+<HR>
+<P CLASS="fineprint"><EM>
+$Id$
+</EM></P>
+
+
+</BODY>
+</HTML>
projects / gcc.git / commitdiff