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/compiler_specific.h" 11 #include "base/containers/hash_tables.h" 12 #include "base/macros.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/embedder/scoped_platform_handle.h" 19 #include "mojo/public/c/system/types.h" 20 #include "mojo/system/channel_endpoint.h" 21 #include "mojo/system/message_in_transit.h" 22 #include "mojo/system/message_pipe.h" 23 #include "mojo/system/raw_channel.h" 24 #include "mojo/system/system_impl_export.h" 25 26 namespace mojo { 27 28 namespace embedder { 29 class PlatformSupport; 30 } 31 32 namespace system { 33 34 class ChannelEndpoint; 35 36 // This class is mostly thread-safe. It must be created on an I/O thread. 37 // |Init()| must be called on that same thread before it becomes thread-safe (in 38 // particular, before references are given to any other thread) and |Shutdown()| 39 // must be called on that same thread before destruction. Its public methods are 40 // otherwise thread-safe. (Many private methods are restricted to the creation 41 // thread.) It may be destroyed on any thread, in the sense that the last 42 // reference to it may be released on any thread, with the proviso that 43 // |Shutdown()| must have been called first (so the pattern is that a "main" 44 // reference is kept on its creation thread and is released after |Shutdown()| 45 // is called, but other threads may have temporarily "dangling" references). 46 // 47 // Note the lock order (in order of allowable acquisition): |MessagePipe|, 48 // |ChannelEndpoint|, |Channel|. Thus |Channel| may not call into 49 // |ChannelEndpoint| with |Channel|'s lock held. 50 class MOJO_SYSTEM_IMPL_EXPORT Channel 51 : public base::RefCountedThreadSafe<Channel>, 52 public RawChannel::Delegate { 53 public: 54 // The first message pipe endpoint attached will have this as its local ID. 55 static const MessageInTransit::EndpointId kBootstrapEndpointId = 1; 56 57 // |platform_support| (typically owned by |Core|) must remain alive until 58 // after |Shutdown()| is called. 59 explicit Channel(embedder::PlatformSupport* platform_support); 60 61 // This must be called on the creation thread before any other methods are 62 // called, and before references to this object are given to any other 63 // threads. |raw_channel| should be uninitialized. Returns true on success. On 64 // failure, no other methods should be called (including |Shutdown()|). 65 bool Init(scoped_ptr<RawChannel> raw_channel); 66 67 // This must be called on the creation thread before destruction (which can 68 // happen on any thread). 69 void Shutdown(); 70 71 // Signals that |Shutdown()| will be called soon (this may be called from any 72 // thread, unlike |Shutdown()|). Warnings will be issued if, e.g., messages 73 // are written after this is called; other warnings may be suppressed. (This 74 // may be called multiple times, or not at all.) 75 void WillShutdownSoon(); 76 77 // Attaches the given endpoint to this channel. This assigns it a local ID, 78 // which it returns. The first endpoint attached will always have 79 // |kBootstrapEndpointId| as its local ID. (For bootstrapping, this occurs on 80 // both sides, so one should use |kBootstrapEndpointId| for the remote ID for 81 // the first message pipe across a channel.) Returns |kInvalidEndpointId| on 82 // failure. 83 // TODO(vtl): This should be combined with "run", and it should take a 84 // |ChannelEndpoint| instead. 85 // TODO(vtl): Maybe limit the number of attached message pipes. 86 MessageInTransit::EndpointId AttachEndpoint( 87 scoped_refptr<ChannelEndpoint> endpoint); 88 89 // Runs the message pipe with the given |local_id| (previously attached), with 90 // the given |remote_id| (negotiated using some other means, e.g., over an 91 // existing message pipe; see comments above for the bootstrap case). Returns 92 // false on failure, in particular if no message pipe with |local_id| is 93 // attached. 94 bool RunMessagePipeEndpoint(MessageInTransit::EndpointId local_id, 95 MessageInTransit::EndpointId remote_id); 96 97 // Tells the other side of the channel to run a message pipe endpoint (which 98 // must already be attached); |local_id| and |remote_id| are relative to this 99 // channel (i.e., |local_id| is the other side's remote ID and |remote_id| is 100 // its local ID). 101 // TODO(vtl): Maybe we should just have a flag argument to 102 // |RunMessagePipeEndpoint()| that tells it to do this. 103 void RunRemoteMessagePipeEndpoint(MessageInTransit::EndpointId local_id, 104 MessageInTransit::EndpointId remote_id); 105 106 // This forwards |message| verbatim to |raw_channel_|. 107 bool WriteMessage(scoped_ptr<MessageInTransit> message); 108 109 // See |RawChannel::IsWriteBufferEmpty()|. 110 // TODO(vtl): Maybe we shouldn't expose this, and instead have a 111 // |FlushWriteBufferAndShutdown()| or something like that. 112 bool IsWriteBufferEmpty(); 113 114 // This removes the message pipe/port's endpoint (with the given local ID and 115 // given remote ID, which should be |kInvalidEndpointId| if not yet running), 116 // returned by |AttachEndpoint()| from this channel. After this is called, 117 // |local_id| may be reused for another message pipe. 118 void DetachMessagePipeEndpoint(MessageInTransit::EndpointId local_id, 119 MessageInTransit::EndpointId remote_id); 120 121 // See |RawChannel::GetSerializedPlatformHandleSize()|. 122 size_t GetSerializedPlatformHandleSize() const; 123 124 embedder::PlatformSupport* platform_support() const { 125 return platform_support_; 126 } 127 128 private: 129 friend class base::RefCountedThreadSafe<Channel>; 130 virtual ~Channel(); 131 132 // |RawChannel::Delegate| implementation (only called on the creation thread): 133 virtual void OnReadMessage( 134 const MessageInTransit::View& message_view, 135 embedder::ScopedPlatformHandleVectorPtr platform_handles) OVERRIDE; 136 virtual void OnError(Error error) OVERRIDE; 137 138 // Helpers for |OnReadMessage| (only called on the creation thread): 139 void OnReadMessageForDownstream( 140 const MessageInTransit::View& message_view, 141 embedder::ScopedPlatformHandleVectorPtr platform_handles); 142 void OnReadMessageForChannel( 143 const MessageInTransit::View& message_view, 144 embedder::ScopedPlatformHandleVectorPtr platform_handles); 145 146 // Removes the message pipe endpoint with the given local ID, which must exist 147 // and be a zombie, and given remote ID. Returns false on failure, in 148 // particular if no message pipe with |local_id| is attached. Only called on 149 // the creation thread. 150 bool RemoveMessagePipeEndpoint(MessageInTransit::EndpointId local_id, 151 MessageInTransit::EndpointId remote_id); 152 153 // Handles errors (e.g., invalid messages) from the remote side. Callable from 154 // any thread. 155 void HandleRemoteError(const base::StringPiece& error_message); 156 // Handles internal errors/failures from the local side. Callable from any 157 // thread. 158 void HandleLocalError(const base::StringPiece& error_message); 159 160 // Helper to send channel control messages. Returns true on success. Should be 161 // called *without* |lock_| held. Callable from any thread. 162 bool SendControlMessage(MessageInTransit::Subtype subtype, 163 MessageInTransit::EndpointId source_id, 164 MessageInTransit::EndpointId destination_id); 165 166 base::ThreadChecker creation_thread_checker_; 167 168 embedder::PlatformSupport* const platform_support_; 169 170 // Note: |MessagePipe|s MUST NOT be used under |lock_|. I.e., |lock_| can only 171 // be acquired after |MessagePipe::lock_|, never before. Thus to call into a 172 // |MessagePipe|, a reference to the |MessagePipe| should be acquired from 173 // |local_id_to_endpoint_map_| under |lock_| and then the lock released. 174 base::Lock lock_; // Protects the members below. 175 176 scoped_ptr<RawChannel> raw_channel_; 177 bool is_running_; 178 // Set when |WillShutdownSoon()| is called. 179 bool is_shutting_down_; 180 181 typedef base::hash_map<MessageInTransit::EndpointId, 182 scoped_refptr<ChannelEndpoint>> IdToEndpointMap; 183 IdToEndpointMap local_id_to_endpoint_map_; 184 // The next local ID to try (when allocating new local IDs). Note: It should 185 // be checked for existence before use. 186 MessageInTransit::EndpointId next_local_id_; 187 188 DISALLOW_COPY_AND_ASSIGN(Channel); 189 }; 190 191 } // namespace system 192 } // namespace mojo 193 194 #endif // MOJO_SYSTEM_CHANNEL_H_ 195
