Add pause methods to Isolate.

sdk/lib/isolate/isolate.dart

Index: sdk/lib/isolate/isolate.dart
diff --git a/sdk/lib/isolate/isolate.dart b/sdk/lib/isolate/isolate.dart
index 7cf0b3613cf50b43ab98445c4e3ef7eb32631d27..e988e043436bd5966e27c5be908179c22d350a91 100644
--- a/sdk/lib/isolate/isolate.dart
+++ b/sdk/lib/isolate/isolate.dart
@@ -29,11 +29,25 @@ class IsolateSpawnException implements Exception {
 }
 
 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
@@ -76,6 +90,58 @@ class Isolate {
    */
   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);
+  }
 }
 
 /**