Update documentation around Isolate capabilities.

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 32 matching lines @@
  * object representing the new isolate when the spawn operation succeeds.
  *
  * Isolates run code in its own event loop, and each event may run smaller tasks
  * in a nested microtask queue.
  *
  * An `Isolate` object allows other isolates to control the event loop
  * of the isolate that it represents, and to inspect the isolate,
  * for example by pausing the isolate or by getting events when the isolate
  * has an uncaught error.
  *
- * The [controlPort] gives access to controlling the isolate, and the
- * [pauseCapability] and [terminateCapability] guard access to some control
- * operations.
+ * The [controlPort] identifies and gives access to controlling the isolate,
+ * and the [pauseCapability] and [terminateCapability] guard access
+ * to some control operations.
+ * For example, calling [pause] on an `Isolate` object created without a
+ * [pauseCapability], has no effect.
+ *
  * The `Isolate` object provided by a spawn operation will have the
  * control port and capabilities needed to control the isolate.
- * New isolates objects can be created without some of these capabilities
- * if necessary.
+ * New isolate objects can be created without some of these capabilities
+ * if necessary, using the [Isolate.Isolate] constructor.
  *
  * An `Isolate` object cannot be sent over a `SendPort`, but the control port
  * and capabilities can be sent, and can be used to create a new functioning
  * `Isolate` object in the receiving port's isolate.
  */
 class Isolate {
   /** 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;
 
   /**
    * Control port used to send control messages to the isolate.
    *
-   * This class provides helper functions that sends control messages
-   * to the control port.
+   * The control port identifies the isolate.
    *
-   * The control port identifies the isolate.
+   * An `Isolate` object allows sending control messages
+   * through the control port.
+   *
+   * Some control messages require a specific capability to be passed along
+   * with the message (see [pauseCapability] and [terminateCapaibility]),
+   * otherwise the message is ignored by the isolate.
    */
   final SendPort controlPort;
 
   /**
    * Capability granting the ability to pause the isolate.
    *
-   * This capability is used by [pause].
-   * If the capability is not the correct pause capability of the isolate,
-   * including if the capability is `null`, then calls to `pause` will have no
-   * effect.
+   * This capability is required by [pause].
+   * If the capability is `null`, or if it is not the correct pause capability
+   * of the isolate identified by [controlPort],
+   * then calls to [pause] will have no effect.
    *
-   * If the isolate is started in a paused state, use this capability as
+   * If the isolate is spawned in a paused state, use this capability as
    * argument to [resume] to resume the isolate.
    */
   final Capability pauseCapability;
 
   /**
    * Capability granting the ability to terminate the isolate.
    *
-   * This capability is used by [kill] and [setErrorsFatal].
-   * If the capability is not the correct termination capability of the isolate,
-   * including if the capability is `null`, then calls to those methods will
-   * have no effect.
+   * This capability is required by [kill] and [setErrorsFatal].
+   * If the capability is `null`, or if it is not the correct termination
+   * capability of the isolate identified by [controlPort],
+   * then calls to those methods will have no effect.
    */
   final Capability terminateCapability;
 
   /**
    * Create a new [Isolate] object with a restricted set of capabilities.
    *
    * The port should be a control port for an isolate, as taken from
    * another `Isolate` object.
    *
    * The capabilities should be the subset of the capabilities that are
    * available to the original isolate.
    * Capabilities of an isolate are locked to that isolate, and have no effect
    * anywhere else, so the capabilities should come from the same isolate as
    * the control port.
    *
-   * If all the available capabilities are included,
-   * there is no reason to create a new object,
-   * since the behavior is defined entirely
-   * by the control port and capabilities.
+   * Can also be used to create an [Isolate] object from a control port, and
+   * any available capabilities, that have been sent through a [SendPort].
+   *
+   * Example:
+   * ```dart
+   * Isolate isolate = findSomeIsolate();
+   * Isolate restrictedIsolate = new Isolate(isolate.controlPort);
+   * untrustedCode(restrictedIsolate);
+   * ```
+   * This example creates a new `Isolate` object that cannot be used to
+   * pause or terminate the isolate. All the untrusted code can do is to
+   * inspect the isolate and see uncaught errors or when it terminates.
    */
   Isolate(this.controlPort, {this.pauseCapability,
                              this.terminateCapability});
 
   /**
    * Return the current [Isolate].
    *
    * The isolate gives access to the capabilities needed to inspect,
    * pause or kill the isolate, and allows granting these capabilities
    * to others.
@@ skipping 168 matching lines @@
        Uri packageRoot,
        Uri packageConfig,
        bool automaticPackageResolution: false});
 
   /**
    * Requests the isolate to pause.
    *
    * 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
-   * the already enqueued events.
+   * or receive-port messages. When the isolate is resumed,
+   * it starts handling the already enqueued events.
    *
    * 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,
+   * The [resumeCapability] is used to identity the pause,
    * and must be used again to end the pause using [resume].
-   * Otherwise a new resume capability is created and returned.
+   * If [resumeCapability] is omitted, a new capability object is created
+   * and used instead.
    *
    * If an isolate is paused more than once using the same capability,
    * only one resume with that capability is needed to end the pause.
    *
    * If an isolate is paused using more than one capability,
    * each pause must be individually ended before the isolate resumes.
    *
    * Returns the capability that must be used to end the pause.
+   * This is either [resumeCapability], or a new capability when
+   * [resumeCapability] is omitted.
+   *
+   * If [pauseCapability] is `null`, or it's not the pause capability
+   * of the isolate identified by [controlPort],
+   * the pause request is ignored by the receiving isolate.
    */
   Capability pause([Capability resumeCapability]) {
     resumeCapability ??= new Capability();
     _pause(resumeCapability);
     return resumeCapability;
   }
 
   /** Internal implementation of [pause]. */
   external void _pause(Capability resumeCapability);
 
   /**
    * Resumes a paused isolate.
    *
    * Sends a message to an isolate requesting that it ends a pause
-   * that was requested using the [resumeCapability].
+   * that was previously requested.
    *
    * When all active pause requests have been cancelled, the isolate
    * 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.
+   * If the [resumeCapability] is not one that has previously been used
+   * to pause the isolate, or it has already been used to resume from
+   * that pause, the resume call has no effect.
    */
   external void resume(Capability resumeCapability);
 
   /**
    * Asks the isolate to send [response] on [responsePort] when it terminates.
    *
    * 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.
    *
@@ skipping 28 matching lines @@
    */
   external void removeOnExitListener(SendPort responsePort);
 
   /**
    * Set whether uncaught errors will terminate the isolate.
    *
    * If errors are fatal, any uncaught error will terminate the isolate
    * event loop and shut down the isolate.
    *
    * This call requires the [terminateCapability] for the isolate.
-   * If the capability is not correct, no change is made.
+   * If the capability absent or wrong, no change is made.
    *
    * Since isolates run concurrently, it's possible for it to exit due to an
    * error before errors are set non-fatal.
    * To avoid this, either use the corresponding parameter to the spawn
    * function, or start the isolate paused, set errors non-fatal and
    * then resume the isolate.
    */
   external void setErrorsFatal(bool errorsAreFatal);
 
   /**
    * Requests the isolate to shut down.
    *
    * The isolate is requested to terminate itself.
    * The [priority] argument specifies when this must happen.
    *
    * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT].
    * The shutdown is performed at different times depending on the priority:
    *
    * * `IMMEDIATE`: 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,
    *     after the current event, and any already scheduled control events,
    *     are completed.
+   *
+   * If [terminateCapability] is `null`, or it's not the terminate capability
+   * of the isolate identified by [controlPort],
+   * the kill request is ignored by the receiving isolate.
    */
   external void kill({int priority: BEFORE_NEXT_EVENT});
 
   /**
    * Request that the isolate send [response] on the [responsePort].
    *
    * If the isolate is alive, it will eventually send `response`
    * (defaulting to `null`) on the response port.
    *
    * The [priority] must be one of [IMMEDIATE] or [BEFORE_NEXT_EVENT].
@@ skipping 234 matching lines @@
  * as the original error, but has no other features of the original error.
  */
 class RemoteError implements Error {
   final String _description;
   final StackTrace stackTrace;
   RemoteError(String description, String stackDescription)
       : _description = description,
         stackTrace = new StackTrace.fromString(stackDescription);
   String toString() => _description;
 }