Make StreamController's unnamed constructor create a single-sub stream.

sdk/lib/async/stream.dart

 // Copyright (c) 2012, 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.async;
 
 // -------------------------------------------------------------------
 // Core Stream types
 // -------------------------------------------------------------------
 
+/**
+ * A source of asynchronous data events.
+ *
+ * A Stream provides a sequence of events. Each event is either a data event or
+ * an error event, representing the result of a single computation. When the
+ * Stream is exhausted, it may send a single "done" event.
+ *
+ * You can [listen] on a stream to receive the events it sends. When you listen,
+ * you receive a [StreamSubscription] object that can be used to stop listening
+ * again, or to temporarily pause events from the stream.

[floitsch, 2013/01/14 16:42:45]

-again- (remove)

[Lasse Reichstein Nielsen, 2013/01/15 09:08:54]

Done.

+ *
+ * When an event is fired, all listeners at that time are informed.
+ * If a listener is added or removed while an event is being fired, the change

[floitsch, 2013/01/14 16:42:45]

maybe?
Subscription changes while an event is fired are queued and handled after the
event has been treated.

[Lasse Reichstein Nielsen, 2013/01/15 09:08:54]

I haven't talked about "subscriptions" as a concept at this point, and I try not
to.
Which might be silly because we do it everywhere else.

[Lasse Reichstein Nielsen, 2013/01/15 09:08:54]

Also, not *really* true because subscriptions are dropped just before their done
event is sent.

+ * will only take effect after the event is completely fired.
+ *
+ * Streams always buffer events that come in while the Stream is paused, and

[floitsch, 2013/01/14 16:42:45]

I wouldn't say this. Rather:
Streams always respect "pause" requests. If necessary they need to buffer their
input, but often, and preferably, they can simply request their input to pause.

[Lasse Reichstein Nielsen, 2013/01/15 09:08:54]

Done.

+ * generally try to throttle the source of their events while they
+ * are paused to avoid bloating buffers.
+ *
+ * There are two kinds of streams: Single-subscription streams and
+ * multi-subscription streams.
+ *
+ * A single-subscription stream allows only a single listener in its entire
+ * life-cycle. It holds back events until it gets a listener, and it exhausts
+ * itself when the listener is unsubscribed, even if the stream wasn't done.
+ *
+ * Single-subscription streams are generally used for streaming parts of
+ * contiguous data like file I/O.
+ *
+ * A multi-subscription stream allows any number of listeners, and it fires
+ * its events when they are ready, whether there are listeners or not.
+ *
+ * Multi-subscription streams are used for independent events/observers.
+ */
 abstract class Stream<T> {
   Stream();
 
+  /**
+   * Creates a new single-subscription stream from the future.
+   *
+   * When the future completes, the stream will fire one event, either
+   * data or error, and then close with a done-event.
+   */
   factory Stream.fromFuture(Future<T> future) {
     _StreamImpl<T> stream = new _MultiStreamImpl<T>();
     future.then((value) {
         stream._add(value);
         stream._close();
       },
       onError: (error) {
         stream._signalError(error);
         stream._close();
       });
@@ skipping 848 matching lines @@
     sink.signalError(error);
   }
 
   /**
    * Handle an incoming done event.
    */
   void handleDone(StreamSink<T> sink) {
     sink.close();
   }
 }