Address shortcomings in documentation on Isolate class.

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 8caccdb4e0ac56198ceae436b91e2e68350d3211..34ef29e83752454c2b1ce34387555a4fd80a0e2e 100644
--- a/sdk/lib/isolate/isolate.dart
+++ b/sdk/lib/isolate/isolate.dart
@@ -7,9 +7,9 @@
  * independent workers that are similar to threads
  * but don't share memory,
  * communicating only via messages.
- * 
+ *
  * To use this library in your code:
- * 
+ *
  *     import 'dart:isolate';
  */
 library dart.isolate;
@@ -162,19 +162,27 @@ class Isolate {
    * 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
-   * method extracted from an object.
+   * The argument [entryPoint] specifies the initial function to call
+   * in the spawned isolate.
+   * The entry-point function is invoked in the new isolate with [message]
+   * as the only argument.
+   *
+   * The function must be a top-level function or a static method
+   * that can be called with a single argument,
+   * that is, a compile-time constant function value
+   * which accepts at least one positional parameter
+   * and has at most one required positional parameter.
+   * The function may accept any number of optional parameters,
+   * as long as it *can* be called with just a single argument.
+   * The function must not be the value of a function expression
+   * or an instance method tear-off.
    *
-   * The entry-point function is invoked with the initial [message].
    * Usually the initial [message] contains a [SendPort] so
    * that the spawner and spawnee can communicate with each other.
    *
    * If the [paused] parameter is set to `true`,
    * the isolate will start up in a paused state,
+   * just before calling the [entryPoint] function with the [message],
    * as if by an initial call of `isolate.pause(isolate.pauseCapability)`.
    * To resume the isolate, call `isolate.resume(isolate.pauseCapability)`.
    *
@@ -184,19 +192,22 @@ class Isolate {
    * corresponding parameter and was processed before the isolate starts
    * running.
    *
+   * If [errorsAreFatal] is omitted, the platform may choose a default behavior
+   * or inherit the current isolate's behavior.
+   *
    * You can also call the [setErrorsFatal], [addOnExitListener] and
    * [addErrorListener] methods on the returned isolate, but unless the
    * isolate was started as [paused], it may already have terminated
    * before those methods can complete.
    *
-   * Returns a future that will complete with an [Isolate] instance if the
+   * Returns a future which will complete with an [Isolate] instance if the
    * spawning succeeded. It will complete with an error otherwise.
    */
   external static Future<Isolate> spawn(void entryPoint(message), var message,
-                                        { bool paused: false,
-                                          bool errorsAreFatal,
-                                          SendPort onExit,
-                                          SendPort onError });
+                                        {bool paused: false,
+                                         bool errorsAreFatal,
+                                         SendPort onExit,
+                                         SendPort onError});
 
   /**
    * Creates and spawns an isolate that runs the code from the library with
@@ -291,13 +302,16 @@ class Isolate {
   /**
    * 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 that are later sent to the
-   * isolate from the current isolate, but no other guarantees are provided.
+   * When the isolate receives the pause command, it stops
+   * processing events from the event loop queue.
+   * It may still add new events to the queue in response to, e.g., timers
+   * or receive port messages. When the isolate is resumed, it handles

[floitsch, 2016/07/04 14:38:27]

receive-port

[Lasse Reichstein Nielsen, 2016/09/28 08:42:03]

Done.

+   * the already enqueued events in their existing order.

[floitsch, 2016/07/04 14:38:27]

I would drop the 'in their existing order'.
It reads like "in order", but that's not true.

If I'm not wrong, the order is actually different than if the system hadn't been
paused, because high-priority events are executed earlier.

[Lasse Reichstein Nielsen, 2016/09/28 08:42:02]

Dropped.
I do think the events are executed in the order they were enqueued, which is the
order they would have been executed in if the isolate hadn't been paused. Unless
timers are handled differently.
I'm not sure what high-priority events are.

    *
-   * The event loop may be paused before previously sent, but not yet exeuted,
-   * messages have been reached.
+   * The pause request is sent through the isolate's command port,
+   * which bypasses the receiving isolate's event loop.
+   * The pause takes effect when it is received, pausing the event loop
+   * as it is at that time.
    *
    * If [resumeCapability] is provided, it is used to identity the pause,
    * and must be used again to end the pause using [resume].
@@ -307,12 +321,12 @@ class Isolate {
    * 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.
+   * each pause must be individully ended before the isolate resumes.

[floitsch, 2016/07/04 14:38:27]

individually

[Lasse Reichstein Nielsen, 2016/09/28 08:42:02]

Done.

    *
-   * Returns the capability that must be used to resume end the pause.
+   * Returns the capability that must be used to end the pause.
    */
   Capability pause([Capability resumeCapability]) {
-    if (resumeCapability == null) resumeCapability = new Capability();
+    resumeCapability ??= new Capability();
     _pause(resumeCapability);
     return resumeCapability;
   }
@@ -327,7 +341,7 @@ class Isolate {
    * that was requested using the [resumeCapability].
    *
    * When all active pause requests have been cancelled, the isolate
-   * will continue handling normal messages.
+   * will continue processing events and handling normal messages.
    *
    * The capability must be one returned by a call to [pause] on this
    * isolate, otherwise the resume call does nothing.