Add StreamChannel.withGuarantees and StreamChannelController.

lib/src/stream_channel_controller.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 '../stream_channel.dart';
+
+/// A controller for exposing a new [StreamChannel].
+///
+/// This exposes two connected [StreamChannel]s, [local] and [foreign]. The
+/// user's code should use [local] to emit and receive events. Then [foreign]
+/// can be returned for others to use. For example, here's a simplified version
+/// of the implementation of [new IsolateChannel]:
+///
+/// ```dart
+/// StreamChannel isolateChannel(ReceivePort receivePort, SendPort sendPort) {

[nweiz, 2016/02/04 00:03:07]

I do actually plan to switch over the IsolateChannel implementation, but I need
to add the ability to control how errors are handled first.

+///   var controller = new StreamChannelController();
+///
+///   // Pipe all events from the receive port into the local sink...
+///   receivePort.pipe(controller.local.sink);
+///
+///   // ...and all events from the local stream into the send port.
+///   controller.local.listen(sendPort.add, onDone: receivePort.close);
+///
+///   // Then return the foreign controller for your users to use.
+///   return controller.foreign;
+/// }
+/// ```
+class StreamChannelController<T> {
+  /// The local channel.
+  ///
+  /// This channel should be used directly by the creator of this
+  /// [StreamChannelController] to send and receive events.
+  StreamChannel<T> get local => _local;

[nweiz, 2016/02/04 00:03:07]

I decided to go with local/foreign here, in part because I want to add a
parameter that controls whether errors can be added to the foreign sink.
"allowThereErrors" reads a lot worse than "allowForeignErrors".

+  StreamChannel<T> _local;

[tjblasi, 2016/02/04 00:33:47]

Consider making these `final` & avoiding the need for getters.

[nweiz, 2016/02/04 01:35:04]

I could do it here, but both channels' constructors refer to the same two
controllers, so I'd have to add an extra dummy constructor just to make those
controllers accessible to initializers. I think this way is less gross.

+
+  /// The foreign channel.
+  ///
+  /// This channel should be returned to external users so they can communicate
+  /// with [local].
+  StreamChannel<T> get foreign => _foreign;
+  StreamChannel<T> _foreign;
+
+  /// Creates a [StreamChannelController].
+  ///
+  /// If [sync] is true, events added to either channel's sink are synchronously
+  /// dispatched to the other channel's stream. This should only be done if the
+  /// source of those events is already asynchronous.
+  StreamChannelController({bool sync: false}) {
+    var _localToForeignController = new StreamController<T>(sync: sync);
+    var _foreignToLocalController = new StreamController<T>(sync: sync);
+    _local = new StreamChannel<T>.withGuarantees(
+        _foreignToLocalController.stream, _localToForeignController.sink);
+    _foreign = new StreamChannel<T>.withGuarantees(
+        _localToForeignController.stream, _foreignToLocalController.sink);
+  }
+}