Add Isolate ping functionality.

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 11 matching lines @@
  * 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;
 }
 
 class Isolate {
+  /** Argument to `ping`: Ask for immediate response. */
+  static const int PING_ALIVE = 0;
+  /** Argument to `ping`: Ask for response after control events. */
+  static const int PING_CONTROL = 1;
+  /** Argument to `ping`: Ask for response after normal events. */
+  static const int PING_EVENT = 2;
+
   /**
    * 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;
   final Capability pauseCapability;
 
   Isolate._fromControlPort(this.controlPort, [this.pauseCapability]);
@@ skipping 55 matching lines @@
    * Otherwise a new capability is created and returned.
    *
    * If an isolate is paused more than once using the same capabilty,
    * 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 all platforms 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].
    *
    * 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 all platforms yet.
    */
   void resume(Capability resumeCapability) {
     var message = new List(2)
         ..[0] = "resume"
         ..[1] = resumeCapability;
     controlPort.send(message);
   }
+
+  /**
+   * Request that the isolate send a response on the [responsePort].
+   *
+   * If the isolate is alive, it will eventually send a `null` response on
+   * the response port.
+   *
+   * The [pingType] must be one of [PING_ALIVE], [PING_CONTROL] or [PING_EVENT].
+   * The response is sent at different times depending on the ping type:
+   *
+   * * `PING_ALIVE`: The the isolate responds as soon as possible.

[Anders Johnsen, 2014/03/04 14:06:20]

The the

+   *     The response should happen no sooner than if sent with `PING_CONTROL`.
+   *     It may be sent earlier of the system has a way to do so.

[Anders Johnsen, 2014/03/04 14:06:20]

of -> if

+   * * `PING_CONTROL`: The response it not sent until all previously sent
+   *     control messages from the current isolate to the receiving isolate
+   *     have been processed. This can be used to wait for
+   *     previously sent control messages.
+   * * `PING_EVENT`: The response is not sent until all prevously sent
+   *     non-control messages from the current isolate to the receiving isolate
+   *     have been processed.
+   *     The ping effectively puts the resonse into the normal event queue after
+   *     previously sent messages.
+   *     This can be used to wait for a another event to be processed.
+   *
+   * WARNING: This method is not handled on all platforms yet.
+   */
+  void ping(SendPort responsePort, [int pingType = PING_ALIVE]) {
+    var message = new List(3)
+        ..[0] = "ping"
+        ..[1] = responsePort
+        ..[2] = pingType;
+    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  ")}';
   }
 }