Add StreamChannel.withGuarantees and StreamChannelController.

Add StreamChannel.withGuarantees and StreamChannelController.

These APIs make it easier for users to create their own stream channels
that follow the StreamChannel guarantees.

R=tjblasi@google.com

Committed: https://github.com/dart-lang/stream_channel/commit/66a45ffe55f8e5e59232a7484db0befe30c98c13

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

https://codereview.chromium.org/1662773003/diff/1/lib/src/stream_channel_cont...
File lib/src/stream_channel_controller.dart (right):

https://codereview.chromium.org/1662773003/diff/1/lib/src/stream_channel_cont...
lib/src/stream_channel_controller.dart:17: /// StreamChannel
isolateChannel(ReceivePort receivePort, SendPort sendPort) {
I do actually plan to switch over the IsolateChannel implementation, but I need
to add the ability to control how errors are handled first.

https://codereview.chromium.org/1662773003/diff/1/lib/src/stream_channel_cont...
lib/src/stream_channel_controller.dart:35: StreamChannel<T> get local => _local;
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".

[nweiz, 2016-02-04 00:21:18]

nweiz@google.com changed reviewers:
+ tjblasi@google.com
- rnystrom@google.com

[nweiz, 2016-02-04 00:21:33]

Description was changed from

==========
Add StreamChannel.withGuarantees and StreamChannelController.

These APIs make it easier for users to create their own stream channels
that follow the StreamChannel guarantees.

R=rnystrom@google.com
==========

to

==========
Add StreamChannel.withGuarantees and StreamChannelController.

These APIs make it easier for users to create their own stream channels
that follow the StreamChannel guarantees.

R=tjblasi@google.com
==========

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

lgtm

https://codereview.chromium.org/1662773003/diff/1/lib/src/guarantee_channel.dart
File lib/src/guarantee_channel.dart (right):

https://codereview.chromium.org/1662773003/diff/1/lib/src/guarantee_channel.d...
lib/src/guarantee_channel.dart:11: /// A [StreamChannel] that enforces the
stream channel guarantees.
Consider adding a pointer to docs explaining what the stream channel guarantees
are, unless this would be obvious to anyone who cares to read this code.

https://codereview.chromium.org/1662773003/diff/1/lib/src/guarantee_channel.d...
lib/src/guarantee_channel.dart:18: _GuaranteeSink<T> _sink;
`_sink`, `_streamController`, and `_subscription` can all be `final`.

https://codereview.chromium.org/1662773003/diff/1/lib/src/stream_channel_cont...
File lib/src/stream_channel_controller.dart (right):

https://codereview.chromium.org/1662773003/diff/1/lib/src/stream_channel_cont...
lib/src/stream_channel_controller.dart:36: StreamChannel<T> _local;
Consider making these `final` & avoiding the need for getters.

[nweiz, 2016-02-04 01:33:42]

Code review changes

[nweiz, 2016-02-04 01:33:50]

Description was changed from

==========
Add StreamChannel.withGuarantees and StreamChannelController.

These APIs make it easier for users to create their own stream channels
that follow the StreamChannel guarantees.

R=tjblasi@google.com
==========

to

==========
Add StreamChannel.withGuarantees and StreamChannelController.

These APIs make it easier for users to create their own stream channels
that follow the StreamChannel guarantees.

R=tjblasi@google.com

Committed:
https://github.com/dart-lang/stream_channel/commit/66a45ffe55f8e5e59232a7484d...
==========

[nweiz, 2016-02-04 01:33:51]

Committed patchset #2 (id:20001) manually as
66a45ffe55f8e5e59232a7484db0befe30c98c13 (presubmit successful).

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

https://codereview.chromium.org/1662773003/diff/1/lib/src/guarantee_channel.dart
File lib/src/guarantee_channel.dart (right):

https://codereview.chromium.org/1662773003/diff/1/lib/src/guarantee_channel.d...
lib/src/guarantee_channel.dart:11: /// A [StreamChannel] that enforces the
stream channel guarantees.
On 2016/02/04 00:33:47, tjblasi wrote:
> Consider adding a pointer to docs explaining what the stream channel
guarantees
> are, unless this would be obvious to anyone who cares to read this code.

The guarantees are explained in the StreamChannel class documentation, which is
linked. It's not as obvious as I'd like, but I'm not sure how to do it better
without being weirdly repetitive.

https://codereview.chromium.org/1662773003/diff/1/lib/src/guarantee_channel.d...
lib/src/guarantee_channel.dart:18: _GuaranteeSink<T> _sink;
On 2016/02/04 00:33:47, tjblasi wrote:
> `_sink`, `_streamController`, and `_subscription` can all be `final`.

Unfortunately not :(. _sink's constructor needs to reference [this],
_streamController's needs to take a callback that refers to instance variables,
and _subscription is only assigned once the stream gets a listener.

https://codereview.chromium.org/1662773003/diff/1/lib/src/stream_channel_cont...
File lib/src/stream_channel_controller.dart (right):

https://codereview.chromium.org/1662773003/diff/1/lib/src/stream_channel_cont...
lib/src/stream_channel_controller.dart:36: StreamChannel<T> _local;
On 2016/02/04 00:33:47, tjblasi wrote:
> Consider making these `final` & avoiding the need for getters.

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.