be more explicit about when and how to register for listeners with isolates

sdk/lib/isolate/isolate.dart

 // Copyright (c) 2012, 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.
 
 /**
  * Concurrent programming using _isolates_:
  * independent workers that are similar to threads
  * but don't share memory,
  * communicating only via messages.
  */
@@ skipping 258 matching lines @@
    * thing before it terminates. It will run no further code after the message
    * has been sent.
    *
    * Adding the same port more than once will only cause it to receive one
    * message, using the last response value that was added.
    *
    * If the isolate is already dead, no message will be sent.
    * If `response` cannot be sent to the isolate, then the request is ignored.
    * It is recommended to only use simple values that can be sent to all
    * isolates, like `null`, booleans, numbers or strings.
+   * 
+   * Since isolates run concurrently, it's possible for it to exit before the
+   * exit listener is established. To avoid this, start the isolate paused,
+   * add the listener, then resume it.
    */
   /* TODO(lrn): Can we do better? Can the system recognize this message and
    * send a reply if the receiving isolate is dead?
    */
   external void addOnExitListener(SendPort responsePort, {Object response});
 
   /**
    * Stop listening on exit messages from the isolate.
    *
    * If a call has previously been made to [addOnExitListener] with the same
@@ skipping 68 matching lines @@
    *
    * The errors are sent back as two elements lists.
    * The first element is a `String` representation of the error, usually
    * created by calling `toString` on the error.
    * The second element is a `String` representation of an accompanying
    * stack trace, or `null` if no stack trace was provided.
    * To convert this back to a [StackTrace] object, use [StackTrace.fromString].
    *
    * Listening using the same port more than once does nothing. It will only
    * get each error once.
+   * 
+   * Since isolates run concurrently, it's possible for it to exit before the

[nweiz, 2015/06/12 19:18:55]

"exit" -> "emit an error"

[Lasse Reichstein Nielsen, 2015/06/12 19:38:16]

"exit or emit an error"?

It can do either or both.

[nweiz, 2015/06/12 21:05:43]

That's true, but if it exits before the listener is established the listener
just won't fire—the same as if it exits afterwards. I think the unintuitive
behavior is particular to emitting errors.

+   * error listener is established. To avoid this, start the isolate paused,
+   * add the listener, then resume it.
    */
   external void addErrorListener(SendPort port);
 
   /**
    * Stop listening for uncaught errors through [port].
    *
    * The `port` should be a port that is listening for errors through
    * [addErrorListener]. This call requests that the isolate stops sending
    * errors on the port.
    *
@@ skipping 213 matching lines @@
  * as the original error, but has no other features of the original error.
  */
 class RemoteError implements Error {
   final String _description;
   final StackTrace stackTrace;
   RemoteError(String description, String stackDescription)
       : _description = description,
         stackTrace = new StackTrace.fromString(stackDescription);
   String toString() => _description;
 }