Document the fact that SendPort.send() dispatches messages immediately.

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.
 
 /**
  * Concurrent programming using _isolates_:
  * independent workers that are similar to threads
  * but don't share memory,
  * communicating only via messages.
  */
@@ skipping 467 matching lines @@
    *
    * The content of [message] can be: primitive values (null, num, bool, double,
    * String), instances of [SendPort], and lists and maps whose elements are any
    * of these. List and maps are also allowed to be cyclic.
    *
    * In the special circumstances when two isolates share the same code and are
    * running in the same process (e.g. isolates created via [Isolate.spawn]), 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.
+   *
+   * The send is immediate--it is not necessary to yield control to the event
+   * loop, provided that the receiver is running in a parallel isolate.

[Lasse Reichstein Nielsen, 2015/08/31 19:45:20]

I don't think we use the term "parallel isolate" anywhere else.
Maybe just "in another isolate".
It's still a little vague - it's not saying what wouldn't work if it wasn't the
way it is, or why yielding to the event loop is relevant. 

Maybe instead say:

The send happens immediately and doesn't block. The corresponding receive port
can receive the message as soon as its isolate's event loop is ready to deliver
it, independently of what the sending isolate is doing.

Is that too wordy?

[Paul Berry, 2015/08/31 19:48:53]

Works for me.  PTAL.

    */
   void send(var message);
 
   /**
    * Tests whether [other] is a [SendPort] pointing to the same
    * [ReceivePort] as this one.
    */
   bool operator==(var other);
 
   /**
@@ skipping 134 matching lines @@
  * as the original error, but has no other features of the original error.
  */
 class RemoteError implements Error {
   final String _description;
   final StackTrace stackTrace;
   RemoteError(String description, String stackDescription)
       : _description = description,
         stackTrace = new StackTrace.fromString(stackDescription);
   String toString() => _description;
 }