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 * A [Sink] that supports adding errors. | 1535 * An interface that abstracts creation or handling of [Stream] events. |
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. | |
1543 */ | 1536 */ |
1544 abstract class EventSink<T> implements Sink<T> { | 1537 abstract class EventSink<T> implements Sink<T> { |
1545 /** | 1538 /** Send a data event to a stream. */ |
1546 * Adds a data [event] to the sink. | |
1547 * | |
1548 * Must not be called on a closed sink. | |
1549 */ | |
1550 void add(T event); | 1539 void add(T event); |
1551 | 1540 |
1552 /** | 1541 /** Send an async error to a stream. */ |
1553 * Adds an [error] to the sink. | 1542 void addError(Object errorEvent, [StackTrace stackTrace]); |
1554 * | |
1555 * Must not be called on a closed sink. | |
1556 */ | |
1557 void addError(Object error, [StackTrace stackTrace]); | |
1558 | 1543 |
1559 /** | 1544 /** Close the sink. No further events can be added after closing. */ |
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 */ | |
1566 void close(); | 1545 void close(); |
1567 } | 1546 } |
1568 | 1547 |
1569 /** [Stream] wrapper that only exposes the [Stream] interface. */ | 1548 /** [Stream] wrapper that only exposes the [Stream] interface. */ |
1570 class StreamView<T> extends Stream<T> { | 1549 class StreamView<T> extends Stream<T> { |
1571 final Stream<T> _stream; | 1550 final Stream<T> _stream; |
1572 | 1551 |
1573 const StreamView(Stream<T> stream) | 1552 const StreamView(Stream<T> stream) |
1574 : _stream = stream, | 1553 : _stream = stream, |
1575 super._internal(); | 1554 super._internal(); |
(...skipping 12 matching lines...) Expand all Loading... |
1588 } | 1567 } |
1589 } | 1568 } |
1590 | 1569 |
1591 /** | 1570 /** |
1592 * Abstract interface for a "sink" accepting multiple entire streams. | 1571 * Abstract interface for a "sink" accepting multiple entire streams. |
1593 * | 1572 * |
1594 * A consumer can accept a number of consecutive streams using [addStream], | 1573 * A consumer can accept a number of consecutive streams using [addStream], |
1595 * and when no further data need to be added, the [close] method tells the | 1574 * and when no further data need to be added, the [close] method tells the |
1596 * consumer to complete its work and shut down. | 1575 * consumer to complete its work and shut down. |
1597 * | 1576 * |
| 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 * |
1598 * The [Stream.pipe] accepts a `StreamConsumer` and will pass the stream | 1581 * The [Stream.pipe] accepts a `StreamConsumer` and will pass the stream |
1599 * to the consumer's [addStream] method. When that completes, it will | 1582 * to the consumer's [addStream] method. When that completes, it will |
1600 * call [close] and then complete its own returned future. | 1583 * call [close] and then complete its own returned future. |
1601 */ | 1584 */ |
1602 abstract class StreamConsumer<S> { | 1585 abstract class StreamConsumer<S> { |
1603 /** | 1586 /** |
1604 * Consumes the elements of [stream]. | 1587 * Consumes the elements of [stream]. |
1605 * | 1588 * |
1606 * Listens on [stream] and does something for each event. | 1589 * Listens on [stream] and does something for each event. |
1607 * | 1590 * |
(...skipping 21 matching lines...) Expand all Loading... |
1629 * Returns a future which is completed when the consumer has shut down. | 1612 * Returns a future which is completed when the consumer has shut down. |
1630 * If cleaning up can fail, the error may be reported in the returned future, | 1613 * If cleaning up can fail, the error may be reported in the returned future, |
1631 * otherwise it completes with `null`. | 1614 * otherwise it completes with `null`. |
1632 */ | 1615 */ |
1633 Future close(); | 1616 Future close(); |
1634 } | 1617 } |
1635 | 1618 |
1636 /** | 1619 /** |
1637 * A object that accepts stream events both synchronously and asynchronously. | 1620 * A object that accepts stream events both synchronously and asynchronously. |
1638 * | 1621 * |
1639 * A [StreamSink] combines the methods from [StreamConsumer] and [EventSink]. | 1622 * A [StreamSink] unifies the asynchronous methods from [StreamConsumer] and |
| 1623 * the synchronous methods from [EventSink]. |
1640 * | 1624 * |
1641 * The [EventSink] methods can't be used while the [addStream] is called. | 1625 * The [EventSink] methods can't be used while the [addStream] is called. |
1642 * As soon as the [addStream]'s [Future] completes with a value, the | 1626 * As soon as the [addStream]'s [Future] completes with a value, the |
1643 * [EventSink] methods can be used again. | 1627 * [EventSink] methods can be used again. |
1644 * | 1628 * |
1645 * If [addStream] is called after any of the [EventSink] methods, it'll | 1629 * If [addStream] is called after any of the [EventSink] methods, it'll |
1646 * be delayed until the underlying system has consumed the data added by the | 1630 * be delayed until the underlying system has consumed the data added by the |
1647 * [EventSink] methods. | 1631 * [EventSink] methods. |
1648 * | 1632 * |
1649 * When [EventSink] methods are used, the [done] [Future] can be used to | 1633 * 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... |
1932 /// Must only be used instead of listening to the [values] stream. | 1916 /// Must only be used instead of listening to the [values] stream. |
1933 /// If the stream has been listened to, this call fails. | 1917 /// If the stream has been listened to, this call fails. |
1934 /// After calling this method, listening on the [values] stream fails. | 1918 /// After calling this method, listening on the [values] stream fails. |
1935 Future cancel() { | 1919 Future cancel() { |
1936 // If values has been listened to, | 1920 // If values has been listened to, |
1937 // this throws a StateError saying that stream has already been listened to, | 1921 // this throws a StateError saying that stream has already been listened to, |
1938 // which is a correct error message for this call too. | 1922 // which is a correct error message for this call too. |
1939 return values.listen(null).cancel(); | 1923 return values.listen(null).cancel(); |
1940 } | 1924 } |
1941 } | 1925 } |
OLD | NEW |