Add method flush to output stream

runtime/bin/output_stream.dart

 // Copyright (c) 2012, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 /**
  * Output streams are used to write data sequentially to a data
  * destination e.g. a connected socket or an open file.
  *
  * An output stream provides internal buffering of the data written
  * through all calls to [write] and [writeFrom] if data cannot be
@@ skipping 33 matching lines @@
    * Write a string to the stream using the given [encoding].The
    * default encoding is UTF-8 - [:Encoding.UTF_8:].
    *
    * Returns true if the data could be written to the underlying
    * communication channel immediately. Otherwise the data is buffered
    * by the output stream and will be sent as soon as possible.
    */
   bool writeString(String string, [Encoding encoding]);
 
   /**
+   * Flushes data from any internal buffers as soon as possible. Note
+   * that the actual meaning of calling [flush] will depend on the
+   * actual type of the underlying communication channel.
+   */
+  void flush();

[Mads Ager (google), 2012/04/17 11:56:44]

Shouldn't there be some sort of notification that the stream has actually been
flushed?

If you do:

stream.write(data);
stream.flush();

It seems to me that you are no wiser than if you had just done the write alone?

Maybe the flush call should either count as a write and onNoPendingWrites should
be called or there should be a callback here?

If we go for a callback I think we should update the documentation for
onNoPendingWrites. It says that it is called when the internal OS buffers have
been flushed. We need to make it clear what the relationship between flush and
onNoPendingWrites is.

[Søren Gjesse, 2012/04/17 13:14:19]

The only reason for having flush is that even when there you get a
noNoPendingWrites callback the data written might still be sitting in an
internal buffer. This is only an issue for files where there is the possibility
that the OS will hold data in memory for some time.

If you do

stream.write(data);
stream.flush();

Then you are somewhat wiser in that, for a file, data will be on the disk "very
soon" and for a non file nothing happens.

+
+  /**
    * Indicate that all data has been written to the output
    * stream. When all data has been written to the communication
    * channel it will be closed.
    */
   void close();
 
   /**
    * Close the communication channel immediately ignoring any buffered
    * data.
    */
@@ skipping 14 matching lines @@
    */
   void set onClosed(void callback());
 
   /**
    * Sets the handler that gets called when the underlying
    * communication channel gets into some kind of error situation.
    */
   void set onError(void callback(Exception e));
 }