1 // Copyright 2013 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_H_ 6 #define MOJO_SYSTEM_CHANNEL_H_ 7 8 #include <stdint.h> 9 10 #include "base/basictypes.h" 11 #include "base/compiler_specific.h" 12 #include "base/containers/hash_tables.h" 13 #include "base/memory/ref_counted.h" 14 #include "base/memory/scoped_ptr.h" 15 #include "base/strings/string_piece.h" 16 #include "base/synchronization/lock.h" 17 #include "base/threading/thread_checker.h" 18 #include "mojo/public/system/core.h" 19 #include "mojo/system/message_in_transit.h" 20 #include "mojo/system/message_pipe.h" 21 #include "mojo/system/raw_channel.h" 22 #include "mojo/system/system_impl_export.h" 23 24 namespace base { 25 class MessageLoop; 26 } 27 28 namespace mojo { 29 namespace system { 30 31 // This class is mostly thread-safe. It must be created on an "I/O thread" (see 32 // raw_channel.h). |Init()| must be called on that same thread before it becomes 33 // thread-safe (in particular, before references are given to any other thread) 34 // and |Shutdown()| must be called on that same thread before destruction. Its 35 // public methods are otherwise thread-safe. It may be destroyed on any thread, 36 // in the sense that the last reference to it may be released on any thread, 37 // with the proviso that |Shutdown()| must have been called first (so the 38 // pattern is that a "main" reference is kept on its creation thread and is 39 // released after |Shutdown()| is called, but other threads may have temporarily 40 // "dangling" references). 41 // 42 // Note that |MessagePipe| calls into |Channel| and the former's |lock_| must be 43 // acquired before the latter's. When |Channel| wants to call into a 44 // |MessagePipe|, it must obtain a reference to the |MessagePipe| (from 45 // |local_id_to_endpoint_info_map_|) under |Channel::lock_| and then release the 46 // lock. 47 // 48 // Also, care must be taken with respect to references: While a |Channel| has 49 // references to |MessagePipe|s, |MessagePipe|s (via |ProxyMessagePipeEndpoint|) 50 // may also have references to |Channel|s. These references are set up by 51 // calling |AttachMessagePipeEndpoint()|. The reference to |MessagePipe| owned 52 // by |Channel| must be removed by calling |DetachMessagePipeEndpoint()| (which 53 // is done by |MessagePipe|/|ProxyMessagePipeEndpoint|, which simultaneously 54 // removes its reference to |Channel|). 55 class MOJO_SYSTEM_IMPL_EXPORT Channel 56 : public base::RefCountedThreadSafe<Channel>, 57 public RawChannel::Delegate { 58 public: 59 // The first message pipe endpoint attached will have this as its local ID. 60 static const MessageInTransit::EndpointId kBootstrapEndpointId = 1; 61 62 Channel(); 63 64 // This must be called on the creation thread before any other methods are 65 // called, and before references to this object are given to any other 66 // threads. Takes ownership of |handle|. Returns true on success. On failure, 67 // no other methods should be called (including |Shutdown()|). 68 bool Init(const PlatformChannelHandle& handle); 69 70 // This must be called on the creation thread before destruction (which can 71 // happen on any thread). 72 void Shutdown(); 73 74 // Attaches the given message pipe/port's endpoint (which must be a 75 // |ProxyMessagePipeEndpoint|) to this channel. This assigns it a local ID, 76 // which it returns. The first message pipe endpoint attached will always have 77 // |kBootstrapEndpointId| as its local ID. (For bootstrapping, this occurs on 78 // both sides, so one should use |kBootstrapEndpointId| for the remote ID for 79 // the first message pipe across a channel.) 80 MessageInTransit::EndpointId AttachMessagePipeEndpoint( 81 scoped_refptr<MessagePipe> message_pipe, unsigned port); 82 void RunMessagePipeEndpoint(MessageInTransit::EndpointId local_id, 83 MessageInTransit::EndpointId remote_id); 84 85 // This forwards |message| verbatim to |raw_channel_|. 86 bool WriteMessage(MessageInTransit* message); 87 88 // This removes the message pipe/port's endpoint (with the given local ID, 89 // returned by |AttachMessagePipeEndpoint()| from this channel. After this is 90 // called, |local_id| may be reused for another message pipe. 91 void DetachMessagePipeEndpoint(MessageInTransit::EndpointId local_id); 92 93 private: 94 friend class base::RefCountedThreadSafe<Channel>; 95 virtual ~Channel(); 96 97 // |RawChannel::Delegate| implementation: 98 virtual void OnReadMessage(const MessageInTransit& message) OVERRIDE; 99 virtual void OnFatalError(FatalError fatal_error) OVERRIDE; 100 101 // Helpers for |OnReadMessage|: 102 void OnReadMessageForDownstream(const MessageInTransit& message); 103 void OnReadMessageForChannel(const MessageInTransit& message); 104 105 // Handles errors (e.g., invalid messages) from the remote side. 106 void HandleRemoteError(const base::StringPiece& error_message); 107 // Handles internal errors/failures from the local side. 108 void HandleLocalError(const base::StringPiece& error_message); 109 110 struct EndpointInfo { 111 EndpointInfo(); 112 EndpointInfo(scoped_refptr<MessagePipe> message_pipe, unsigned port); 113 ~EndpointInfo(); 114 115 scoped_refptr<MessagePipe> message_pipe; 116 unsigned port; 117 }; 118 119 base::ThreadChecker creation_thread_checker_; 120 121 // Note: |MessagePipe|s MUST NOT be used under |lock_|. I.e., |lock_| can only 122 // be acquired after |MessagePipe::lock_|, never before. Thus to call into a 123 // |MessagePipe|, a reference should be acquired from 124 // |local_id_to_endpoint_info_map_| under |lock_| (e.g., by copying the 125 // |EndpointInfo|) and then the lock released. 126 base::Lock lock_; // Protects the members below. 127 128 scoped_ptr<RawChannel> raw_channel_; 129 130 typedef base::hash_map<MessageInTransit::EndpointId, EndpointInfo> 131 IdToEndpointInfoMap; 132 IdToEndpointInfoMap local_id_to_endpoint_info_map_; 133 // The next local ID to try (when allocating new local IDs). Note: It should 134 // be checked for existence before use. 135 MessageInTransit::EndpointId next_local_id_; 136 137 DISALLOW_COPY_AND_ASSIGN(Channel); 138 }; 139 140 } // namespace system 141 } // namespace mojo 142 143 #endif // MOJO_SYSTEM_CHANNEL_H_ 144