Mojo AssociatedRemote: clarify when it is callable.

BUG=None

Change-Id: I5297415b0c5b9c658743e9842ede3fe16efde51f
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/5431567
Reviewed-by: Daniel Cheng <dcheng@chromium.org>
Commit-Queue: Yuzhu Shen <yzshen@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1284054}

mojo/public/cpp/bindings/associated_remote.h

@@ -78,6 +78,9 @@ class AssociatedRemote {
   // Exposes access to callable Interface methods directed at this
   // AssociatedRemote's receiver. Must only be called on a bound
   // AssociatedRemote.
+  //
+  // Please also see comments of |is_bound()| about when it is safe to make
+  // calls using the returned pointer.
   typename Interface::Proxy_* get() const {
     DCHECK(is_bound())
         << "Cannot issue Interface method calls on an unbound AssociatedRemote";
@@ -88,15 +91,25 @@ class AssociatedRemote {
   typename Interface::Proxy_* operator->() const { return get(); }
   typename Interface::Proxy_& operator*() const { return *get(); }
 
-  // Indicates whether this AssociatedRemote is bound and thus can issue
-  // Interface method calls via the above accessors.
+  // Indicates whether this AssociatedRemote is bound.
   //
-  // NOTE: The state of being "bound" should not be confused with the state of
+  // NOTE:
+  // 1) The state of being "bound" should not be confused with the state of
   // being "connected" (see |is_connected()| below). An AssociatedRemote is
   // NEVER passively unbound and the only way for it to become unbound is to
   // explicitly call |reset()| or |Unbind()|. As such, unless you make explicit
   // calls to those methods, it is always safe to assume that an
-  // AssociatedRemote you've bound will remain bound and callable.
+  // AssociatedRemote you've bound will remain bound.
+  //
+  // 2) The state of being "bound" is a necessary but not sufficient condition
+  // for Interface methods to be callable. For them to be callable, the
+  // AssociatedRemote must also be "associated", which means either one of
+  // the following cases:
+  //   2-1) Either itself or its entangled AssociatedReceiver must be sent over
+  //   a Remote/Receiver pair or an already-established
+  //   AssociatedRemote/AssociatedReceiver pair.
+  //   2-2) It is bound with a dedicated message pipe. Please see comments of
+  //   BindNewEndpointAndPassDedicatedReceiver().
   bool is_bound() const { return internal_state_.is_bound(); }
   explicit operator bool() const { return is_bound(); }
 

mojo/public/cpp/bindings/lib/interface_endpoint_client.cc

@@ -582,7 +582,14 @@ bool InterfaceEndpointClient::SendMessage(Message* message,
                                           bool is_control_message) {
   CHECK(sequence_checker_.CalledOnValidSequence());
   DCHECK(!message->has_flag(Message::kFlagExpectsResponse));
-  DCHECK(!handle_.pending_association());
+
+  CHECK(!handle_.pending_association())
+      << "Cannot send a message when the endpoint hasn't been associated with "
+         "a message pipe. This failure typically happens when attempting to "
+         "make a call with an AssociatedRemote before one of the endpoints "
+         "(either the AssociatedRemote itself or its entangled "
+         "AssociatedReceiver) is sent over a Remote/Receiver pair or an "
+         "already-established AssociatedRemote/AssociatedReceiver pair.";
 
   // This has to been done even if connection error has occurred. For example,
   // the message contains a pending associated request. The user may try to use