Update the streams interfaces

runtime/bin/input_stream.dart

 // Copyright (c) 2011, 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.
 
 /**
  * Input is read from a given input stream. Such an input stream can
  * be an endpoint, e.g., a socket or a file, or another input stream.
  * Multiple input streams can be chained together to operate collaboratively
  * on a given input.
  */
 interface InputStream {
   /**
-   * Reads [len] bytes into [buffer] buffer starting at [offset] offset.
-   * [callback] callback is invoked on completion unless it is null.
+   * Reads as much data as is available from the stream. If no data is
+   * available null will be returned.
    */
-  bool read(List<int> buffer, int offset, int len, void callback());
+  List<int> read();
 
   /**
-   * Reads data from the stream into a buffer until a given [pattern] occurs and
-   * hands that buffer over as an input to the registered [callback].
-   * The callback is not invoked if a read error occurs.
+   * The data handler gets called when data is available.
    */
-  void readUntil(List<int> pattern, void callback(List<int> buffer));
+  void set dataHandler(void callback());

[sra1, 2011/10/18 23:45:51]

There is a subtle relationship between the number of times read() may be called
and the number of times the callback is called.  Please specify this completely.

Questions I can't yet answer:

Will calling read() once in the callback always return a non-null value?

If the callback contains two read() calls, can the second call return data or
will the second one always return null?

Can the callback be called multiple times if there is no intervening read()?

Can I rely on the callback always being called so that the read()s are always
inside the callback?

If the InputStream is created and data is immediately available (e.g. a memory
based stream), does the callback get called? If so, during or after the setter?

[Søren Gjesse, 2011/10/19 14:45:41]

That should hopefully be the case - unless the OS somehow lies to us.
It can return data as new data might have arrived.
Most likely not.
Yes.
We should ensure that hte callback is called and always called from the event
loop not directly by the setter. The setter should then schedule the event.

+
+  /**
+   * The close handler gets called when the underlying communication
+   * channel is closed and no more data will become available. Not all
+   * types of communication channels will emit close events.
+   */
+  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(StreamError error));
 }
+
+
+interface StringInputStream factory _StringInputStream {

[dcarlson, 2011/10/18 17:26:19]

I'm surprised that it does not generate close/error events. Is this intended? 

[Søren Gjesse, 2011/10/19 14:45:41]

No, it should also generate the close and error events.

+  /**
+   * Decodes a binary input stream into characters using the specified
+   * encoding.
+   */
+  StringInputStream(InputStream input, [String encoding = "UTF-8"]);

[dcarlson, 2011/10/18 17:26:19]

Could we add a dataHandler as an optional param?

[Søren Gjesse, 2011/10/19 14:45:41]

Maybe, but then we should also do that for the InputStream as well. With named
optional arguments we could consider it.

+
+  /**
+   * Reads as many characters as is available from the stream. If no data is
+   * available null will be returned.
+   */
+  String read();
+
+  /**
+   * Returns the encoding used to decode the binary data into characters.
+   */
+  String get encoding();

[dcarlson, 2011/10/18 17:26:19]

Can the encoding be changed mid-stream?

[Søren Gjesse, 2011/10/19 14:45:41]

No.

+
+  /**
+   * The data handler gets called when data is available.
+   */
+  void set dataHandler(void callback());
+}
+
+
+interface ProcessingInputStream factory _ProcessingInputStream {
+  ProcessingInputStream(InputStream input);
+
+  /**
+   * Reads [len] bytes from the stream. When the bytes have been read the
+   * specified [callback] is called with the data.
+   */
+  void readFully(int len, void callback(List<int> buffer));
+
+  /**
+   * Reads data from the stream into a buffer until the specified [pattern]
+   * occurs. When the pattern occours the specified [callback] is called with
+   * the data including the pattern. If the pattern is not found before
+   * [maxLength] bytes have been received the error handler will be called.
+   */
+  void readUntil(List<int> pattern,
+                 void callback(List<int> buffer),
+                 [int maxLength = -1]);
+
+  /**
+   * Reads as much data as is available from the stream. The supplied
+   * callback is called with the data.
+   */
+  void read(void callback(List<int> data));
+
+  /**
+   * The close handler gets called when the underlying communication
+   * channel gets closed. Not all types of communication channels will
+   * emit close events.
+   */
+  void set closeHandler(void callback());

[sra1, 2011/10/18 23:45:51]

This implies that the underlying's closeHander setter is called, either with the
callback or a wrapped callback.
What happens to pre-existing closeHandler on the underlying?
What happens if input.closeHandler is called after processingInput.closeHandler?

If this is all dangerous behaviour, can it be made to cause an error?

[Søren Gjesse, 2011/10/19 14:45:41]

My take on this is that if you wrap an InputStream in a StringInputStream (or
some other stream) you should not touch the stream wrapped. This also goes for
calling read on the wrapped stream. I am not sure we can enforce that though.

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