Add pause methods to Isolate.

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 {
+  /**
+   * Control port used to send control messages to the isolate.
+   *
+   * This class provides helper functions that work by sending messages
+   * to the control port.
+   *
+   * The accepted messages of a control port are all lists containing

[floitsch, 2014/02/04 12:39:25]

I would prefer not to expose the protocol just yet.

This means that normal receive-ports need to filter out control messages (and
similarly control receive-ports need to filter out non-control messages).

[Lasse Reichstein Nielsen, 2014/02/04 14:02:29]

I thought we were going to expose the control port and capabilities.
Will we make the control messages not be normal messages that the user can send
directly? I.e., wrapping in an "Isolate" is the only way to send the message
(which is not safe, because the user can implement SendPort and record the
message that way).

[floitsch, 2014/02/04 16:57:49]

If we are certain that this is the protocol we want to support, sure.
I would prefer not to expose it just yet. If users do some tricks to get to it,
that's fine. They can't expect it not to change, though.

+   * a string identifying the request, and optionally a number of parameters.
+   *
+   * NOTICE: The formats of these messages are tentative.
+   *
+   * * Pause: `["pause", pauseCapability, resumeCapability]`.
+   * * Resume: `["resume", resumeCapability]`.
+   *
+   */
+  final SendPort controlPort;
+  final Capability pauseCapability;
 
-  final SendPort _controlPort;
-
-  Isolate._fromControlPort(SendPort controlPort)
-      : this._controlPort = controlPort;
+  Isolate._fromControlPort(this.controlPort, [this.pauseCapability]);

[Lasse Reichstein Nielsen, 2014/02/04 14:02:29]

Should eventually be public.

 
   /**
    * 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
@@ skipping 22 matching lines @@
    * * `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.
    */
   external static Future<Isolate> spawnUri(
       Uri uri, List<String> args, var message);
+
+
+  /**
+   * 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.
+   *
+   * 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.
+   *
+   * 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.
+   */
+  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 requresting that it ends a pause

[floitsch, 2014/02/04 12:39:25]

requesting

+   * that was requested using the [resumeCapability].
+   * The resume will happen eventually, but not necessarily right away.

[floitsch, 2014/02/04 12:39:25]

Remove that line.

+   *
+   * 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.
+   */
+  void resume(Capability resumeCapability) {
+    var message = new List(2)
+        ..[0] = "resume"
+        ..[1] = resumeCapability;
+    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  ")}';
   }
 }