Add a flush operations to IOSink

sdk/lib/io/io_sink.dart

Index: sdk/lib/io/io_sink.dart
diff --git a/sdk/lib/io/io_sink.dart b/sdk/lib/io/io_sink.dart
index b954a86d5ffeed71ac9f0e15677613193ed04251..f2685a3ec2181c9c9e53190940fc80f12c5692ed 100644
--- a/sdk/lib/io/io_sink.dart
+++ b/sdk/lib/io/io_sink.dart
@@ -46,6 +46,25 @@ abstract class IOSink implements StreamSink<List<int>>, StringSink {
   Future addStream(Stream<List<int>> stream);
 
   /**
+   * Flushes the data currently added to the stream to underlying
+   * storage if possible.
+   *
+   * Returns a future which completes when the flush operation is
+   * complete.
+   *
+   * Currently this method only has effect if the target of the
+   * [IOSink] is a file. For all other targets this does nothing
+   * and the returned future completed immediately.
+   *
+   * If [add] is used to write to the [IOSink] all data written using
+   * [add] before calling [flush] will be flushed. If [addStream] is
+   * used and [flush] is called before the future returned from
+   * [addStream] is complete the abount of data which will be flushed
+   * is undefined.
+   */
+  Future flush();
+
+  /**
    * Close the target.
    */
   Future close();
@@ -231,4 +250,12 @@ class _IOSinkImpl extends _StreamSinkImpl<List<int>> implements IOSink {
   void writeCharCode(int charCode) {
     write(new String.fromCharCode(charCode));
   }
+
+  Future flush() {

[Anders Johnsen, 2013/08/01 13:54:28]

So, several comments and concerns about this approach:

1) It's not very portable. It only works for files, and will be
near-to-impossible to implement for other data-types. IOSink is exposed as a
class for other users, where they expect this stuff should work for their
supplied StreamConsumer.

2) Calling flush directly like so will ignore anything currently queued. That
is, it's only flushing the current operation, not what's currently buffered by
the IOSinks StreamController (I may be mistaken, but that's how I read the
code).

I would recommend another direction that may not flush stuff directly for files
like this does, however, it'll be portable. Let 'flush()' return
'Future.value()' in the case the stream is not paused. If paused, return a
future that will complete once the stream is resumed again. That should ensure
that it's possible to implement a way for flushing any data currently in
buffers, all the way down to the target(may it be OS). The question is then what
to do in the case of an add immediate after flush() - that can definitely be
debated.

[Søren Gjesse, 2013/08/01 14:29:18]

As the comment above states this only does anything for files and also only
works reliably when using add or when the future from addStream has completed.
As far as I can see our implementation will send data written directly to the OS
when add is used (sync StreamController in IOSink implementation), and therefore
sending flush will work.

I don't think this makes much sense for anything but files, and also I don't see
it have much meaning while addStream is used.

I am fine with dropping this and stating that if flushing file content to disk
is required then one should use a RandomAccessFile.

+    if (_target is _FileStreamConsumer) {
+      return _target.flush();
+    } else {
+      return new Future.value(null);
+    }
+  }
 }