Add StreamChannel.withGuarantees and StreamChannelController.

lib/stream_channel.dart

 // Copyright (c) 2016, 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.
 
 import 'dart:async';
 
 import 'package:async/async.dart';
 
+import 'src/guarantee_channel.dart';
 import 'src/stream_channel_transformer.dart';
 
 export 'src/delegating_stream_channel.dart';
 export 'src/isolate_channel.dart';
 export 'src/json_document_transformer.dart';
 export 'src/multi_channel.dart';
 export 'src/stream_channel_completer.dart';
+export 'src/stream_channel_controller.dart';
 export 'src/stream_channel_transformer.dart';
 
 /// An abstract class representing a two-way communication channel.
 ///
 /// Users should consider the [stream] emitting a "done" event to be the
 /// canonical indicator that the channel has closed. If they wish to close the
 /// channel, they should close the [sink]—canceling the stream subscription is
 /// not sufficient. Protocol errors may be emitted through the stream or through
 /// [Sink.done], depending on their underlying cause. Note that the sink may
 /// silently drop events if the channel closes before [Sink.close] is called.
@@ skipping 32 matching lines @@
 abstract class StreamChannel<T> {
   /// The single-subscription stream that emits values from the other endpoint.
   Stream<T> get stream;
 
   /// The sink for sending values to the other endpoint.
   StreamSink<T> get sink;
 
   /// Creates a new [StreamChannel] that communicates over [stream] and [sink].
   ///
   /// Note that this stream/sink pair must provide the guarantees listed in the
-  /// [StreamChannel] documentation.
+  /// [StreamChannel] documentation. If they don't do so natively, [new
+  /// StreamChannel.withGuarantees] should be used instead.
   factory StreamChannel(Stream<T> stream, StreamSink<T> sink) =>
       new _StreamChannel<T>(stream, sink);
 
+  /// Creates a new [StreamChannel] that communicates over [stream] and [sink].
+  ///
+  /// Unlike [new StreamChannel], this enforces the guarantees listed in the
+  /// [StreamChannel] documentation. This makes it somewhat less efficient than
+  /// just wrapping a stream and a sink directly, so [new StreamChannel] should
+  /// be used when the guarantees are provided natively.
+  factory StreamChannel.withGuarantees(Stream<T> stream, StreamSink<T> sink) =>
+      new GuaranteeChannel(stream, sink);
+
   /// Connects [this] to [other], so that any values emitted by either are sent
   /// directly to the other.
   void pipe(StreamChannel<T> other);
 
   /// Transforms [this] using [transformer].
   ///
   /// This is identical to calling `transformer.bind(channel)`.
   StreamChannel transform(StreamChannelTransformer<T, dynamic> transformer);
 
   /// Transforms only the [stream] component of [this] using [transformer].
@@ skipping 39 matching lines @@
 
   StreamChannel<T> transformSink(StreamSinkTransformer<T, T> transformer) =>
       changeSink(transformer.bind);
 
   StreamChannel<T> changeStream(Stream<T> change(Stream<T> stream)) =>
       new StreamChannel(change(stream), sink);
 
   StreamChannel<T> changeSink(StreamSink<T> change(StreamSink<T> sink)) =>
       new StreamChannel(stream, change(sink));
 }