Change singleSubscription/multiSubscription to normal/broadcast.

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,
  * or to temporarily pause events from the stream.
  *
- * When an event is fired, all listeners at that time are informed.
+ * When an event is fired, the listeners at that time are informed.
  * If a listener is added or removed while an event is being fired, the change
  * will only take effect after the event is completely fired.
  *
  * 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 too.
  *
- * There are two kinds of streams: Single-subscription streams and
- * multi-subscription streams.
+ * There are two kinds of streams: The normal "single-subscription" streams and
+ * "broadcast" 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
+ * A single-subscription stream allows only a single listener at a time.
+ * It holds back events until it gets a listener, and it may exhaust
  * 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
+ * A broadcast 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.
+ * Braodcast streams are used for independent events/observers.
  *
- * The default implementation of [isSingleSubscription] and
- * [asMultiSubscriptionStream] are assuming this is a single-subscription stream
- * and a multi-subscription stream inheriting from [Stream] must override these
- * to return [:false:] and [:this:] respectively.
+ * The default implementation of [isBroadcast] and
+ * [asBroadcastStream] are assuming this is a single-subscription stream
+ * and a broadcast stream inheriting from [Stream] must override these
+ * to return [:true:] and [:this:] respectively.
  */
 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.
    */
@@ skipping 12 matching lines @@
 
   /**
    * Creates a single-subscription stream that gets its data from [data].
    */
   factory Stream.fromIterable(Iterable<T> data) {
     _PendingEvents iterableEvents = new _IterablePendingEvents<T>(data);
     return new _GeneratedSingleStreamImpl<T>(iterableEvents);
   }
 
   /**
-   * Whether the stream is a single-subscription stream.
+   * Whether the stream is a broadcast stream.
    */
-  bool get isSingleSubscription => true;
+  bool get isBroadcast => false;

[Bob Nystrom, 2013/01/24 17:29:14]

Have you considered having an actual distinct type for broadcast streams?

I ask because I know Nathan got burned a couple of times trying to add a
listener to a single-cast stream that already had one. It would be nice if the
type system could help us statically avoid those bugs.

 
   /**
    * Returns a multi-subscription stream that produces the same events as this.
    *
    * If this stream is single-subscription, return a new stream that allows
    * multiple subscribers. It will subscribe to this stream when its first
    * subscriber is added, and unsubscribe again when the last subscription is
    * cancelled.
    *
-   * If this stream is already multi-subscriber, it is returned unmodified.
+   * If this stream is already a broadcast stream, it is returned unmodified.
    */
-  Stream<T> asMultiSubscriberStream() {
+  Stream<T> asBroadcastStream() {
     return new _SingleStreamMultiplexer<T>(this);
   }
 
   /**
    * Stream that outputs events from the [sources] in cyclic order.
    *
    * The merged streams are paused and resumed in order to ensure the proper
    * order of output events.
    */
   factory Stream.cyclic(Iterable<Stream> sources) {
@@ skipping 729 matching lines @@
   void signalError(AsyncError errorEvent);
   void close();
 }
 
 /** [Stream] wrapper that only exposes the [Stream] interface. */
 class StreamView<T> extends Stream<T> {
   Stream<T> _stream;
 
   StreamView(this._stream);
 
-  bool get isSingleSubscription => _stream.isSingleSubscription;
+  bool get isBroadcast => _stream.isBroadcast;
+
+  Stream<T> asBroadcastStream() => _stream.asBroadcastStream();
 
   StreamSubscription<T> listen(void onData(T value),
                                { void onError(AsyncError error),
                                  void onDone(),
                                  bool unsubscribeOnError }) {
     return _stream.listen(onData, onError: onError, onDone: onDone,
                           unsubscribeOnError: unsubscribeOnError);
   }
 }
 
@@ skipping 76 matching lines @@
     sink.signalError(error);
   }
 
   /**
    * Handle an incoming done event.
    */
   void handleDone(StreamSink<T> sink) {
     sink.close();
   }
 }