1 // Copyright 2014 The Chromium Authors. All rights reserved. 2 // Use of this source code is governed by a BSD-style license that can be 3 // found in the LICENSE file. 4 5 #ifndef MOJO_SYSTEM_CHANNEL_ENDPOINT_H_ 6 #define MOJO_SYSTEM_CHANNEL_ENDPOINT_H_ 7 8 #include "base/macros.h" 9 #include "base/memory/ref_counted.h" 10 #include "base/memory/scoped_ptr.h" 11 #include "base/synchronization/lock.h" 12 #include "mojo/system/message_in_transit.h" 13 #include "mojo/system/message_in_transit_queue.h" 14 #include "mojo/system/system_impl_export.h" 15 16 namespace mojo { 17 namespace system { 18 19 class Channel; 20 class MessagePipe; 21 22 // TODO(vtl): The plan: 23 // - (Done.) Move |Channel::Endpoint| to |ChannelEndpoint|. Make it 24 // refcounted, and not copyable. Make |Channel| a friend. Make things work. 25 // - (Done.) Give |ChannelEndpoint| a lock. The lock order (in order of 26 // allowable acquisition) is: |MessagePipe|, |ChannelEndpoint|, |Channel|. 27 // - Stop having |Channel| as a friend. 28 // - Move logic from |ProxyMessagePipeEndpoint| into |ChannelEndpoint|. Right 29 // now, we have to go through lots of contortions to manipulate state owned 30 // by |ProxyMessagePipeEndpoint| (in particular, |Channel::Endpoint| doesn't 31 // know about the remote ID; the local ID is duplicated in two places). 32 // Hollow out |ProxyMessagePipeEndpoint|, and have it just own a reference 33 // to |ChannelEndpoint| (hence the refcounting). 34 // - In essence, |ChannelEndpoint| becomes the thing that knows about 35 // channel-specific aspects of an endpoint (notably local and remote IDs, 36 // and knowledge about handshaking), and mediates between the |Channel| and 37 // the |MessagePipe|. 38 // - In the end state, |Channel| should no longer need to know about 39 // |MessagePipe| and ports (but only |ChannelEndpoint|) and 40 // |ProxyMessagePipeEndpoint| should no longer need to know about |Channel| 41 // (ditto). 42 // 43 // Things as they are now, before I change everything (TODO(vtl): update this 44 // comment appropriately): 45 // 46 // Terminology: 47 // - "Message pipe endpoint": In the implementation, a |MessagePipe| owns 48 // two |MessagePipeEndpoint| objects, one for each port. The 49 // |MessagePipeEndpoint| objects are only accessed via the |MessagePipe| 50 // (which has the lock), with the additional information of the port 51 // number. So as far as the channel is concerned, a message pipe endpoint 52 // is a pointer to a |MessagePipe| together with the port number. 53 // - The value of |port| in |EndpointInfo| refers to the 54 // |ProxyMessagePipeEndpoint| (i.e., the endpoint that is logically on 55 // the other side). Messages received by a channel for a message pipe 56 // are thus written to the *peer* of this port. 57 // - "Attached"/"detached": A message pipe endpoint is attached to a channel 58 // if it has a pointer to it. It must be detached before the channel gives 59 // up its pointer to it in order to break a reference cycle. (This cycle 60 // is needed to allow a channel to be shut down cleanly, without shutting 61 // down everything else first.) 62 // - "Running" (message pipe endpoint): A message pipe endpoint is running 63 // if messages written to it (via some |MessagePipeDispatcher|, to which 64 // some |MojoHandle| is assigned) are being transmitted through the 65 // channel. 66 // - Before a message pipe endpoint is run, it will queue messages. 67 // - When a message pipe endpoint is detached from a channel, it is also 68 // taken out of the running state. After that point, messages should 69 // no longer be written to it. 70 // - "Normal" message pipe endpoint (state): The channel itself does not 71 // have knowledge of whether a message pipe endpoint has started running 72 // yet. It will *receive* messages for a message pipe in either state (but 73 // the message pipe endpoint won't *send* messages to the channel if it 74 // has not started running). 75 // - "Zombie" message pipe endpoint (state): A message pipe endpoint is a 76 // zombie if it is still in |local_id_to_endpoint_info_map_|, but the 77 // channel is no longer forwarding messages to it (even if it may still be 78 // receiving messages for it). 79 // - There are various types of zombies, depending on the reason the 80 // message pipe endpoint cannot yet be removed. 81 // - If the remote side is closed, it will send a "remove" control 82 // message. After the channel receives that message (to which it 83 // responds with a "remove ack" control message), it knows that it 84 // shouldn't receive any more messages for that message pipe endpoint 85 // (local ID), but it must wait for the endpoint to detach. (It can't 86 // do so without a race, since it can't call into the message pipe 87 // under |lock_|.) [TODO(vtl): When I add remotely-allocated IDs, 88 // we'll have to remove the |EndpointInfo| from 89 // |local_id_to_endpoint_info_map_| -- i.e., remove the local ID, 90 // since it's no longer valid and may be reused by the remote side -- 91 // and keep the |EndpointInfo| alive in some other way.] 92 // - If the local side is closed and the message pipe endpoint was 93 // already running (so there are no queued messages left to send), it 94 // will detach the endpoint, and send a "remove" control message. 95 // However, the channel may still receive messages for that endpoint 96 // until it receives a "remove ack" control message. 97 // - If the local side is closed but the message pipe endpoint was not 98 // yet running , the detaching is delayed until after it is run and 99 // all the queued messages are sent to the channel. On being detached, 100 // things proceed as in one of the above cases. The endpoint is *not* 101 // a zombie until it is detached (or a "remove" message is received). 102 // [TODO(vtl): Maybe we can get rid of this case? It'd only not yet be 103 // running since under the current scheme it wouldn't have a remote ID 104 // yet.] 105 // - Note that even if the local side is closed, it may still receive a 106 // "remove" message from the other side (if the other side is closed 107 // simultaneously, and both sides send "remove" messages). In that 108 // case, it must still remain alive until it receives the "remove 109 // ack" (and it must ack the "remove" message that it received). 110 class MOJO_SYSTEM_IMPL_EXPORT ChannelEndpoint 111 : public base::RefCountedThreadSafe<ChannelEndpoint> { 112 public: 113 // TODO(vtl): More comments.... 114 ChannelEndpoint(MessagePipe* message_pipe, unsigned port); 115 116 // Takes messages from the given |MessageInTransitQueue|. This must be called 117 // before this object is attached to a channel, and before anyone has a chance 118 // to enqueue any messages. 119 void TakeMessages(MessageInTransitQueue* message_queue); 120 121 // Methods called by |MessagePipe| (via |ProxyMessagePipeEndpoint|): 122 123 // TODO(vtl): This currently only works if we're "running". We'll move the 124 // "paused message queue" here (will this be needed when we have 125 // locally-allocated remote IDs?). 126 bool EnqueueMessage(scoped_ptr<MessageInTransit> message); 127 128 void DetachFromMessagePipe(); 129 130 // Methods called by |Channel|: 131 132 // Called by |Channel| when it takes a reference to this object. 133 void AttachToChannel(Channel* channel, MessageInTransit::EndpointId local_id); 134 135 // TODO(vtl): Combine this with |AttachToChannel()|. 136 void Run(MessageInTransit::EndpointId remote_id); 137 138 // Called by |Channel| before it gives up its reference to this object. 139 void DetachFromChannel(); 140 141 private: 142 enum State { 143 // Attached, possibly running or not. 144 STATE_NORMAL, 145 // "Zombie" states: 146 // Waiting for |DetachMessagePipeEndpoint()| before removing. 147 STATE_WAIT_LOCAL_DETACH, 148 // Waiting for a |kSubtypeChannelRemoveMessagePipeEndpointAck| before 149 // removing. 150 STATE_WAIT_REMOTE_REMOVE_ACK, 151 }; 152 153 // TODO(vtl): This is totally temporary, until this becomes a proper 154 // self-contained class. See the plan above. 155 friend class Channel; 156 157 friend class base::RefCountedThreadSafe<ChannelEndpoint>; 158 ~ChannelEndpoint(); 159 160 // Must be called with |lock_| held. 161 bool WriteMessageNoLock(scoped_ptr<MessageInTransit> message); 162 163 // TODO(vtl): Move these under lock. 164 State state_; 165 // TODO(vtl): When moved under lock, this can/should be made a raw pointer. 166 scoped_refptr<MessagePipe> message_pipe_; 167 unsigned port_; 168 169 // TODO(vtl): Move the things above under lock. 170 // Protects the members below. 171 base::Lock lock_; 172 173 // |channel_| must be alive whenever this is non-null. Before the |channel_| 174 // gives up its reference to this object, it will call |DetachFromChannel()|. 175 Channel* channel_; 176 MessageInTransit::EndpointId local_id_; 177 MessageInTransit::EndpointId remote_id_; 178 179 // This queue is used before we're running on a channel and ready to send 180 // messages. 181 MessageInTransitQueue paused_message_queue_; 182 183 DISALLOW_COPY_AND_ASSIGN(ChannelEndpoint); 184 }; 185 186 } // namespace system 187 } // namespace mojo 188 189 #endif // MOJO_SYSTEM_CHANNEL_ENDPOINT_H_ 190
