Add Isolate.onExit.

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 18 matching lines @@
 }
 
 class Isolate {
   /**
    * Control port used to send control messages to the isolate.
    *
    * This class provides helper functions that sends control messages
    * to the control port.
    */
   final SendPort controlPort;
+  /**
+   * Capability granting the ability to pause the isolate.
+   */
   final Capability pauseCapability;
 
   Isolate._fromControlPort(this.controlPort, [this.pauseCapability]);
 
   /**
    * 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
@@ skipping 28 matching lines @@
    * 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.
    */
   external static Future<Isolate> spawnUri(
       Uri uri, List<String> args, var message, { bool paused: false });
 
 
   /**

[Søren Gjesse, 2014/03/04 10:16:25]

I think we should move the WARNING up as the first line in the comment, and
extend it to also say that this is still experimental.

[Lasse Reichstein Nielsen, 2014/03/06 09:26:12]

Done.

    * 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 sent to the isolate from
-   * the current isolate, but no other guarantees are provided.
+   * 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,
+   * messages have been reached.
    *
    * If [resumeCapability] is provided, it is used to identity the pause,
    * and must be used again to end the pause using [resume].
-   * Otherwise a new capability is created and returned.
+   * Otherwise a new resume capability is created and returned.
    *
-   * If an isolate is paused more than once using the same capabilty,
+   * If an isolate is paused more than once using the same capability,
    * only one resume with that capability is needed to end the pause.
    *
    * If an isolate is paused using more than one capability,
    * they must all be individully ended before the isolate resumes.
    *
    * Returns the capability that must be used to resume end the pause.
    *
-   * WARNING: This method is not handled on any platform yet.
+   * WARNING: This method is not handled on every platform yet.
    */
   Capability pause([Capability resumeCapability]) {
     if (resumeCapability == null) resumeCapability = new Capability();
     var message = new List(3)
         ..[0] = "pause"
         ..[1] = pauseCapability
         ..[2] = resumeCapability;
     controlPort.send(message);
     return resumeCapability;
   }
 
   /**
    * Resumes a paused isolate.
    *
    * Sends a message to an isolate requesting that it ends a pause
    * that was requested using the [resumeCapability].
    *
+   * When all active pause requests have been cancelled, the isolate
+   * will continue handling normal messages.
+   *
    * The capability must be one returned by a call to [pause] on this
    * isolate, otherwise the resume call does nothing.
    *
-   * WARNING: This method is not handled on any platform yet.
+   * WARNING: This method is not handled on every platform yet.
    */
   void resume(Capability resumeCapability) {
     var message = new List(2)
         ..[0] = "resume"
         ..[1] = resumeCapability;
     controlPort.send(message);
   }
+
+  /**
+   * Asks the isolate to send a message on [responsePort] when it terminates.
+   *
+   * The isolate will send a `null` message on [responsePort] as the last
+   * thing before it terminates. It will run no further code after the message
+   * has been sent.
+   *
+   * If the isolate is already dead, no message will be sent.
+   * TODO(lrn): Can we do better? Can the system recognize this message and
+   * send a reply if the receiving isolate is dead?

[Søren Gjesse, 2014/03/04 10:16:25]

Add the warning as for pause/resume.

[Lasse Reichstein Nielsen, 2014/03/06 09:26:12]

Done.

+   */
+  void addOnExitListener(SendPort responsePort) {

[Søren Gjesse, 2014/03/04 10:16:25]

No capability needed to "spy" on when an isolate exits?

[Lasse Reichstein Nielsen, 2014/03/06 09:26:12]

No. It's considered harmless. You don't leak any information from the isolate. 
If you have the isolate object, you can send control messages to it, including
this and the "ping" operation. To avoid that, don't give access to the isolate
(in this case, you can treat the control port itself as the capability needed
for these operations).

+    // TODO(lrn): Can we have an internal method that checks if the receiving
+    // isolate of a SendPort is still alive?
+    var message = new List(2)
+        ..[0] = "add-ondone"
+        ..[1] = responsePort;
+    controlPort.send(message);
+  }
+
+  /**
+   * 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.
+   */
+  void removeOnExitListener(SendPort responsePort) {
+    var message = new List(2)
+        ..[0] = "remove-ondone"
+        ..[1] = responsePort;
+    controlPort.send(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
  * many [SendPort]s for the same [ReceivePort].
  *
  * [SendPort]s can be transmitted to other isolates.
@@ skipping 145 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  ")}';
   }
 }