From c6c222a89a7a9f5d76b785b394a500f6c9565a9e Mon Sep 17 00:00:00 2001 From: Phil Edwards Date: Mon, 9 Jul 2001 19:37:01 +0000 Subject: [PATCH] explanations.html: New file. 2001-07-09 Phil Edwards * 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 --- libstdc++-v3/ChangeLog | 7 ++ libstdc++-v3/docs/html/27_io/howto.html | 58 ++++++++++++++++- libstdc++-v3/docs/html/configopts.html | 83 ++++++++++++------------ libstdc++-v3/docs/html/explanations.html | 74 +++++++++++++++++++++ 4 files changed, 177 insertions(+), 45 deletions(-) create mode 100644 libstdc++-v3/docs/html/explanations.html diff --git a/libstdc++-v3/ChangeLog b/libstdc++-v3/ChangeLog index 6fd9f64f86d..0f51b444c03 100644 --- a/libstdc++-v3/ChangeLog +++ b/libstdc++-v3/ChangeLog @@ -1,3 +1,10 @@ +2001-07-09 Phil Edwards + + * 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 * 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 8495f081b29..abb4c698aaf 100644 --- a/libstdc++-v3/docs/html/27_io/howto.html +++ b/libstdc++-v3/docs/html/27_io/howto.html @@ -8,7 +8,7 @@ libstdc++-v3 HOWTO: Chapter 27 - + @@ -29,6 +29,7 @@

What is this <sstream>/stringstreams thing?

Pathetic performance? Ditch C.

It sounds like a flame on C, but it isn't. Really. Calm down. + I'm just saying it to get your attention. +

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: +

+     #include <iostream>
+     #include <cstdio>
+
+     std::cout << "Hel";
+     std::printf ("lo, worl");
+     std::cout << "d!\n";
+

+ This must do what you think it does. +

Alert members of the audience will immediately notice that buffering + is going to make a hash of the output unless special steps are taken. +

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 tricky to get right.) + The upside is that correctness is insured. The downside is that + writing through cout 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. +

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 +

+     #include any of the I/O headers such as ios, iostream, etc
+
+     std::sync_with_stdio(false);
+

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 cout and + company will become fully buffered on their own. +

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. +

+ -

Comments and suggestions are welcome, and may be sent to the mailing list. -
$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 $

diff --git a/libstdc++-v3/docs/html/configopts.html b/libstdc++-v3/docs/html/configopts.html index 69e48bcb495..513e546019a 100644 --- a/libstdc++-v3/docs/html/configopts.html +++ b/libstdc++-v3/docs/html/configopts.html @@ -7,7 +7,7 @@ libstdc++-v3 configure options - + @@ -66,56 +66,55 @@ options I/O package (from glibc, 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 here.

--enable-sjlj-exceptions -

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. +

--enable-sjlj-exceptions +

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.

--enable-clocale

This is an abbreviated form of '--enable-clocale=generic' (described next).

--enable-clocale=MODEL

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 glibc, the GNU C - library), or 'generic' to use a generic "C" abstraction - which consists of "C" locale info. The default is - 'generic'. +

--enable-clocale=MODEL +

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 + glibc, the GNU C + library), or 'generic' to use a generic "C" abstraction + which consists of "C" locale info. The default is 'generic'.

--enable-c99

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 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.

--enable-long-long

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).

--enable-cheaders=OPTION @@ -148,14 +147,14 @@ options

--enable-version-specific-runtime-libs

Specify that run-time libraries should be installed in the - compiler-specific subdirectory (i.e., - $(libdir)/gcc-lib/$(target_alias)/$(gcc_version)) - instead of $(libdir). 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 - $(libdir)/gcc-lib/$(target_alias)/$(gcc_version)/include/g++, - unless you also specify - --with-gxx-include-dir=_dirname_ during configuration. + compiler-specific subdirectory (i.e., + ${libdir}/gcc-lib/${target_alias}/${gcc_version}) + instead of ${libdir}. 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 + ${libdir}/gcc-lib/${target_alias}/${gcc_version}/include/g++, + unless you also specify + --with-gxx-include-dir=dirname during configuration.

--with-gxx-include-dir=<include-files dir> @@ -212,7 +211,7 @@ options

-$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 $

diff --git a/libstdc++-v3/docs/html/explanations.html b/libstdc++-v3/docs/html/explanations.html new file mode 100644 index 00000000000..eb88000ffc9 --- /dev/null +++ b/libstdc++-v3/docs/html/explanations.html @@ -0,0 +1,74 @@ + + + + + + + + Explanatory notes about libstdc++-v3 design + + + + + +

Explanatory notes about libstdc++-v3 +design

+ +

The latest version of this document is always available at + + http://gcc.gnu.org/onlinedocs/libstdc++/explanations.html. +

+ +

To the libstdc++-v3 homepage. + + + +

"I/O packages", `--enable-cstdio`

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 + for the programmer but for the + implementors as well. +

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. +

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). +

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. +

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 __c_file_type and + __c_lock (for the stdio case, these are FILE (as in + "FILE*") and a simple POSIX mutex, respectively). An + interface class called __basic_file must also be filled in; + as an example, for the stdio case, these member functions are all + inline calles to fread, fwrite, etc. +

Return to the top of the page or + to the homepage. +

+ + + + +

+$Id$ +

+ + + + -- 2.30.2

Pathetic performance? Ditch C.

Explanatory notes about libstdc++-v3 +design

"I/O packages", --enable-cstdio

"I/O packages", `--enable-cstdio`