Mojo: Remove Channel::AttachMessagePipeEndpoint().

mojo/system/channel.h

 // Copyright 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #ifndef MOJO_SYSTEM_CHANNEL_H_
 #define MOJO_SYSTEM_CHANNEL_H_
 
 #include <stdint.h>
 
 #include "base/compiler_specific.h"
@@ skipping 26 matching lines @@
 // |Init()| must be called on that same thread before it becomes thread-safe (in
 // particular, before references are given to any other thread) and |Shutdown()|
 // must be called on that same thread before destruction. Its public methods are
 // otherwise thread-safe. (Many private methods are restricted to the creation
 // thread.) It may be destroyed on any thread, in the sense that the last
 // reference to it may be released on any thread, with the proviso that
 // |Shutdown()| must have been called first (so the pattern is that a "main"
 // reference is kept on its creation thread and is released after |Shutdown()|
 // is called, but other threads may have temporarily "dangling" references).
 //
-// Note that |MessagePipe| calls into |Channel| and the former's |lock_| must be
-// acquired before the latter's. When |Channel| wants to call into a
-// |MessagePipe|, it must obtain a reference to the |MessagePipe| (from
-// |local_id_to_endpoint_info_map_|) under |Channel::lock_| and then release the
-// lock.
-//
-// Also, care must be taken with respect to references: While a |Channel| has
-// references to |MessagePipe|s, |MessagePipe|s (via |ProxyMessagePipeEndpoint|)
-// may also have references to |Channel|s. These references are set up by
-// calling |AttachMessagePipeEndpoint()|. The reference to |MessagePipe| owned
-// by |Channel| must be removed by calling |DetachMessagePipeEndpoint()| (which
-// is done by |MessagePipe|/|ProxyMessagePipeEndpoint|, which simultaneously
-// removes its reference to |Channel|).
+// Note the lock order (in order of allowable acquisition): |MessagePipe|,
+// |ChannelEndpoint|, |Channel|. Thus |Channel| may not call into
+// |ChannelEndpoint| with |Channel|'s lock held.
 class MOJO_SYSTEM_IMPL_EXPORT Channel
     : public base::RefCountedThreadSafe<Channel>,
       public RawChannel::Delegate {
  public:
   // The first message pipe endpoint attached will have this as its local ID.
   static const MessageInTransit::EndpointId kBootstrapEndpointId = 1;
 
   // |platform_support| (typically owned by |Core|) must remain alive until
   // after |Shutdown()| is called.
   explicit Channel(embedder::PlatformSupport* platform_support);
 
   // This must be called on the creation thread before any other methods are
   // called, and before references to this object are given to any other
   // threads. |raw_channel| should be uninitialized. Returns true on success. On
   // failure, no other methods should be called (including |Shutdown()|).
   bool Init(scoped_ptr<RawChannel> raw_channel);
 
   // This must be called on the creation thread before destruction (which can
   // happen on any thread).
   void Shutdown();
 
   // Signals that |Shutdown()| will be called soon (this may be called from any
   // thread, unlike |Shutdown()|). Warnings will be issued if, e.g., messages
   // are written after this is called; other warnings may be suppressed. (This
   // may be called multiple times, or not at all.)
   void WillShutdownSoon();
 
-  // TODO(vtl): Write comment here.
-  MessageInTransit::EndpointId AttachEndpoint(
-      scoped_refptr<ChannelEndpoint> endpoint);
-
-  // TODO(vtl): Remove this version.
-  // Attaches the given message pipe/port's endpoint (which must be a
-  // |ProxyMessagePipeEndpoint|) to this channel. This assigns it a local ID,
-  // which it returns. The first message pipe endpoint attached will always have
+  // Attaches the given endpoint to this channel. This assigns it a local ID,
+  // which it returns. The first endpoint attached will always have
   // |kBootstrapEndpointId| as its local ID. (For bootstrapping, this occurs on
   // both sides, so one should use |kBootstrapEndpointId| for the remote ID for
   // the first message pipe across a channel.) Returns |kInvalidEndpointId| on
   // failure.
   // TODO(vtl): This should be combined with "run", and it should take a
   // |ChannelEndpoint| instead.
   // TODO(vtl): Maybe limit the number of attached message pipes.
-  MessageInTransit::EndpointId AttachMessagePipeEndpoint(
-      scoped_refptr<MessagePipe> message_pipe,
-      unsigned port);
+  MessageInTransit::EndpointId AttachEndpoint(
+      scoped_refptr<ChannelEndpoint> endpoint);
 
   // Runs the message pipe with the given |local_id| (previously attached), with
   // the given |remote_id| (negotiated using some other means, e.g., over an
   // existing message pipe; see comments above for the bootstrap case). Returns
   // false on failure, in particular if no message pipe with |local_id| is
   // attached.
   bool RunMessagePipeEndpoint(MessageInTransit::EndpointId local_id,
                               MessageInTransit::EndpointId remote_id);
 
   // Tells the other side of the channel to run a message pipe endpoint (which
   // must already be attached); |local_id| and |remote_id| are relative to this
   // channel (i.e., |local_id| is the other side's remote ID and |remote_id| is
   // its local ID).
   // TODO(vtl): Maybe we should just have a flag argument to
   // |RunMessagePipeEndpoint()| that tells it to do this.
   void RunRemoteMessagePipeEndpoint(MessageInTransit::EndpointId local_id,
                                     MessageInTransit::EndpointId remote_id);
 
   // This forwards |message| verbatim to |raw_channel_|.
   bool WriteMessage(scoped_ptr<MessageInTransit> message);
 
   // See |RawChannel::IsWriteBufferEmpty()|.
   // TODO(vtl): Maybe we shouldn't expose this, and instead have a
   // |FlushWriteBufferAndShutdown()| or something like that.
   bool IsWriteBufferEmpty();
 
   // This removes the message pipe/port's endpoint (with the given local ID and
   // given remote ID, which should be |kInvalidEndpointId| if not yet running),
-  // returned by |AttachMessagePipeEndpoint()| from this channel. After this is
-  // called, |local_id| may be reused for another message pipe.
+  // returned by |AttachEndpoint()| from this channel. After this is called,
+  // |local_id| may be reused for another message pipe.
   void DetachMessagePipeEndpoint(MessageInTransit::EndpointId local_id,
                                  MessageInTransit::EndpointId remote_id);
 
   // See |RawChannel::GetSerializedPlatformHandleSize()|.
   size_t GetSerializedPlatformHandleSize() const;
 
   embedder::PlatformSupport* platform_support() const {
     return platform_support_;
   }
 
@@ skipping 57 matching lines @@
   // be checked for existence before use.
   MessageInTransit::EndpointId next_local_id_;
 
   DISALLOW_COPY_AND_ASSIGN(Channel);
 };
 
 }  // namespace system
 }  // namespace mojo
 
 #endif  // MOJO_SYSTEM_CHANNEL_H_