Add a flush operations to IOSink

sdk/lib/io/io_sink.dart

 // Copyright (c) 2013, 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.
 
 part of dart.io;
 
 /**
  * Helper class to wrap a [StreamConsumer<List<int>>] and provide
  * utility functions for writing to the StreamConsumer directly. The
  * [IOSink] buffers the input given by all [StringSink] methods and will delay
@@ skipping 28 matching lines @@
    * Writes an error to the consumer.
    */
   void addError(error);
 
   /**
    * Adds all elements of the given [stream] to `this`.
    */
   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();
 
   /**
    * Get a future that will complete when all synchronous have completed, or an
    * error happened. This future is identical to the future returned from close.
    */
   Future get done;
 }
@@ skipping 165 matching lines @@
   }
 
   void writeln([Object obj = ""]) {
     write(obj);
     write("\n");
   }
 
   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);
+    }
+  }
 }