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 1444 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1455 * In case of an error the subscription will automatically cancel (even | 1455 * In case of an error the subscription will automatically cancel (even |
1456 * when it was listening with `cancelOnError` set to `false`). | 1456 * when it was listening with `cancelOnError` set to `false`). |
1457 * | 1457 * |
1458 * In case of a `done` event the future completes with the given | 1458 * In case of a `done` event the future completes with the given |
1459 * [futureValue]. | 1459 * [futureValue]. |
1460 */ | 1460 */ |
1461 Future<E> asFuture<E>([E futureValue]); | 1461 Future<E> asFuture<E>([E futureValue]); |
1462 } | 1462 } |
1463 | 1463 |
1464 /** | 1464 /** |
1465 * A [Sink] that supports adding errors. | 1465 * An interface that abstracts creation or handling of [Stream] events. |
1466 * | |
1467 * This makes it suitable for capturing the results of asynchronous | |
1468 * computations, which can complete with a value or an error. | |
1469 * | |
1470 * The [EventSink] has been designed to handle asynchronous events from | |
1471 * [Stream]s. See, for example, [Stream.eventTransformed] which uses | |
1472 * `EventSink`s to transform events. | |
1473 */ | 1466 */ |
1474 abstract class EventSink<T> implements Sink<T> { | 1467 abstract class EventSink<T> implements Sink<T> { |
1475 /** | 1468 /** Send a data event to a stream. */ |
1476 * Adds a data [event] to the sink. | |
1477 * | |
1478 * Must not be called on a closed sink. | |
1479 */ | |
1480 void add(T event); | 1469 void add(T event); |
1481 | 1470 |
1482 /** | 1471 /** Send an async error to a stream. */ |
1483 * Adds an [error] to the sink. | 1472 void addError(Object errorEvent, [StackTrace stackTrace]); |
1484 * | |
1485 * Must not be called on a closed sink. | |
1486 */ | |
1487 void addError(Object error, [StackTrace stackTrace]); | |
1488 | 1473 |
1489 /** | 1474 /** Close the sink. No further events can be added after closing. */ |
1490 * Closes the sink. | |
1491 * | |
1492 * Calling this method more than once is allowed, but does nothing. | |
1493 * | |
1494 * Neither [add] nor [addError] must be called after this method. | |
1495 */ | |
1496 void close(); | 1475 void close(); |
1497 } | 1476 } |
1498 | 1477 |
1499 /** [Stream] wrapper that only exposes the [Stream] interface. */ | 1478 /** [Stream] wrapper that only exposes the [Stream] interface. */ |
1500 class StreamView<T> extends Stream<T> { | 1479 class StreamView<T> extends Stream<T> { |
1501 final Stream<T> _stream; | 1480 final Stream<T> _stream; |
1502 | 1481 |
1503 const StreamView(Stream<T> stream) | 1482 const StreamView(Stream<T> stream) |
1504 : _stream = stream, | 1483 : _stream = stream, |
1505 super._internal(); | 1484 super._internal(); |
(...skipping 12 matching lines...) Expand all Loading... |
1518 } | 1497 } |
1519 } | 1498 } |
1520 | 1499 |
1521 /** | 1500 /** |
1522 * Abstract interface for a "sink" accepting multiple entire streams. | 1501 * Abstract interface for a "sink" accepting multiple entire streams. |
1523 * | 1502 * |
1524 * A consumer can accept a number of consecutive streams using [addStream], | 1503 * A consumer can accept a number of consecutive streams using [addStream], |
1525 * and when no further data need to be added, the [close] method tells the | 1504 * and when no further data need to be added, the [close] method tells the |
1526 * consumer to complete its work and shut down. | 1505 * consumer to complete its work and shut down. |
1527 * | 1506 * |
| 1507 * This class is not just a [Sink<Stream>] because it is also combined with |
| 1508 * other [Sink] classes, like it's combined with [EventSink] in the |
| 1509 * [StreamSink] class. |
| 1510 * |
1528 * The [Stream.pipe] accepts a `StreamConsumer` and will pass the stream | 1511 * The [Stream.pipe] accepts a `StreamConsumer` and will pass the stream |
1529 * to the consumer's [addStream] method. When that completes, it will | 1512 * to the consumer's [addStream] method. When that completes, it will |
1530 * call [close] and then complete its own returned future. | 1513 * call [close] and then complete its own returned future. |
1531 */ | 1514 */ |
1532 abstract class StreamConsumer<S> { | 1515 abstract class StreamConsumer<S> { |
1533 /** | 1516 /** |
1534 * Consumes the elements of [stream]. | 1517 * Consumes the elements of [stream]. |
1535 * | 1518 * |
1536 * Listens on [stream] and does something for each event. | 1519 * Listens on [stream] and does something for each event. |
1537 * | 1520 * |
(...skipping 21 matching lines...) Expand all Loading... |
1559 * Returns a future which is completed when the consumer has shut down. | 1542 * Returns a future which is completed when the consumer has shut down. |
1560 * If cleaning up can fail, the error may be reported in the returned future, | 1543 * If cleaning up can fail, the error may be reported in the returned future, |
1561 * otherwise it completes with `null`. | 1544 * otherwise it completes with `null`. |
1562 */ | 1545 */ |
1563 Future close(); | 1546 Future close(); |
1564 } | 1547 } |
1565 | 1548 |
1566 /** | 1549 /** |
1567 * A object that accepts stream events both synchronously and asynchronously. | 1550 * A object that accepts stream events both synchronously and asynchronously. |
1568 * | 1551 * |
1569 * A [StreamSink] combines the methods from [StreamConsumer] and [EventSink]. | 1552 * A [StreamSink] unifies the asynchronous methods from [StreamConsumer] and |
| 1553 * the synchronous methods from [EventSink]. |
1570 * | 1554 * |
1571 * The [EventSink] methods can't be used while the [addStream] is called. | 1555 * The [EventSink] methods can't be used while the [addStream] is called. |
1572 * As soon as the [addStream]'s [Future] completes with a value, the | 1556 * As soon as the [addStream]'s [Future] completes with a value, the |
1573 * [EventSink] methods can be used again. | 1557 * [EventSink] methods can be used again. |
1574 * | 1558 * |
1575 * If [addStream] is called after any of the [EventSink] methods, it'll | 1559 * If [addStream] is called after any of the [EventSink] methods, it'll |
1576 * be delayed until the underlying system has consumed the data added by the | 1560 * be delayed until the underlying system has consumed the data added by the |
1577 * [EventSink] methods. | 1561 * [EventSink] methods. |
1578 * | 1562 * |
1579 * When [EventSink] methods are used, the [done] [Future] can be used to | 1563 * When [EventSink] methods are used, the [done] [Future] can be used to |
(...skipping 225 matching lines...) Expand 10 before | Expand all | Expand 10 after Loading... |
1805 } | 1789 } |
1806 | 1790 |
1807 void addError(error, [StackTrace stackTrace]) { | 1791 void addError(error, [StackTrace stackTrace]) { |
1808 _sink.addError(error, stackTrace); | 1792 _sink.addError(error, stackTrace); |
1809 } | 1793 } |
1810 | 1794 |
1811 void close() { | 1795 void close() { |
1812 _sink.close(); | 1796 _sink.close(); |
1813 } | 1797 } |
1814 } | 1798 } |
OLD | NEW |