languages/dart-sdk
languages/dart-sdk
1
0
Fork 0
mirror of https://github.com/dart-lang/sdk synced 2024-10-03 06:21:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improve stream-controller documentation.

Browse source 
R=lrn@google.com

Review URL: https://codereview.chromium.org/1635643002 .
This commit is contained in:
Florian Loitsch 2016-01-26 11:35:44 +01:00
parent bbde44f7cc
commit 42f063e0a0
1 changed files with 18 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

20
sdk/lib/async/stream_controller.dart
View file

@ -68,9 +68,16 @@ abstract class StreamController<T> implements StreamSink<T> {
* If [sync] is true, the returned stream controller is a
* [SynchronousStreamController], and must be used with the care
* and attention necessary to not break the [Stream] contract.
* See [Completer.sync] for some explanations on when a synchronous
* dispatching can be used.
* If in doubt, keep the controller non-sync.
*
* The controller will buffer all incoming events until the subscriber is
* registered.
* A Stream should be inert until a subscriber starts listening on it (using
* the [onListen] callback to start producing events). Streams should not
* leak resources (like websockets) when no user ever listens on the stream.
*
* The controller buffers all incoming events until a subscriber is
* registered, but this feature should only be used in rare circumstances.
*
* The [onPause] function is called when the stream becomes
* paused. [onResume] is called when the stream resumed.
@ -100,6 +107,12 @@ abstract class StreamController<T> implements StreamSink<T> {
* The [Stream] returned by [stream] is a broadcast stream.
* It can be listened to more than once.
*
* A Stream should be inert until a subscriber starts listening on it (using
* the [onListen] callback to start producing events). Streams should not
* leak resources (like websockets) when no user ever listens on the stream.
*
* Broadcast streams do not buffer events when there is no listener.
*
* The controller distributes any events to all currently subscribed
* listeners at the time when [add], [addError] or [close] is called.
* It is not allowed to call `add`, `addError`, or `close` before a previous
@ -116,6 +129,9 @@ abstract class StreamController<T> implements StreamSink<T> {
* The returned stream controller is a [SynchronousStreamController],
* and must be used with the care and attention necessary to not break
* the [Stream] contract.
* See [Completer.sync] for some explanations on when a synchronous
* dispatching can be used.
* If in doubt, keep the controller non-sync.
*
* If [sync] is false, the event will always be fired at a later time,
* after the code adding the event has completed.