Update isolate documentation.

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.
  *
  * See also:
  * [dart:isolate - Concurrency with Isolates](https://www.dartlang.org/docs/dart-up-and-running/contents/ch03.html#ch03-dartisolate---concurrency-with-isolates)
  * in the library tour.
  */
 library dart.isolate;
 
 import "dart:async";
 
 /**
  * Thrown when an isolate cannot be created.
  */
 class IsolateSpawnException implements Exception {
   // TODO(floitsch): clean up spawn exception.
   const IsolateSpawnException(String this._s);
   String toString() => "IsolateSpawnException: '$_s'";
   final String _s;
 }
 
+/**
+ * Thrown when an isolate message is invalid.
+ */
+class IsolateMessageException implements Exception {
+  final String _message;
+
+  // TODO(floitsch): give access to the message that couldn't be sent.

[Lasse Reichstein Nielsen, 2013/12/11 10:38:28]

Ah, agree :)

+  const IsolateMessageException(String this._message);
+
+  String toString() => "IsolateMessageException: '$_message'";
+}
+
 class Isolate {
 
   final SendPort _controlPort;
 
   Isolate._fromControlPort(SendPort controlPort)
       : this._controlPort = controlPort;
 
   /**
    * Creates and spawns an isolate that shares the same code as the current
    * isolate.
    *
    * The argument [entryPoint] specifies the entry point of the spawned
    * isolate. It must be a top-level function or a static method that
    * takes one argument - that is, one-parameter functions that can be
    * compile-time constant function values.
    * It is not allowed to pass the value of function expressions or an instance
    * method extracted from an object.
    *
    * The entry-point function is invoked with the initial [message].
    * Usually the initial [message] contains a [SendPort] so
    * that the spawner and spawnee can communicate with each other.
    *
    * Returns a future that will complete with an [Isolate] instance if the
    * spawning succeeded. It will complete with an error otherwise.
+   *
+   * All errors are reported asynchronously through the returned future.

[Lasse Reichstein Nielsen, 2013/12/11 10:38:28]

Not necessarily all errors.
Let's specify which arguments and conditions can cause an exception, and that
these exceptions are returned through the future.

[floitsch, 2013/12/11 12:14:16]

Yes.
This should be changed to list all the possible exceptions and to make sure that
they are dealt with correctly.

    */
   external static Future<Isolate> spawn(void entryPoint(message), var message);
 
   /**
    * Creates and spawns an isolate that runs the code from the library with
    * the specified URI.
    *
    * The isolate starts executing the top-level `main` function of the library
    * with the given URI.
    *
    * The target `main` must be a subtype of one of these three signatures:
    *
    * * `main()`
    * * `main(args)`
    * * `main(args, message)`
    *
    * When present, the parameter `args` is set to the provided [args] list.
    * When present, the parameter `message` is set to the initial [message].
    *
    * Returns a future that will complete with an [Isolate] instance if the
    * spawning succeeded. It will complete with an error otherwise.
+   *
+   * All errors are reported asynchronously through the returned future.

[Lasse Reichstein Nielsen, 2013/12/11 10:38:28]

Ditto.

    */
   external static Future<Isolate> spawnUri(
       Uri uri, List<String> args, var message);
 }
 
 /**
  * Sends messages to its [ReceivePort]s.
  *
  * [SendPort]s are created from [ReceivePort]s. Any message sent through
  * a [SendPort] is delivered to its corresponding [ReceivePort]. There might be
@@ skipping 148 matching lines @@
   const _IsolateUnhandledException(this.message, this.source, this.stackTrace);
 
   String toString() {
     return 'IsolateUnhandledException: exception while handling message: '
         '${message} \n  '
         '${source.toString().replaceAll("\n", "\n  ")}\n'
         'original stack trace:\n  '
         '${stackTrace.toString().replaceAll("\n","\n  ")}';
   }
 }