Update Isolate API.

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 35d2a8b15c90cb444672753f7b197714faa39ab3..0d50fa3eba265088c652cc8250b701d10b3426f7 100644
--- a/sdk/lib/isolate/isolate.dart
+++ b/sdk/lib/isolate/isolate.dart
@@ -63,8 +63,6 @@ class Isolate {
   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.
@@ -259,20 +257,26 @@ class Isolate {
   external void resume(Capability resumeCapability);
 
   /**
-   * Asks the isolate to send a message on [responsePort] when it terminates.
+   * Asks the isolate to send [response] on [responsePort] when it terminates.
    *
    * WARNING: This method is experimental and not handled on every platform yet.
    *
-   * The isolate will send a `null` message on [responsePort] as the last
+   * The isolate will send a `response` message on `responsePort` as the last
    * thing before it terminates. It will run no further code after the message
    * has been sent.
    *
+   * Adding the same poort more than once will only cause it to receive one

[Søren Gjesse, 2015/04/13 08:25:55]

poort -> port

[Lasse Reichstein Nielsen, 2015/04/13 10:15:03]

Done.

+   * message, using the last response value that was added.
+   *
    * If the isolate is already dead, no message will be sent.
+   * If `response` cannot be sent to the isolate, then the request is ignored.
+   * It is recommended to only use simple values that can be sent to all
+   * isolates, like `null`, booleans, numbers or strings.
    */
   /* TODO(lrn): Can we do better? Can the system recognize this message and
    * send a reply if the receiving isolate is dead?
    */
-  external void addOnExitListener(SendPort responsePort);
+  external void addOnExitListener(SendPort responsePort, {Object response});

[Lasse Reichstein Nielsen, 2015/04/10 19:38:02]

I am slightly worried about sending the "response" object. It can be very
useful, but it does open the possibility of sending something that can't be
received at the other end, and thereby failing, silently, to add the listener.

[Søren Gjesse, 2015/04/13 08:25:55]

Don't we already know whether the other isolate is a spawn or spawnUri isolate?
Then we can check whether it need to be a 'simple value'.

[Lasse Reichstein Nielsen, 2015/04/13 10:15:03]

True, now sending an invalid value throws at the sending end. That's good enough
to prevent silent failure.

 
   /**
    * Stop listening on exit messages from the isolate.
@@ -308,8 +312,7 @@ class Isolate {
    * 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 [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT].
    * The shutdown is performed at different times depending on the priority:
    *
    * * `IMMEDIATE`: The the isolate shuts down as soon as possible.
@@ -323,44 +326,35 @@ class Isolate {
    *     control returns to the event loop of the receiving isolate,
    *     after the current event, and any already scheduled control events,
    *     are completed.
-   * * `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.
    */
-  external void kill([int priority = BEFORE_NEXT_EVENT]);
+  external void kill({int priority: BEFORE_NEXT_EVENT});

[kevmoo, 2015/04/10 19:03:10]

This is a breaking change.

[Søren Gjesse, 2015/04/13 08:25:55]

The API is still marked as experimental, and kill have only been working since
1.9, so this should be OK.

 
   /**
-   * Request that the isolate send a response on the [responsePort].
+   * Request that the isolate send [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.
+   * If the isolate is alive, it will eventually send `response`
+   * (defaulting to `null`) on the response port.
    *
-   * The [pingType] must be one of [IMMEDIATE], [BEFORE_NEXT_EVENT] or
-   * [AS_EVENT].
+   * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT].
    * The response is sent at different times depending on the ping type:
    *
    * * `IMMEDIATE`: The the isolate responds as soon as it receives the
    *     control message. This is after any previous control message
-   *     from the same isolate has been received.
+   *     from the same isolate has been received, but may be during
+   *     execution of another event.
    * * `BEFORE_NEXT_EVENT`: The response is scheduled for the next time
    *     control returns to the event loop of the receiving isolate,
    *     after the current event, and any already scheduled control events,
    *     are completed.
-   * * `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 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.
+   *
+   * If `response` cannot be sent to the isolate, then the request is ignored.
+   * It is recommended to only use simple values that can be sent to all
+   * isolates, like `null`, booleans, numbers or strings.
    */
-  external void ping(SendPort responsePort, [int pingType = IMMEDIATE]);
+  external void ping(SendPort responsePort, {Object response,

[kevmoo, 2015/04/10 19:03:10]

this is a breaking change

[kevmoo, 2015/04/10 19:03:10]

This is a breaking change.

+                                             int priority: IMMEDIATE});

[Lasse Reichstein Nielsen, 2015/04/10 19:38:02]

This is indeed a breaking change.
Luckily, the function is still marked as experimental, which means that we can
break it to improve it.

Now, if we could have both positional and named optional arguments on the same
function, then it wouldn't be a problem, the we could just add {response}
independently of what other arguments we already have.
Not having that is really cramping out style.

I would have preferred a signature of:
  void ping(SendPort responsePort, [int priority = IMMEDIATE],
                                   {Object response});
which is non-breaking, but we can't wait for the language to get unbroken.

 
   /**
    * Requests that uncaught errors of the isolate are sent back to [port].