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