11320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Copyright 2014 The Chromium Authors. All rights reserved. 21320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Use of this source code is governed by a BSD-style license that can be 31320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// found in the LICENSE file. 41320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 51320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#ifndef MOJO_SYSTEM_CHANNEL_ENDPOINT_H_ 61320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#define MOJO_SYSTEM_CHANNEL_ENDPOINT_H_ 71320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 81320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#include "base/macros.h" 91320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#include "base/memory/ref_counted.h" 101320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#include "base/memory/scoped_ptr.h" 111320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#include "base/synchronization/lock.h" 121320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#include "mojo/system/message_in_transit.h" 131320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#include "mojo/system/message_in_transit_queue.h" 141320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#include "mojo/system/system_impl_export.h" 151320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 161320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tuccinamespace mojo { 171320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tuccinamespace system { 181320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 191320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucciclass Channel; 201320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucciclass MessagePipe; 211320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 221320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// TODO(vtl): The plan: 231320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - (Done.) Move |Channel::Endpoint| to |ChannelEndpoint|. Make it 241320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// refcounted, and not copyable. Make |Channel| a friend. Make things work. 251320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - (Done.) Give |ChannelEndpoint| a lock. The lock order (in order of 261320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// allowable acquisition) is: |MessagePipe|, |ChannelEndpoint|, |Channel|. 271320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - Stop having |Channel| as a friend. 281320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - Move logic from |ProxyMessagePipeEndpoint| into |ChannelEndpoint|. Right 291320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// now, we have to go through lots of contortions to manipulate state owned 301320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// by |ProxyMessagePipeEndpoint| (in particular, |Channel::Endpoint| doesn't 311320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// know about the remote ID; the local ID is duplicated in two places). 321320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Hollow out |ProxyMessagePipeEndpoint|, and have it just own a reference 331320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// to |ChannelEndpoint| (hence the refcounting). 341320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - In essence, |ChannelEndpoint| becomes the thing that knows about 351320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// channel-specific aspects of an endpoint (notably local and remote IDs, 361320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// and knowledge about handshaking), and mediates between the |Channel| and 371320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// the |MessagePipe|. 381320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - In the end state, |Channel| should no longer need to know about 391320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// |MessagePipe| and ports (but only |ChannelEndpoint|) and 401320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// |ProxyMessagePipeEndpoint| should no longer need to know about |Channel| 411320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// (ditto). 421320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// 431320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Things as they are now, before I change everything (TODO(vtl): update this 441320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// comment appropriately): 451320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// 461320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// Terminology: 471320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - "Message pipe endpoint": In the implementation, a |MessagePipe| owns 481320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// two |MessagePipeEndpoint| objects, one for each port. The 491320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// |MessagePipeEndpoint| objects are only accessed via the |MessagePipe| 501320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// (which has the lock), with the additional information of the port 511320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// number. So as far as the channel is concerned, a message pipe endpoint 521320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// is a pointer to a |MessagePipe| together with the port number. 531320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - The value of |port| in |EndpointInfo| refers to the 541320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// |ProxyMessagePipeEndpoint| (i.e., the endpoint that is logically on 551320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// the other side). Messages received by a channel for a message pipe 561320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// are thus written to the *peer* of this port. 571320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - "Attached"/"detached": A message pipe endpoint is attached to a channel 581320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// if it has a pointer to it. It must be detached before the channel gives 591320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// up its pointer to it in order to break a reference cycle. (This cycle 601320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// is needed to allow a channel to be shut down cleanly, without shutting 611320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// down everything else first.) 621320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - "Running" (message pipe endpoint): A message pipe endpoint is running 631320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// if messages written to it (via some |MessagePipeDispatcher|, to which 641320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// some |MojoHandle| is assigned) are being transmitted through the 651320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// channel. 661320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - Before a message pipe endpoint is run, it will queue messages. 671320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - When a message pipe endpoint is detached from a channel, it is also 681320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// taken out of the running state. After that point, messages should 691320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// no longer be written to it. 701320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - "Normal" message pipe endpoint (state): The channel itself does not 711320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// have knowledge of whether a message pipe endpoint has started running 721320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// yet. It will *receive* messages for a message pipe in either state (but 731320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// the message pipe endpoint won't *send* messages to the channel if it 741320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// has not started running). 751320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - "Zombie" message pipe endpoint (state): A message pipe endpoint is a 761320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// zombie if it is still in |local_id_to_endpoint_info_map_|, but the 771320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// channel is no longer forwarding messages to it (even if it may still be 781320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// receiving messages for it). 791320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - There are various types of zombies, depending on the reason the 801320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// message pipe endpoint cannot yet be removed. 811320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - If the remote side is closed, it will send a "remove" control 821320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// message. After the channel receives that message (to which it 831320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// responds with a "remove ack" control message), it knows that it 841320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// shouldn't receive any more messages for that message pipe endpoint 851320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// (local ID), but it must wait for the endpoint to detach. (It can't 861320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// do so without a race, since it can't call into the message pipe 871320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// under |lock_|.) [TODO(vtl): When I add remotely-allocated IDs, 881320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// we'll have to remove the |EndpointInfo| from 891320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// |local_id_to_endpoint_info_map_| -- i.e., remove the local ID, 901320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// since it's no longer valid and may be reused by the remote side -- 911320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// and keep the |EndpointInfo| alive in some other way.] 921320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - If the local side is closed and the message pipe endpoint was 931320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// already running (so there are no queued messages left to send), it 941320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// will detach the endpoint, and send a "remove" control message. 951320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// However, the channel may still receive messages for that endpoint 961320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// until it receives a "remove ack" control message. 971320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - If the local side is closed but the message pipe endpoint was not 981320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// yet running , the detaching is delayed until after it is run and 991320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// all the queued messages are sent to the channel. On being detached, 1001320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// things proceed as in one of the above cases. The endpoint is *not* 1011320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// a zombie until it is detached (or a "remove" message is received). 1021320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// [TODO(vtl): Maybe we can get rid of this case? It'd only not yet be 1031320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// running since under the current scheme it wouldn't have a remote ID 1041320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// yet.] 1051320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// - Note that even if the local side is closed, it may still receive a 1061320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// "remove" message from the other side (if the other side is closed 1071320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// simultaneously, and both sides send "remove" messages). In that 1081320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// case, it must still remain alive until it receives the "remove 1091320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci// ack" (and it must ack the "remove" message that it received). 1101320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucciclass MOJO_SYSTEM_IMPL_EXPORT ChannelEndpoint 1111320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci : public base::RefCountedThreadSafe<ChannelEndpoint> { 1121320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci public: 1131320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // TODO(vtl): More comments.... 1141320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci ChannelEndpoint(MessagePipe* message_pipe, unsigned port); 1151320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1161320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Takes messages from the given |MessageInTransitQueue|. This must be called 1171320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // before this object is attached to a channel, and before anyone has a chance 1181320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // to enqueue any messages. 1191320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci void TakeMessages(MessageInTransitQueue* message_queue); 1201320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1211320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Methods called by |MessagePipe| (via |ProxyMessagePipeEndpoint|): 1221320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1231320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // TODO(vtl): This currently only works if we're "running". We'll move the 1241320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // "paused message queue" here (will this be needed when we have 1251320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // locally-allocated remote IDs?). 1261320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci bool EnqueueMessage(scoped_ptr<MessageInTransit> message); 1271320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1281320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci void DetachFromMessagePipe(); 1291320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1301320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Methods called by |Channel|: 1311320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1321320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Called by |Channel| when it takes a reference to this object. 1331320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci void AttachToChannel(Channel* channel, MessageInTransit::EndpointId local_id); 1341320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1351320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // TODO(vtl): Combine this with |AttachToChannel()|. 1361320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci void Run(MessageInTransit::EndpointId remote_id); 1371320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1381320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Called by |Channel| before it gives up its reference to this object. 1391320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci void DetachFromChannel(); 1401320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1411320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci private: 1421320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci enum State { 1431320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Attached, possibly running or not. 1441320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci STATE_NORMAL, 1451320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // "Zombie" states: 1461320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Waiting for |DetachMessagePipeEndpoint()| before removing. 1471320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci STATE_WAIT_LOCAL_DETACH, 1481320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Waiting for a |kSubtypeChannelRemoveMessagePipeEndpointAck| before 1491320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // removing. 1501320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci STATE_WAIT_REMOTE_REMOVE_ACK, 1511320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci }; 1521320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1531320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // TODO(vtl): This is totally temporary, until this becomes a proper 1541320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // self-contained class. See the plan above. 1551320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci friend class Channel; 1561320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1571320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci friend class base::RefCountedThreadSafe<ChannelEndpoint>; 1581320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci ~ChannelEndpoint(); 1591320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1601320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Must be called with |lock_| held. 1611320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci bool WriteMessageNoLock(scoped_ptr<MessageInTransit> message); 1621320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1631320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // TODO(vtl): Move these under lock. 1641320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci State state_; 1651320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // TODO(vtl): When moved under lock, this can/should be made a raw pointer. 1661320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci scoped_refptr<MessagePipe> message_pipe_; 1671320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci unsigned port_; 1681320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1691320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // TODO(vtl): Move the things above under lock. 1701320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // Protects the members below. 1711320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci base::Lock lock_; 1721320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1731320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // |channel_| must be alive whenever this is non-null. Before the |channel_| 1741320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // gives up its reference to this object, it will call |DetachFromChannel()|. 1751320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci Channel* channel_; 1761320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci MessageInTransit::EndpointId local_id_; 1771320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci MessageInTransit::EndpointId remote_id_; 1781320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1791320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // This queue is used before we're running on a channel and ready to send 1801320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci // messages. 1811320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci MessageInTransitQueue paused_message_queue_; 1821320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1831320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci DISALLOW_COPY_AND_ASSIGN(ChannelEndpoint); 1841320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci}; 1851320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1861320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci} // namespace system 1871320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci} // namespace mojo 1881320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci 1891320f92c476a1ad9d19dba2a48c72b75566198e9Primiano Tucci#endif // MOJO_SYSTEM_CHANNEL_ENDPOINT_H_ 190