Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(10)

Side by Side Diff: sdk/lib/async/stream.dart

Issue 2822173002: Warn when adding something to a closed sink and improve documentation (Closed)
Patch Set: Only warn for now. Created 3 years, 7 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch
OLDNEW
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
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
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
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
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 }
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698