Warn when adding something to a closed sink and improve documentation

sdk/lib/io/io_sink.dart

 // Copyright (c) 2013, the Dart project authors.  Please see the AUTHORS file
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 
 part of dart.io;
 
 /**
  * A combined byte and text output.
  *
  * An [IOSink] combines a [StreamSink] of bytes with a [StringSink],
  * and allows easy output of both bytes and text.
  *
  * Writing text ([write]) and adding bytes ([add]) may be interleaved freely.
  *
  * While a stream is being added using [addStream], any further attempts
  * to add or write to the [IOSink] will fail until the [addStream] completes.
  *
- * If data is added to the [IOSink] after the sink is closed, the data will be
- * ignored. Use the [done] future to be notified when the [IOSink] is closed.
+ * It is an error to add data to the [IOSink] after the sink is closed.
  */
 abstract class IOSink implements StreamSink<List<int>>, StringSink {
   /**
    * Create an [IOSink] that outputs to a [target] [StreamConsumer] of bytes.
    *
    * Text written to [StreamSink] methods is encoded to bytes using [encoding]
    * before being output on [target].
    */
   factory IOSink(StreamConsumer<List<int>> target, {Encoding encoding: UTF8}) =>
       new _IOSinkImpl(target, encoding);
@@ skipping 111 matching lines @@
   final Completer _doneCompleter = new Completer();
   StreamController<T> _controllerInstance;
   Completer _controllerCompleter;
   bool _isClosed = false;
   bool _isBound = false;
   bool _hasError = false;
 
   _StreamSinkImpl(this._target);
 
   void add(T data) {
-    if (_isClosed) return;
+    if (_isClosed) {
+      // TODO(29554): throw a StateError, and don't just report the problem.
+      stderr.writeln("StreamSink is closed and adding to it is an error.");
+      stderr.writeln("  See http://dartbug.com/29554.");
+      stderr.writeln(StackTrace.current);

[Lasse Reichstein Nielsen, 2017/05/08 11:31:08]

I don't know enough about stderr to be sure this doesn't have a side-effect on
other uses of stderr. I'm guessing it doesn't, but let's ask someone who'd know.

[floitsch, 2017/05/08 12:22:39]

It completely interferes with the user's stderr.
However, it's still less likely to break them, than if we threw.

+      return;
+    }
     _controller.add(data);
   }
 
   void addError(error, [StackTrace stackTrace]) {
+    if (_isClosed) {
+      // TODO(29554): throw a StateError, and don't just report the problem.
+      stderr.writeln("StreamSink is closed and adding to it is an error.");
+      stderr.writeln("  See http://dartbug.com/29554.");
+      stderr.writeln(StackTrace.current);
+      return;
+    }
     _controller.addError(error, stackTrace);
   }
 
   Future addStream(Stream<T> stream) {
     if (_isBound) {
       throw new StateError("StreamSink is already bound to a stream");
     }
     _isBound = true;
     if (_hasError) return done;
     // Wait for any sync operations to complete.
@@ skipping 134 matching lines @@
 
   void writeln([Object object = ""]) {
     write(object);
     write("\n");
   }
 
   void writeCharCode(int charCode) {
     write(new String.fromCharCode(charCode));
   }
 }