[v3] documentation on cstdio and synchronization
Phil Edwards
pedwards@disaster.jaj.com
Mon Jul 9 12:41:00 GMT 2001
Some notes on the --enable-cstdio=foo decisions as requested, and the pain
of global streams sync'ing. Applied to trunk and branch.
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.
Index: docs/html/configopts.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/configopts.html,v
retrieving revision 1.10
diff -u -3 -p -r1.10 configopts.html
--- configopts.html 2001/04/20 08:59:25 1.10
+++ configopts.html 2001/07/09 19:34:50
@@ -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>
Index: docs/html/27_io/howto.html
===================================================================
RCS file: /cvs/gcc/gcc/libstdc++-v3/docs/html/27_io/howto.html,v
retrieving revision 1.5
diff -u -3 -p -r1.5 howto.html
--- howto.html 2001/05/30 21:55:03 1.5
+++ howto.html 2001/07/09 19:34:50
@@ -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,10 +401,61 @@
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>.
More information about the Libstdc++
mailing list