OLD | NEW |
1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file | 1 // Copyright (c) 2013, the Dart project authors. Please see the AUTHORS file |
2 // for details. All rights reserved. Use of this source code is governed by a | 2 // for details. All rights reserved. Use of this source code is governed by a |
3 // BSD-style license that can be found in the LICENSE file. | 3 // BSD-style license that can be found in the LICENSE file. |
4 | 4 |
5 part of dart.async; | 5 part of dart.async; |
6 | 6 |
7 // ------------------------------------------------------------------- | 7 // ------------------------------------------------------------------- |
8 // Core Stream types | 8 // Core Stream types |
9 // ------------------------------------------------------------------- | 9 // ------------------------------------------------------------------- |
10 | 10 |
(...skipping 1514 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1525 * In case of an error the subscription will automatically cancel (even | 1525 * In case of an error the subscription will automatically cancel (even |
1526 * when it was listening with `cancelOnError` set to `false`). | 1526 * when it was listening with `cancelOnError` set to `false`). |
1527 * | 1527 * |
1528 * In case of a `done` event the future completes with the given | 1528 * In case of a `done` event the future completes with the given |
1529 * [futureValue]. | 1529 * [futureValue]. |
1530 */ | 1530 */ |
1531 Future<E> asFuture<E>([E futureValue]); | 1531 Future<E> asFuture<E>([E futureValue]); |
1532 } | 1532 } |
1533 | 1533 |
1534 /** | 1534 /** |
1535 * An interface that abstracts creation or handling of [Stream] events. | 1535 * A [Sink] that supports adding errors. |
| 1536 * |
| 1537 * This makes it suitable for capturing the results of asynchronous |
| 1538 * computations, which can complete with a value or an error. |
| 1539 * |
| 1540 * The [EventSink] has been designed to handle asynchronous events from |
| 1541 * [Stream]s. See, for example, [Stream.eventTransformed] which uses |
| 1542 * `EventSink`s to transform events. |
1536 */ | 1543 */ |
1537 abstract class EventSink<T> implements Sink<T> { | 1544 abstract class EventSink<T> implements Sink<T> { |
1538 /** Send a data event to a stream. */ | 1545 /** |
| 1546 * Adds a data [event] to the sink. |
| 1547 * |
| 1548 * Must not be called on a closed sink. |
| 1549 */ |
1539 void add(T event); | 1550 void add(T event); |
1540 | 1551 |
1541 /** Send an async error to a stream. */ | 1552 /** |
1542 void addError(Object errorEvent, [StackTrace stackTrace]); | 1553 * Adds an [error] to the sink. |
| 1554 * |
| 1555 * Must not be called on a closed sink. |
| 1556 */ |
| 1557 void addError(Object error, [StackTrace stackTrace]); |
1543 | 1558 |
1544 /** Close the sink. No further events can be added after closing. */ | 1559 /** |
| 1560 * Closes the sink. |
| 1561 * |
| 1562 * Calling this method more than once is allowed, but does nothing. |
| 1563 * |
| 1564 * Neither [add] nor [addError] must be called after this method. |
| 1565 */ |
1545 void close(); | 1566 void close(); |
1546 } | 1567 } |
1547 | 1568 |
1548 /** [Stream] wrapper that only exposes the [Stream] interface. */ | 1569 /** [Stream] wrapper that only exposes the [Stream] interface. */ |
1549 class StreamView<T> extends Stream<T> { | 1570 class StreamView<T> extends Stream<T> { |
1550 final Stream<T> _stream; | 1571 final Stream<T> _stream; |
1551 | 1572 |
1552 const StreamView(Stream<T> stream) | 1573 const StreamView(Stream<T> stream) |
1553 : _stream = stream, | 1574 : _stream = stream, |
1554 super._internal(); | 1575 super._internal(); |
(...skipping 12 matching lines...) Expand all Loading... |
1567 } | 1588 } |
1568 } | 1589 } |
1569 | 1590 |
1570 /** | 1591 /** |
1571 * Abstract interface for a "sink" accepting multiple entire streams. | 1592 * Abstract interface for a "sink" accepting multiple entire streams. |
1572 * | 1593 * |
1573 * A consumer can accept a number of consecutive streams using [addStream], | 1594 * A consumer can accept a number of consecutive streams using [addStream], |
1574 * and when no further data need to be added, the [close] method tells the | 1595 * and when no further data need to be added, the [close] method tells the |
1575 * consumer to complete its work and shut down. | 1596 * consumer to complete its work and shut down. |
1576 * | 1597 * |
1577 * This class is not just a [Sink<Stream>] because it is also combined with | |
1578 * other [Sink] classes, like it's combined with [EventSink] in the | |
1579 * [StreamSink] class. | |
1580 * | |
1581 * The [Stream.pipe] accepts a `StreamConsumer` and will pass the stream | 1598 * The [Stream.pipe] accepts a `StreamConsumer` and will pass the stream |
1582 * to the consumer's [addStream] method. When that completes, it will | 1599 * to the consumer's [addStream] method. When that completes, it will |
1583 * call [close] and then complete its own returned future. | 1600 * call [close] and then complete its own returned future. |
1584 */ | 1601 */ |
1585 abstract class StreamConsumer<S> { | 1602 abstract class StreamConsumer<S> { |
1586 /** | 1603 /** |
1587 * Consumes the elements of [stream]. | 1604 * Consumes the elements of [stream]. |
1588 * | 1605 * |
1589 * Listens on [stream] and does something for each event. | 1606 * Listens on [stream] and does something for each event. |
1590 * | 1607 * |
(...skipping 21 matching lines...) Expand all Loading... |
1612 * Returns a future which is completed when the consumer has shut down. | 1629 * Returns a future which is completed when the consumer has shut down. |
1613 * If cleaning up can fail, the error may be reported in the returned future, | 1630 * If cleaning up can fail, the error may be reported in the returned future, |
1614 * otherwise it completes with `null`. | 1631 * otherwise it completes with `null`. |
1615 */ | 1632 */ |
1616 Future close(); | 1633 Future close(); |
1617 } | 1634 } |
1618 | 1635 |
1619 /** | 1636 /** |
1620 * A object that accepts stream events both synchronously and asynchronously. | 1637 * A object that accepts stream events both synchronously and asynchronously. |
1621 * | 1638 * |
1622 * A [StreamSink] unifies the asynchronous methods from [StreamConsumer] and | 1639 * A [StreamSink] combines the methods from [StreamConsumer] and [EventSink]. |
1623 * the synchronous methods from [EventSink]. | |
1624 * | 1640 * |
1625 * The [EventSink] methods can't be used while the [addStream] is called. | 1641 * The [EventSink] methods can't be used while the [addStream] is called. |
1626 * As soon as the [addStream]'s [Future] completes with a value, the | 1642 * As soon as the [addStream]'s [Future] completes with a value, the |
1627 * [EventSink] methods can be used again. | 1643 * [EventSink] methods can be used again. |
1628 * | 1644 * |
1629 * If [addStream] is called after any of the [EventSink] methods, it'll | 1645 * If [addStream] is called after any of the [EventSink] methods, it'll |
1630 * be delayed until the underlying system has consumed the data added by the | 1646 * be delayed until the underlying system has consumed the data added by the |
1631 * [EventSink] methods. | 1647 * [EventSink] methods. |
1632 * | 1648 * |
1633 * When [EventSink] methods are used, the [done] [Future] can be used to | 1649 * When [EventSink] methods are used, the [done] [Future] can be used to |
(...skipping 282 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1916 /// Must only be used instead of listening to the [values] stream. | 1932 /// Must only be used instead of listening to the [values] stream. |
1917 /// If the stream has been listened to, this call fails. | 1933 /// If the stream has been listened to, this call fails. |
1918 /// After calling this method, listening on the [values] stream fails. | 1934 /// After calling this method, listening on the [values] stream fails. |
1919 Future cancel() { | 1935 Future cancel() { |
1920 // If values has been listened to, | 1936 // If values has been listened to, |
1921 // this throws a StateError saying that stream has already been listened to, | 1937 // this throws a StateError saying that stream has already been listened to, |
1922 // which is a correct error message for this call too. | 1938 // which is a correct error message for this call too. |
1923 return values.listen(null).cancel(); | 1939 return values.listen(null).cancel(); |
1924 } | 1940 } |
1925 } | 1941 } |
OLD | NEW |