Add method flush to output stream

runtime/bin/output_stream.dart

Index: runtime/bin/output_stream.dart
diff --git a/runtime/bin/output_stream.dart b/runtime/bin/output_stream.dart
index 6583599a7c295b1f7fc53affa7901d3dbcc62517..7e8a13c9b8aec18b3b1e926de1be2992145ba55c 100644
--- a/runtime/bin/output_stream.dart
+++ b/runtime/bin/output_stream.dart
@@ -51,6 +51,13 @@ interface OutputStream {
   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.