This is the mail archive of the gcc-patches@gcc.gnu.org mailing list for the GCC project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

[v3] documentation on cstdio and synchronization



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 &quot;C&quot;
-        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 &quot;C&quot; abstraction
- which consists of &quot;C&quot; 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 &quot;C&quot; abstraction
+        which consists of &quot;C&quot; locale info.  The default is 'generic'.
      </P>
 
  <DT><TT>--enable-c99  </TT>
  <DD><P>The &quot;long long&quot; 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 &quot;as
+        if&quot; 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 &quot;long long&quot; type was introduced in C99.  It is
         provided as a GNU extension to C++98 in g++.  This flag builds
-        support for &quot;long long&quot; 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 &quot;C&quot; headers by default (ie cmath
-        not math.h) or add appropriate compile-time flags to all
-        compile lines to allow &quot;C&quot; 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 &quot;long long&quot; 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 &quot;C&quot;
+        headers by default (i.e., &lt;cmath&gt; not &lt;math.h&gt;)
+        or add appropriate compile-time flags to all compile lines to
+        allow &quot;C&quot; 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=&lt;include-files dir&gt;</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 &lt;sstream&gt;/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 &lt;iostream&gt;
+     #include &lt;cstdio&gt;
+
+     std::cout &lt;&lt; &quot;Hel&quot;;
+     std::printf (&quot;lo, worl&quot;);
+     std::cout &lt;&lt; &quot;d!\n&quot;;
+      </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>.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]