Add Isolate.kill().

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;
+  /** Argument to `ping` and `kill`: Ask for immediate action. */
+  static const int IMMEDIATE = 0;
+  /** Argument to `ping` and `kill`: Ask for action before the next event. */
+  static const int BEFORE_NEXT_EVENT = 1;
+  /** Argument to `ping` and `kill`: Ask for action after normal events. */
+  static const int AS_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;
   /**
    * Capability granting the ability to pause the isolate.
@@ skipping 60 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 });
 
-
   /**
    * Requests the isolate to pause.
    *
    * WARNING: This method is experimental and not handled on every platform yet.
    *
    * 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.
    *
@@ skipping 96 matching lines @@
    */
   void setErrorsFatal(bool errorsAreFatal) {
     var message = new List(3)
         ..[0] = "set-errors-fatal"
         ..[1] = terminateCapability
         ..[2] = errorsAreFatal;
     controlPort.send(message);
   }
 
   /**
+   * Requests the isolate to shut down.
+   *
+   * WARNING: This method is experimental and not handled on every platform yet.
+   *
+   * The isolate is requested to terminate itself.
+   * The [priority] argument specifies when this must happen.
+   *
+   * The [priority] must be one of [IMMEDIATE], [BEFORE_NEXT_EVENT] or
+   * [AS_EVENT].
+   * The shutdown is performed at different times depending on the priority:
+   *
+   * * `IMMEDIATE`: The the isolate shuts down as soon as possible.
+   *     Control messages are handled in order, so all previously sent control
+   *     events from this isolate will all have been processed.
+   *     The shutdown should happen no later than if sent with
+   *     `BEFORE_NEXT_EVENT`.
+   *     It may happen earlier if the system has a way to shut down cleanly
+   *     at an earlier time, even during the execution of another event.
+   * * `BEFORE_NEXT_EVENT`: The shutdown is scheduled for the next time
+   *     control returns to the event loop of the receiving isolate.
+   *     If more than one such event are scheduled, they are executed in
+   *     the order their control messages were received.
+   * * `AS_EVENT`: The shutdown does not happen until all prevously sent
+   *     non-control messages from the current isolate to the receiving isolate
+   *     have been processed.
+   *     The kill operation effectively puts the shutdown into the normal event
+   *     queue after previously sent messages, and it is affected by any control
+   *     messages that affect normal events, including `pause`.
+   *     This can be used to wait for a another event to be processed.
+   */
+  void kill([int priority = BEFORE_NEXT_EVENT]) {
+    controlPort.send(["kill", terminateCapability, priority]);
+  }
+
+  /**
    * Request that the isolate send a response on the [responsePort].
    *
    * WARNING: This method is experimental and not handled on every platform yet.
    *
    * 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 [pingType] must be one of [IMMEDIATE], [BEFORE_NEXT_EVENT] or
+   * [AS_EVENT].
    * The response is sent at different times depending on the ping type:
    *
-   * * `PING_ALIVE`: The the isolate responds as soon as possible.
-   *     The response should happen no later than if sent with `PING_CONTROL`.
-   *     It may be sent earlier if the system has a way to do so.
-   * * `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
+   * * `IMMEDIATE`: The the isolate responds as soon as it receives the
+   *     control message.
+   * * `BEFORE_NEXT_EVENT`: The response is scheduled for the next time
+   *     control returns to the event loop of the receiving isolate.
+   *     If more than one such event are scheduled, they are executed in
+   *     the order their control messages were received.
+   * * `AS_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.
+   *     The ping effectively puts the response into the normal event queue
+   *     after previously sent messages, and it is affected by any control
+   *     messages that affect normal events, including `pause`.
    *     This can be used to wait for a another event to be processed.
    */
-  void ping(SendPort responsePort, [int pingType = PING_ALIVE]) {
+  void ping(SendPort responsePort, [int pingType = IMMEDIATE]) {
     var message = new List(3)
         ..[0] = "ping"
         ..[1] = responsePort
         ..[2] = pingType;
     controlPort.send(message);
   }
 }
 
 /**
  * Sends messages to its [ReceivePort]s.
@@ skipping 152 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  ")}';
   }
 }