[vm/concurrency] Update documentation of SendPort.send to be more precise

In addition to making the documentation of [SendPort.send] more precise
by describing what objects are disallowed for sending objects between
isolates within the same isolate group, it also makes [Isolate.exit]
link to [SendPort.send].

Closes #46623

TEST=Updates documentation only.

Change-Id: I9bc1d88faaf2b70589af5e56168976ba89a35558
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/219080
Commit-Queue: Martin Kustermann <[email protected]>
Reviewed-by: Alexander Aprelev <[email protected]>

Author: mkustermann

sdk/lib/isolate/isolate.dart

@@ -563,9 +563,9 @@ class Isolate {
   /// This operation is potentially dangerous and should be used judiciously.
   /// The isolate stops operating *immediately*. It throws if the optional
   /// [message] does not adhere to the limitations on what can be sent from one
-  /// isolate to another. It also throws if a [finalMessagePort] is associated
-  /// with an isolate spawned outside of current isolate group, spawned via
-  /// [spawnUri].
+  /// isolate to another (see [SendPort.send] for more details). It also throws
+  /// if a [finalMessagePort] is associated with an isolate spawned outside of
+  /// current isolate group, spawned via [spawnUri].
   ///
   /// If successful, a call to this method does not return. Pending `finally`
   /// blocks are not executed, control flow will not go back to the event loop,
@@ -575,9 +575,9 @@ class Isolate {
   /// code will run in the isolate.)
   ///
   /// If [finalMessagePort] is provided, and the [message] can be sent through
-  /// it, then the message is sent through that port as the final operation of
-  /// the current isolate. The isolate terminates immediately after
-  /// that [SendPort.send] call returns.
+  /// it (see [SendPort.send] for more details), then the message is sent
+  /// through that port as the final operation of the current isolate. The
+  /// isolate terminates immediately after that [SendPort.send] call returns.
   ///
   /// If the port is a native port -- one provided by [ReceivePort.sendPort] or
   /// [RawReceivePort.sendPort] -- the system may be able to send this final
@@ -599,9 +599,10 @@ class Isolate {
 /// when sent.
 abstract class SendPort implements Capability {
   /// Sends an asynchronous [message] through this send port, to its
-  /// corresponding `ReceivePort`.
+  /// corresponding [ReceivePort].
   ///
-  /// The content of [message] can be:
+  /// The transitive object graph of [message] can contain the following
+  /// objects:
   ///   - [Null]
   ///   - [bool]
   ///   - [int]
@@ -612,14 +613,34 @@ abstract class SendPort implements Capability {
   ///   - [SendPort]
   ///   - [Capability]
   ///
-  /// 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).
-  ///
-  /// The send happens immediately and doesn't block.  The corresponding receive
+  /// If the sender and receiver isolate share the same code (e.g. isolates
+  /// created via [Isolate.spawn]), the transitive object graph of [message] can
+  /// contain any object, with the following exceptions:
+  ///
+  ///   - Objects with native resources (subclasses of e.g.
+  ///     `NativeFieldWrapperClass1`). A [Socket] object for example referrs
+  ///     internally to objects that have native resources attached and can
+  ///     therefore not be sent.
+  ///   - [ReceivePort]
+  ///   - [DynamicLibrary]
+  ///   - [Pointer]
+  ///   - [UserTag]
+  ///   - `MirrorReference`
+  ///
+  /// Apart from those exceptions any object can be sent. Objects that are
+  /// identified as immutable (e.g. strings) will be shared whereas all other
+  /// objects will be copied.
+  ///
+  /// The send happens immediately and may have a linear time cost to copy the
+  /// transtive object graph. The send itself doesn't block (i.e. doesn't wait
+  /// until the receiver has received the message). 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.
+  ///
+  /// Note: Due to an implementation choice the Dart VM made for how closures
+  /// represent captured state, closures can currently capture more state than
+  /// they need, which can cause the transitive closure to be larger than
+  /// needed. Open bug to address this: http://dartbug.com/36983
   void send(Object? message);
 
   /// Tests whether [other] is a [SendPort] pointing to the same