New OutputStream interface

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 edcec3ded6b8b9876665131297927813655da8af..80a3409132d73770131b21fd3fab06eb780fde18 100644
--- a/runtime/bin/output_stream.dart
+++ b/runtime/bin/output_stream.dart
@@ -7,13 +7,68 @@
  * be an endpoint, e.g., a socket or a file, or another output stream.
  * Multiple output streams can be chained together to operate collaboratively
  * on a given output.
+ *
+ * An output stream provides internal buffering of the data written
+ * through all calls to [write] and [writeFrom] if data cannot be
+ * written immediately to the communication channel. The callback set
+ * through [noPendingWriteHandler] can be used to to keep the rate of
+ * writing in sync with the rate the system can actually write data to
+ * the underlying communication channel.
  */
 interface OutputStream {
   /**
-   * Writes [len] bytes into [buffer] buffer starting at [offset] offset].
-   * If write succeedes true is returned. Otherwise false is returned
-   * and [callback] callback is invoked on completion.
+   * Writes the content of [buffer] to the stream. This will pass
+   * ownership of the specified buffer to the system and the caller
+   * should not change it. 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 send as

[Mads Ager (google), 2011/10/31 09:56:48]

will be sent

[Søren Gjesse, 2011/11/01 08:56:46]

Done.

+   * soon as possible.
    */
-  bool write(List<int> buffer, int offset, int len, void callback());
+  bool write(List<int> buffer);
+
+  /**
+   * Writes [len] bytes from buffer [buffer] starting at offset
+   * [offset] to the output stream. If [offset] is not specified the
+   * default is 0. If [len] is not specified the default is the length
+   * of the buffer passed. The system will copy the data to be written
+   * so the caller can safely change [buffer] afterwards. 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 send as soon as possible.

[Mads Ager (google), 2011/10/31 09:56:48]

will be sent

[Søren Gjesse, 2011/11/01 08:56:46]

Done.

+   */
+  bool writeFrom(List<int> buffer, [int offset, int len]);
+
+  /**
+   * Indicate that all data has been written to the output
+   * stream. When all data has been written to communication channel

[Mads Ager (google), 2011/10/31 09:56:48]

to communication -> to the communication

[Søren Gjesse, 2011/11/01 08:56:46]

Done.

+   * it will be closed.
+   */
+  void end();
+
+  /**
+   * Close the communication channel immediately ignoring any buffered
+   * data.
+   */
+  void close();
+
+  /**
+   * The no pending write handler gets called when the internal OS
+   * buffers have been flushed. This callback can be used to keep the
+   * rate of writing in sync with the rate the system can write data
+   * to the underlying communication channel.
+   */
+  void set noPendingWriteHandler(void callback());
+
+  /*
+   * The close handler gets called when the underlying communication
+   * channel have been closed.

[Mads Ager (google), 2011/10/31 09:56:48]

have -> has

[Søren Gjesse, 2011/11/01 08:56:46]

Done.

+   */
+  void set closeHandler(void callback());
+
+  /**
+   * The error handler gets called when the underlying communication
+   * channel gets into some kind of error situation.
+   */
+  void set errorHandler(void callback());

[Mads Ager (google), 2011/10/31 09:56:48]

Should the callback take a string or some other error indication? We don't have
to add that now.

[Søren Gjesse, 2011/11/01 08:56:46]

Maybe this should be an exception object. We will determine later.

 }