Add errorsAreFatal, onExit and onError parameters to the spawn functions.

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 126 matching lines @@
    * 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.
    *
    * If the [paused] parameter is set to `true`,
    * the isolate will start up in a paused state,
    * as if by an initial call of `isolate.pause(isolate.pauseCapability)`.
-   * This allows setting up error or exit listeners on the isolate
-   * before it starts running.
    * To resume the isolate, call `isolate.resume(isolate.pauseCapability)`.
    *
+   * If the [errorAreFatal], [onExit] and/or [onError] parameters are provided,
+   * the isolate will act as if, respectively, [setErrorsFatal],
+   * [addOnExitListener] and [addErrorListener] were called with the
+   * corresponding parameter and was processed before the isolate starts
+   * running.
+   *
+   * You can also call the [setErrorsFatal], [addOnExitListener] and
+   * [addErrorListener] methods on the returned isolate, but unless the
+   * isolate was started as [paused], it may already have terminated
+   * before those methods can complete.
+   *
+   * WARNING: The [errorsAreFatal], [onExit] and [onError] parameters are not
+   * implemented yet.
+   *
    * Returns a future that will complete with an [Isolate] instance if the
    * spawning succeeded. It will complete with an error otherwise.
    */
   external static Future<Isolate> spawn(void entryPoint(message), var message,
-                                        { bool paused: false });
+                                        { bool paused: false,
+                                          bool errorsAreFatal,
+                                          SendPort onExit,
+                                          SendPort onError });
 
   /**
    * 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:
+   * The target `main` must be callable with zero, one or two arguments.
+   * Examples:
    *
    * * `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].
    *
    * If the [paused] parameter is set to `true`,
    * the isolate will start up in a paused state,
    * as if by an initial call of `isolate.pause(isolate.pauseCapability)`.
-   * This allows setting up error or exit listeners on the isolate
-   * before it starts running.
    * To resume the isolate, call `isolate.resume(isolate.pauseCapability)`.
    *
+   * If the [errorAreFatal], [onExit] and/or [onError] parameters are provided,
+   * the isolate will act as if, respectively, [setErrorsFatal],
+   * [addOnExitListener] and [addErrorListener] were called with the
+   * corresponding parameter and was processed before the isolate starts
+   * running.
+   *
+   * You can also call the [setErrorsFatal], [addOnExitListener] and
+   * [addErrorListener] methods on the returned isolate, but unless the
+   * isolate was started as [paused], it may already have terminated
+   * before those methods can complete.
+   *
+   * WARNING: The [errorsAreFatal], [onExit] and [onError] parameters are not
+   * implemented yet.
+   *
    * If the [checked] parameter is set to `true` or `false`,
    * the new isolate will run code in checked mode,
    * respectively in production mode, if possible.
    * If the parameter is omitted, the new isolate will inherit the
    * value from the current isolate.
    *
    * It may not always be possible to honor the `checked` parameter.
    * If the isolate code was pre-compiled, it may not be possible to change
    * the checked mode setting dynamically.
    * In that case, the `checked` parameter is ignored.
@@ skipping 17 matching lines @@
    *
    * Returns a future that will complete with an [Isolate] instance if the
    * spawning succeeded. It will complete with an error otherwise.
    */
   external static Future<Isolate> spawnUri(
       Uri uri,
       List<String> args,
       var message,
       {bool paused: false,
        bool checked,
-       Uri packageRoot});
+       Uri packageRoot,
+       bool errorsAreFatal,
+       SendPort onExit,
+       SendPort onError});
 
   /**
    * Requests the isolate to pause.
    *
    * The isolate should stop handling events by pausing its event queue.
    * The request will eventually make the isolate stop doing anything.
    * It will be handled before any other messages that are later sent to the
    * isolate from the current isolate, but no other guarantees are provided.
    *
    * The event loop may be paused before previously sent, but not yet exeuted,
@@ skipping 41 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.
+   * exit listener is established, and in that case no response will be
+   * sent on [responsePort].
+   * To avoid this, either use the corresponding parameter to the spawn
+   * function, or start the isolate paused, add the listener and
+   * then resume the isolate.
    */
   /* 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
    * send-port, this will unregister the port, and it will no longer receive
    * a message when the isolate terminates.
    * A response may still be sent until this operation is fully processed by
    * the isolate.
    */
   external void removeOnExitListener(SendPort responsePort);
 
   /**
    * Set whether uncaught errors will terminate the isolate.
    *
    * If errors are fatal, any uncaught error will terminate the isolate
    * event loop and shut down the isolate.
    *
    * This call requires the [terminateCapability] for the isolate.
    * If the capability is not correct, no change is made.
+   *
+   * Since isolates run concurrently, it's possible for it to exit due to an
+   * error before errors are set non-fatal.
+   * To avoid this, either use the corresponding parameter to the spawn
+   * function, or start the isolate paused, set errors non-fatal and
+   * then resume the isolate.
    */
   external void setErrorsFatal(bool errorsAreFatal);
 
   /**
    * Requests the isolate to shut down.
    *
    * The isolate is requested to terminate itself.
    * The [priority] argument specifies when this must happen.
    *
    * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT].
@@ skipping 43 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
    * error listener is established. To avoid this, start the isolate paused,
-   * add the listener, then resume it.
+   * add the listener and then resume the isolate.
    */
   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;
 }