isolates: remove Isolate2 interface, add top-level spawn functions, more comments

lib/isolate/isolate_api.dart

 // Copyright (c) 2011, 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.
 
 /**
+ * The initial [ReceivePort] available by default for this isolate. This
+ * [ReceivePort] is created automatically and it is commonly used to establish
+ * the first communication between isolates (see [spawnFunction] and
+ * [spawnUri]).
+ */
+ReceivePort get port() => _port;
+
+/**
+ * Creates and spawns an isolate that shares the same code as the current
+ * isolate, but that starts from [topLevelFunction]. The [topLevelFunction]
+ * argument must be a static top-level function or a static method that takes no
+ * arguments. It is illegal to pass a function closure.
+ *
+ * When any isolate starts (even the main script of the application), a default
+ * [ReceivePort] is created for it. This port is available from the top-level
+ * getter [port] defined in this library.
+ *
+ * [spawnFunction] returns a [SendPort] derived from the child isolate's default
+ * port.
+ *
+ * See comments at the top of this library for more details.
+ */
+// Note this feature is not yet available in the dartvm.
+SendPort spawnFunction(void topLevelFunction()) {
+  return _spawnFunction(topLevelFunction);
+}
+
+/**
+ * Creates and spawns an isolate whose code is available at [uri].  Like with
+ * [spawnFunction], the child isolate will have a default [ReceivePort], and a
+ * this function returns a [SendPort] derived from it.
+ *
+ * See comments at the top of this library for more details.
+ */
+SendPort spawnUri(String uri) {
+  return _spawnUri(uri);
+}
+
+/**
  * [SendPort]s are created from [ReceivePort]s. Any message sent through
  * a [SendPort] is delivered to its respective [ReceivePort]. There might be
  * many [SendPort]s for the same [ReceivePort].
  *
  * [SendPort]s can be transmitted to other isolates.
  */
 interface SendPort extends Hashable {
 
   /**
    * Sends an asynchronous [message] to this send port. The message is
@@ skipping 19 matching lines @@
    bool operator==(var other);
 
   /**
    * Returns an immutable hash code for this send port that is
    * consistent with the == operator.
    */
   int hashCode();
 
 }
 
-
 /**
  * [ReceivePort]s, together with [SendPort]s, are the only means of
  * communication between isolates. [ReceivePort]s have a [:toSendPort:] method
  * which returns a [SendPort]. Any message that is sent through this [SendPort]
  * is delivered to the [ReceivePort] it has been created from. There, they are
  * dispatched to the callback that has been registered on the receive port.
  *
  * A [ReceivePort] may have many [SendPort]s.
  */
 interface ReceivePort default _ReceivePortFactory {
@@ skipping 29 matching lines @@
 
   /**
    * Creates a new send port that sends to this receive port. It is legal to
    * create several [SendPort]s from the same [ReceivePort].
    */
   SendPort toSendPort();
 
 }
 
 /**
+ * NOTE: This API will be deprecated soon.
+ *
  * The [Isolate] class serves two purposes: (1) as template for spawning a new
  * isolate, and (2) as entry-point for the newly spawned isolate.
  *
  * New isolates are spawned by sub-classing [Isolate] and then invoking
  * [:spawn:] on the instance. This will spawn a new isolate, which creates a
  * new instance of the class, initializes the instance's [port] field
  * and invokes the instance method [main].
  *
  * The new instance is created by invoking the default constructor of the
  * class that served as template for spawning the new isolate. This means, that
  * sub-classes must have a default constructor (i.e. no-argument constructor).
  *
  * Isolates may be "heavy" or "light". Heavy isolates live in their own thread,
  * whereas "light" isolates live in the same thread as the isolate which spawned
  * them.
+ *
+ * NOTE: once [spawnFunction] and [spawnUri] are supported in both frog and the
+ * dartvm, this class will be removed. The distinction of heavy and light will
+ * be removed too. Thus far the main use for 'light' isolates is for running
+ * isolates that share access to the DOM. A special API will be added for this
+ * purpose soon. See the library top-level comments for more details.
  */
-// TODO(sigmund): delete once we implement the new isolates in the vm
+// TODO(sigmund): delete once we implement the new API in the vm
 class Isolate {
 
   /**
    * Redirects to [Isolate.light].
    */
   Isolate() : this.light();
 
   /**
    * Creates a new isolate-template for a light isolate.
    */
@@ skipping 48 matching lines @@
   /**
    * When isolates are created, an instance of the template's class is
    * instantiated in the new isolate. After the [port] has been set up, this
    * [main] method is invoked on the instance.
    */
   abstract void main();
 
   final bool _isLight;
   ReceivePort _port;
 }
-
-/**
- * [Isolate2] provides APIs to spawn, communicate, and stop an isolate. An
- * isolate can be spawned by simply creating a new instance of [Isolate2]. The
- * [Isolate2] instance exposes a port to communicate with the isolate and
- * methods to control its behavior remotely.
- */
- // TODO(sigmund): rename to Isolate once we delete the old implementation
-interface Isolate2 default _IsolateFactory {
-
-  /**
-   * Create and spawn an isolate that shares the same code as the current
-   * isolate, but that starts from [topLevelFunction]. The [topLevelFunction]
-   * argument must be a static method closure that takes exactly one
-   * argument of type [ReceivePort]. It is illegal to pass a function closure
-   * that captures values in scope.
-   *
-   * When an child isolate is spawned, a new [ReceivePort] is created for it.
-   * This port is passed to [topLevelFunction]. A [SendPort] derived from
-   * such port is sent to the spawner isolate, which is accessible in
-   * [Isolate2.sendPort] field of this instance.
-   */
-  Isolate2.fromCode(Function topLevelFunction);
-
-  /**
-   * Create and spawn an isolate whose code is available at [uri].
-   * The code in [uri] must have an method called [: isolateMain :], which takes
-   * exactly one argument of type [ReceivePort].
-   * Like with [Isolate2.fromCode], a [ReceivePort] is created in the child
-   * isolate, and a [SendPort] to it is stored in [Isolate2.sendPort].
-   */
-  Isolate2.fromUri(String uri);
-
-  /** Port used to communicate with this isolate. */
-  SendPort sendPort;
-}