Proposal for new Isolate library.

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 49c0eb82b6ec79a044575f47a495bd079713d570..5394e0f11fa247d6b64a9cb7daa7782ac401b47c 100644
--- a/sdk/lib/isolate/isolate.dart
+++ b/sdk/lib/isolate/isolate.dart
@@ -6,7 +6,20 @@ 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.
+// 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 isolateArguments;

[Søren Gjesse, 2013/07/26 11:49:35]

The name of this should be in the plural form. How about isolateMessage?

[floitsch, 2013/07/26 12:01:28]

Done.

 
 class IsolateSpawnException implements Exception {
   const IsolateSpawnException(String this._s);
@@ -15,14 +28,6 @@ class IsolateSpawnException implements Exception {
 }
 
 /**

[Søren Gjesse, 2013/07/26 11:49:35]

Please remove or rewrite the old parts of the dartdoc.

[floitsch, 2013/07/26 12:01:28]

Done.

- * 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
@@ -32,24 +37,17 @@ ReceivePort get port => _Isolate.port;
  * [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.
+ * Usually the initial [message] contains a [SendPort] so 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]);

[Søren Gjesse, 2013/07/26 11:49:35]

Don't you want the topLevelFunction to take one argument?

[floitsch, 2013/07/26 12:01:28]

Sounds interesting. Would you still set the `isolateMessage` ?

Main argument against is consistency: the initial message is always in
`isolateMessage`.

 
 /**

[Søren Gjesse, 2013/07/26 11:49:35]

Ditto.

[floitsch, 2013/07/26 12:01:28]

Done.

  * 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.
  */
-SendPort spawnUri(String uri) => _Isolate.spawnUri(uri);
+void spawnUri(Uri uri, [dynamic message]);
 
 /**
  * [SendPort]s are created from [ReceivePort]s. Any message sent through
@@ -69,6 +67,10 @@ abstract class SendPort {
    * 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
+   * serializer (if given) is invoked.  TODO(floitsch): specify how
+   * serialization and deserialization should work.

[Søren Gjesse, 2013/07/26 11:49:35]

Should it be possible to override the built-in serialization as well?

[floitsch, 2013/07/26 12:01:28]

Not sure. Could be an option, but it sounds dangerous.

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

You can't override the serialization and deserialization of ports, because they
are magically handled by the system, and you can't create one.
You should not even be allowed to control the data that are passed to the
deserializer because it would allow you to create bad ports. The isolate
communication must be handled internally. We can then provide custom
serialization/deserialization for user objects, but it will be on top of our own
internal serialization.
(And yes, I have ideas for this).

+   *
    * 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
@@ -79,7 +81,7 @@ abstract class SendPort {
    * 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 });

[Søren Gjesse, 2013/07/26 11:49:35]

Serializer and deserializer come i pairs. It could be nice if in the case of
spawnFunction these could (optionally) be specified when creating the
ReceivePort. The ReceivePort would then have a default serializer and all
derived SendPorts would have a deserializer.

[floitsch, 2013/07/26 12:01:28]

I like this, but the problem is that you don't know where SendPorts end up.
The other direction, giving a deserializer to the `send` could be easier.
Added suggestion in comments.

 
   /**
    * Sends a message to this send port and returns a [Future] of the reply.
@@ -87,6 +89,9 @@ abstract class SendPort {
    * 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);
 
@@ -118,14 +123,17 @@ 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.
    */
-  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