Proposal for new Isolate library.

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.
 
 library dart.isolate;
 
 import "dart:async";
 
-part "isolate_stream.dart";
+/**
+ * Returns the initial message an isolate received.
+ *
+ * If the isolate is the main-isolate it contains the list of arguments that
+ * have been given on the command line.
+ *
+ * This getter supercedes io:Options (which is now deprecated).
+ */
+// TODO(floitsch): alternatively we could keep io:Options (or a nicer variant
+// of it). The main advantage of removing it, is that libraries/programs that
+// are otherwise server-independent could be spawned in the browser.

[Lasse Reichstein Nielsen, 2013/08/12 07:19:03]

We should have an "Options" class somewhere for easy parsing of options, but it
doesn't need to contain the arguments themselves.
It can either get them as a list of strings, or default to using
Isolate::isolateMessage.

+// If devs use dart:io just for the arguments they can't be used in spawnUri,
+// by forcing them to use dart:isolate they would run in the browser, too.
+dynamic get isolateMessage;
 
 class IsolateSpawnException implements Exception {
   const IsolateSpawnException(String this._s);
   String toString() => "IsolateSpawnException: '$_s'";
   final String _s;
 }
 
 /**
- * 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 => _Isolate.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.
- *
- * The optional [unhandledExceptionCallback] argument is invoked whenever an
- * exception inside the isolate is unhandled. It can be seen as a big
- * `try/catch` around everything that is executed inside the isolate. The
- * callback should return `true` when it was able to handled the exception.
+ * The initial [message] is stored in the global [isolateMessage] where the
+ * spawnee can access it. Usually the initial [message] contains a [SendPort] so

[Lasse Reichstein Nielsen, 2013/08/12 07:19:03]

So the user is expected to use ports directly, and not streams based on ports?
Or, in other words, Ports are still exposed?

What are the restrictions on "message"?

[floitsch, 2013/08/23 17:07:30]

Yes. But a good framework would abstract most of it away.
Basically JSON + sendports. Not sure if we can add serializer support (like for
SendPorts).

+ * that the spawner and spawnee can communicate with each other.
  */
-SendPort spawnFunction(void topLevelFunction(),
-    [bool unhandledExceptionCallback(IsolateUnhandledException e)])
-    => _Isolate.spawnFunction(topLevelFunction, unhandledExceptionCallback);
+void spawnFunction(void topLevelFunction(), [dynamic message]);
 
 /**
  * Creates and spawns an isolate whose code is available at [uri].  Like with
  * [spawnFunction], the child isolate will have a default [ReceivePort], and a

[Lasse Reichstein Nielsen, 2013/08/12 07:19:03]

It no longer returns a port.

[floitsch, 2013/08/23 17:07:30]

Done.

  * this function returns a [SendPort] derived from it.
  */
-SendPort spawnUri(String uri) => _Isolate.spawnUri(uri);
+void spawnUri(Uri uri, [dynamic message]);
 
 /**
  * [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.
  */
 abstract class SendPort {
 
   /**
    * Sends an asynchronous [message] to this send port. The message is copied to
    * the receiving isolate. If specified, the [replyTo] port will be provided to
    * the receiver to facilitate exchanging sequences of messages.
    *
    * The content of [message] can be: primitive values (null, num, bool, double,

[Lasse Reichstein Nielsen, 2013/08/12 07:19:03]

This is really annoying me, because I do it too: You list "null", which is a
value, in a list of types. It would be more correct to write "Null", but it just
reads so much better this way.

Could we rename the type of "null" to "null"? (Probably too confusing, then we
have to say "the null type" instead of just Null, but do we ever use Null in
practice?)

[floitsch, 2013/08/23 17:07:30]

:)

    * String), instances of [SendPort], and lists and maps whose elements are any
    * of these. List and maps are also allowed to be cyclic.
    *
+   * If, during serialization, an object of different type is encountered, the

[Lasse Reichstein Nielsen, 2013/08/12 07:19:03]

"an object of another type is".

Using "different" requires saying different from what, and in which way. What
you mean is "one not listed above".

And which serialization? You haven't mentioned serialization before at all, so
you need to start by saying that the message is serialized in some internal way,
and only then say that you can have a custom serialization for unrecognized
objects.

[floitsch, 2013/08/23 17:07:30]

done.
serialization is still vague. I need help to nail that part down.

+   * serializer (if given) is invoked.  TODO(floitsch): specify how
+   * serialization and deserialization should work.

[Lasse Reichstein Nielsen, 2013/08/12 07:19:03]

That's an incredibly complex thing to just introduce in a side statement.
That is, until we have something more to say, remove the parameter. We don't
want a half-cocked serialization that users begin to use.

[floitsch, 2013/08/23 17:07:30]

This is for discussion. I'm hoping we (devs) can come up with a good solution.
At that point we must, of course, update this comment.

+   *
    * In the special circumstances when two isolates share the same code and are
    * running in the same process (e.g. isolates created via [spawnFunction]), it
    * is also possible to send object instances (which would be copied in the
    * process). This is currently only supported by the dartvm.  For now, the
    * dart2js compiler only supports the restricted messages described above.
    *
    * Deprecation note: it is no longer valid to transmit a [ReceivePort] in a
    * message. Previously they were translated to the corresponding send port
    * before being transmitted.
    */
-  void send(var message, [SendPort replyTo]);
+  void send(var message, { serializer(x), SendPort replyTo });
 
   /**
    * Sends a message to this send port and returns a [Future] of the reply.
    * Basically, this internally creates a new receive port, sends a
    * message to this send port with replyTo set to such receive port, and, when
    * a reply is received, it closes the receive port and completes the returned
    * future.
+   *
+   * Note: it is not possible to provide a serializer to this function. Use
+   * [send] instead.
    */
   Future call(var message);
 
   /**
    * Tests whether [other] is a [SendPort] pointing to the same
    * [ReceivePort] as this one.
    */
   bool operator==(var other);
 
   /**
@@ skipping 11 matching lines @@
  * 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.
  */
 abstract class ReceivePort {
 
   /**
    * Opens a long-lived port for receiving messages. The returned port
    * must be explicitly closed through [ReceivePort.close].
+   *
+   * If a message was serialized during sending the deserializer is invoked
+   * when receiving data.

[Lasse Reichstein Nielsen, 2013/08/12 07:19:03]

So the deserializer is invoked on the entire message, but the serializer only on
the sub-parts that aren't handled?
Drop this for now. We can make it symmetric when we have a good story about
serialization.

[floitsch, 2013/08/23 17:07:30]

This CL is partially to discuss a good story. Leaving for now.

    */
-  external factory ReceivePort();
+  external factory ReceivePort({ deserializer(x) });
 
   /**
    * Sets up a callback function for receiving pending or future
    * messages on this receive port.
    */
-  void receive(void callback(var message, SendPort replyTo));
+  void onData(void callback(var message, SendPort replyTo));
 
   /**
    * Closes this receive port immediately. Pending messages will not
    * be processed and it is impossible to re-open the port. Single-shot
    * reply ports, such as those created through [SendPort.call], are
    * automatically closed when the reply has been received. Multiple
    * invocations of [close] are allowed but ignored.
    */
   void close();
 
@@ skipping 59 matching lines @@
   const IsolateUnhandledException(this.message, this.source, this.stackTrace);
 
   String toString() {
     return 'IsolateUnhandledException: exception while handling message: '
         '${message} \n  '
         '${source.toString().replaceAll("\n", "\n  ")}\n'
         'original stack trace:\n  '
         '${stackTrace.toString().replaceAll("\n","\n  ")}';
   }
 }