diff options
| author | Phil Edwards <pme@gcc.gnu.org> | 2001-07-09 19:37:01 +0000 |
|---|---|---|
| committer | Phil Edwards <pme@gcc.gnu.org> | 2001-07-09 19:37:01 +0000 |
| commit | c6c222a89a7a9f5d76b785b394a500f6c9565a9e (patch) | |
| tree | 7170ee8bed9c0f886e5fbeb1698f610635ab4707 | |
| parent | 2b2c8b3e193c0af836177bc680c947488cacd4cd (diff) | |
| download | gcc-c6c222a89a7a9f5d76b785b394a500f6c9565a9e.zip gcc-c6c222a89a7a9f5d76b785b394a500f6c9565a9e.tar.gz gcc-c6c222a89a7a9f5d76b785b394a500f6c9565a9e.tar.bz2 | |
explanations.html: New file.
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.
From-SVN: r43868
| -rw-r--r-- | libstdc++-v3/ChangeLog | 7 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/27_io/howto.html | 58 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/configopts.html | 83 | ||||
| -rw-r--r-- | libstdc++-v3/docs/html/explanations.html | 74 |
4 files changed, 177 insertions, 45 deletions
diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 6fd9f64..0f51b44 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,10 @@ +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 diff --git a/libstdc++-v3/docs/html/27_io/howto.html b/libstdc++-v3/docs/html/27_io/howto.html index 8495f08..abb4c69 100644 --- a/libstdc++-v3/docs/html/27_io/howto.html +++ b/libstdc++-v3/docs/html/27_io/howto.html @@ -8,7 +8,7 @@ <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> @@ -29,6 +29,7 @@ <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> @@ -400,14 +401,65 @@ 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> diff --git a/libstdc++-v3/docs/html/configopts.html b/libstdc++-v3/docs/html/configopts.html index 69e48bc..513e54601 100644 --- a/libstdc++-v3/docs/html/configopts.html +++ b/libstdc++-v3/docs/html/configopts.html @@ -7,7 +7,7 @@ <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> @@ -66,56 +66,55 @@ options</A></H1> 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> @@ -148,14 +147,14 @@ options</A></H1> <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> @@ -212,7 +211,7 @@ options</A></H1> <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> diff --git a/libstdc++-v3/docs/html/explanations.html b/libstdc++-v3/docs/html/explanations.html new file mode 100644 index 0000000..eb88000 --- /dev/null +++ b/libstdc++-v3/docs/html/explanations.html @@ -0,0 +1,74 @@ +<!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> |