Update isolate documentation.

sdk/lib/_internal/lib/isolate_helper.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 _isolate_helper;
 
 import 'dart:async';
 import 'dart:collection' show Queue, HashMap;
 import 'dart:isolate';
 import 'dart:_js_helper' show
     Closure,
     Null,
     Primitives,
     convertDartClosureToJS;
 import 'dart:_foreign_helper' show DART_CLOSURE_TO_JS,
                                    JS,
                                    JS_CREATE_ISOLATE,
                                    JS_CURRENT_ISOLATE_CONTEXT,
                                    JS_CURRENT_ISOLATE,
                                    JS_SET_CURRENT_ISOLATE,
                                    IsolateContext;
 import 'dart:_interceptors' show JSExtendableArray;
 
 ReceivePort controlPort;
 
+class IsolateDeserializationError extends Error {
+  final String _message;
+  IsolateDeserializationError(this._message);
+
+  toString() => "IsolateDeserializationError: $_message";
+}
+
 /**
  * Called by the compiler to support switching
  * between isolates when we get a callback from the DOM.
  */
 _callInIsolate(_IsolateContext isolate, Function function) {
   var result = isolate.eval(function);
   _globalState.topEventLoop.run();
   return result;
 }
 
@@ skipping 1034 matching lines @@
     // Overridable fallback.
     return visitObject(x);
   }
 
   visitPrimitive(x);
   visitList(List x);
   visitMap(Map x);
   visitSendPort(SendPort x);
 
   visitObject(Object x) {
-    // TODO(floitsch): make this a real exception. (which one)?
-    throw "Message serialization: Illegal value $x passed";
+    throw new IsolateMessageException("Illegal value $x passed");

[Lasse Reichstein Nielsen, 2013/12/11 10:38:28]

Could we put the value of x into the object?
If the receiver of the exception is also the one passing the value, it won't
leak anything, and it can be useful to inspect the object that causes the
problem.
This is an Exception, so you need data that can allow you to act on the
exception. The value of x, and perhaps the entire message as well, seems
reasonable.

[floitsch, 2013/12/11 12:14:16]

Yes. I would like that.
The problem is that it would require more changes to the VM, so I only marked it
as TODO.

   }
 
   static bool isPrimitive(x) {
     return (x == null) || (x is String) || (x is num) || (x is bool);
   }
 }
 
 
 /** A visitor that recursively copies a message. */
 class _Copier extends _MessageTraverser {
@@ skipping 134 matching lines @@
       var key = _deserializeHelper(keys[i]);
       var value = _deserializeHelper(values[i]);
       result[key] = value;
     }
     return result;
   }
 
   deserializeSendPort(List x);
 
   deserializeObject(List x) {
-    // TODO(floitsch): Use real exception (which one?).
-    throw "Unexpected serialized object";
+    throw new IsolateDeserializationError("Unexpected serialized object");

[Lasse Reichstein Nielsen, 2013/12/11 10:38:28]

How does this error occur?

It happens during deserialization, but anything passed through serialization
should be deserializable as well, so is this really a sanity check?

[floitsch, 2013/12/11 12:14:16]

It's a sanity check, and could happen once we have cross-computer isolates. In
that case other users could fake isolate-messages.

   }
 }
 
 class TimerImpl implements Timer {
   final bool _once;
   bool _inEventLoop = false;
   int _handle;
 
   TimerImpl(int milliseconds, void callback())
       : _once = true {
@@ skipping 64 matching lines @@
       _handle = null;
     } else {
       throw new UnsupportedError("Canceling a timer.");
     }
   }
 
   bool get isActive => _handle != null;
 }
 
 bool hasTimer() => JS('', '#.setTimeout', globalThis) != null;