Update isolate documentation.

Update isolate documentation.

[floitsch, 2013-12-10 10:42:22]

We don't implement this yet, so I will wait before committing, but I want to
file a bug against co19 asap.

[Lasse Reichstein Nielsen, 2013-12-10 11:42:26]

I still don't see why errors, especially ArgumentError, should not be thrown
directly.

Every function that you call directly has a direct part.
If nothing else, its parameter type assertions are executed directly and throw
normally. I think other argument validation errors are perfectly fine to throw
directly as well. It's better to fail early than to put the errors into a future
and only discover them later.
That is from the assumption that you should not catch errors. If you think you
should catch an error, you should catch type errors as well, and then you are
back to an extra try catch.

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

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/_internal/lib/iso...
File sdk/lib/_internal/lib/isolate_helper.dart (right):

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/_internal/lib/iso...
sdk/lib/_internal/lib/isolate_helper.dart:1087: throw new
IsolateMessageException("Illegal value $x passed");
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.

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/_internal/lib/iso...
sdk/lib/_internal/lib/isolate_helper.dart:1242: throw new
IsolateDeserializationError("Unexpected serialized object");
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?

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/isolate/isolate.dart
File sdk/lib/isolate/isolate.dart (right):

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/isolate/isolate.d...
sdk/lib/isolate/isolate.dart:35: // TODO(floitsch): give access to the message
that couldn't be sent.
Ah, agree :)

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/isolate/isolate.d...
sdk/lib/isolate/isolate.dart:66: * All errors are reported asynchronously
through the returned future.
Not necessarily all errors.
Let's specify which arguments and conditions can cause an exception, and that
these exceptions are returned through the future.

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/isolate/isolate.d...
sdk/lib/isolate/isolate.dart:89: * All errors are reported asynchronously
through the returned future.
Ditto.

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

As discussed. I'm handing over to you (Lasse).

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/_internal/lib/iso...
File sdk/lib/_internal/lib/isolate_helper.dart (right):

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/_internal/lib/iso...
sdk/lib/_internal/lib/isolate_helper.dart:1087: throw new
IsolateMessageException("Illegal value $x passed");
On 2013/12/11 10:38:28, Lasse Reichstein Nielsen wrote:
> 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.

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

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/_internal/lib/iso...
sdk/lib/_internal/lib/isolate_helper.dart:1242: throw new
IsolateDeserializationError("Unexpected serialized object");
On 2013/12/11 10:38:28, Lasse Reichstein Nielsen wrote:
> 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?

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

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/isolate/isolate.dart
File sdk/lib/isolate/isolate.dart (right):

https://codereview.chromium.org/93873014/diff/20001/sdk/lib/isolate/isolate.d...
sdk/lib/isolate/isolate.dart:66: * All errors are reported asynchronously
through the returned future.
On 2013/12/11 10:38:28, Lasse Reichstein Nielsen wrote:
> Not necessarily all errors.
> Let's specify which arguments and conditions can cause an exception, and that
> these exceptions are returned through the future.

Yes.
This should be changed to list all the possible exceptions and to make sure that
they are dealt with correctly.