OLD | NEW |
(Empty) | |
| 1 // Copyright (c) 2006-2008 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 IPC_IPC_CHANNEL_PROXY_H__ |
| 6 #define IPC_IPC_CHANNEL_PROXY_H__ |
| 7 |
| 8 #include <vector> |
| 9 |
| 10 #include "base/ref_counted.h" |
| 11 #include "ipc/ipc_channel.h" |
| 12 |
| 13 class MessageLoop; |
| 14 |
| 15 namespace IPC { |
| 16 |
| 17 //----------------------------------------------------------------------------- |
| 18 // IPC::ChannelProxy |
| 19 // |
| 20 // This class is a helper class that is useful when you wish to run an IPC |
| 21 // channel on a background thread. It provides you with the option of either |
| 22 // handling IPC messages on that background thread or having them dispatched to |
| 23 // your main thread (the thread on which the IPC::ChannelProxy is created). |
| 24 // |
| 25 // The API for an IPC::ChannelProxy is very similar to that of an IPC::Channel. |
| 26 // When you send a message to an IPC::ChannelProxy, the message is routed to |
| 27 // the background thread, where it is then passed to the IPC::Channel's Send |
| 28 // method. This means that you can send a message from your thread and your |
| 29 // message will be sent over the IPC channel when possible instead of being |
| 30 // delayed until your thread returns to its message loop. (Often IPC messages |
| 31 // will queue up on the IPC::Channel when there is a lot of traffic, and the |
| 32 // channel will not get cycles to flush its message queue until the thread, on |
| 33 // which it is running, returns to its message loop.) |
| 34 // |
| 35 // An IPC::ChannelProxy can have a MessageFilter associated with it, which will |
| 36 // be notified of incoming messages on the IPC::Channel's thread. This gives |
| 37 // the consumer of IPC::ChannelProxy the ability to respond to incoming |
| 38 // messages on this background thread instead of on their own thread, which may |
| 39 // be bogged down with other processing. The result can be greatly improved |
| 40 // latency for messages that can be handled on a background thread. |
| 41 // |
| 42 // The consumer of IPC::ChannelProxy is responsible for allocating the Thread |
| 43 // instance where the IPC::Channel will be created and operated. |
| 44 // |
| 45 class ChannelProxy : public Message::Sender { |
| 46 public: |
| 47 // A class that receives messages on the thread where the IPC channel is |
| 48 // running. It can choose to prevent the default action for an IPC message. |
| 49 class MessageFilter : public base::RefCountedThreadSafe<MessageFilter> { |
| 50 public: |
| 51 virtual ~MessageFilter() {} |
| 52 |
| 53 // Called on the background thread to provide the filter with access to the |
| 54 // channel. Called when the IPC channel is initialized or when AddFilter |
| 55 // is called if the channel is already initialized. |
| 56 virtual void OnFilterAdded(Channel* channel) {} |
| 57 |
| 58 // Called on the background thread when the filter has been removed from |
| 59 // the ChannelProxy and when the Channel is closing. After a filter is |
| 60 // removed, it will not be called again. |
| 61 virtual void OnFilterRemoved() {} |
| 62 |
| 63 // Called to inform the filter that the IPC channel is connected and we |
| 64 // have received the internal Hello message from the peer. |
| 65 virtual void OnChannelConnected(int32 peer_pid) {} |
| 66 |
| 67 // Called when there is an error on the channel, typically that the channel |
| 68 // has been closed. |
| 69 virtual void OnChannelError() {} |
| 70 |
| 71 // Called to inform the filter that the IPC channel will be destroyed. |
| 72 // OnFilterRemoved is called immediately after this. |
| 73 virtual void OnChannelClosing() {} |
| 74 |
| 75 // Return true to indicate that the message was handled, or false to let |
| 76 // the message be handled in the default way. |
| 77 virtual bool OnMessageReceived(const Message& message) { |
| 78 return false; |
| 79 } |
| 80 }; |
| 81 |
| 82 // Initializes a channel proxy. The channel_id and mode parameters are |
| 83 // passed directly to the underlying IPC::Channel. The listener is called on |
| 84 // the thread that creates the ChannelProxy. The filter's OnMessageReceived |
| 85 // method is called on the thread where the IPC::Channel is running. The |
| 86 // filter may be null if the consumer is not interested in handling messages |
| 87 // on the background thread. Any message not handled by the filter will be |
| 88 // dispatched to the listener. The given message loop indicates where the |
| 89 // IPC::Channel should be created. |
| 90 ChannelProxy(const std::string& channel_id, Channel::Mode mode, |
| 91 Channel::Listener* listener, MessageFilter* filter, |
| 92 MessageLoop* ipc_thread_loop); |
| 93 |
| 94 ~ChannelProxy() { |
| 95 Close(); |
| 96 } |
| 97 |
| 98 // Close the IPC::Channel. This operation completes asynchronously, once the |
| 99 // background thread processes the command to close the channel. It is ok to |
| 100 // call this method multiple times. Redundant calls are ignored. |
| 101 // |
| 102 // WARNING: The MessageFilter object held by the ChannelProxy is also |
| 103 // released asynchronously, and it may in fact have its final reference |
| 104 // released on the background thread. The caller should be careful to deal |
| 105 // with / allow for this possibility. |
| 106 void Close(); |
| 107 |
| 108 // Send a message asynchronously. The message is routed to the background |
| 109 // thread where it is passed to the IPC::Channel's Send method. |
| 110 virtual bool Send(Message* message); |
| 111 |
| 112 // Used to intercept messages as they are received on the background thread. |
| 113 // |
| 114 // Ordinarily, messages sent to the ChannelProxy are routed to the matching |
| 115 // listener on the worker thread. This API allows code to intercept messages |
| 116 // before they are sent to the worker thread. |
| 117 void AddFilter(MessageFilter* filter); |
| 118 void RemoveFilter(MessageFilter* filter); |
| 119 |
| 120 #if defined(OS_POSIX) |
| 121 // Calls through to the underlying channel's methods. |
| 122 // TODO(playmobil): For now this is only implemented in the case of |
| 123 // create_pipe_now = true, we need to figure this out for the latter case. |
| 124 int GetClientFileDescriptor() const; |
| 125 #endif // defined(OS_POSIX) |
| 126 |
| 127 protected: |
| 128 class Context; |
| 129 // A subclass uses this constructor if it needs to add more information |
| 130 // to the internal state. If create_pipe_now is true, the pipe is created |
| 131 // immediately. Otherwise it's created on the IO thread. |
| 132 ChannelProxy(const std::string& channel_id, Channel::Mode mode, |
| 133 MessageLoop* ipc_thread_loop, Context* context, |
| 134 bool create_pipe_now); |
| 135 |
| 136 // Used internally to hold state that is referenced on the IPC thread. |
| 137 class Context : public base::RefCountedThreadSafe<Context>, |
| 138 public Channel::Listener { |
| 139 public: |
| 140 Context(Channel::Listener* listener, MessageFilter* filter, |
| 141 MessageLoop* ipc_thread); |
| 142 virtual ~Context() { } |
| 143 MessageLoop* ipc_message_loop() const { return ipc_message_loop_; } |
| 144 const std::string& channel_id() const { return channel_id_; } |
| 145 |
| 146 // Dispatches a message on the listener thread. |
| 147 void OnDispatchMessage(const Message& message); |
| 148 |
| 149 protected: |
| 150 // IPC::Channel::Listener methods: |
| 151 virtual void OnMessageReceived(const Message& message); |
| 152 virtual void OnChannelConnected(int32 peer_pid); |
| 153 virtual void OnChannelError(); |
| 154 |
| 155 // Like OnMessageReceived but doesn't try the filters. |
| 156 void OnMessageReceivedNoFilter(const Message& message); |
| 157 |
| 158 // Gives the filters a chance at processing |message|. |
| 159 // Returns true if the message was processed, false otherwise. |
| 160 bool TryFilters(const Message& message); |
| 161 |
| 162 // Like Open and Close, but called on the IPC thread. |
| 163 virtual void OnChannelOpened(); |
| 164 virtual void OnChannelClosed(); |
| 165 |
| 166 // Called on the consumers thread when the ChannelProxy is closed. At that |
| 167 // point the consumer is telling us that they don't want to receive any |
| 168 // more messages, so we honor that wish by forgetting them! |
| 169 virtual void Clear() { listener_ = NULL; } |
| 170 |
| 171 private: |
| 172 friend class ChannelProxy; |
| 173 // Create the Channel |
| 174 void CreateChannel(const std::string& id, const Channel::Mode& mode); |
| 175 |
| 176 // Methods called via InvokeLater: |
| 177 void OnSendMessage(Message* message_ptr); |
| 178 void OnAddFilter(MessageFilter* filter); |
| 179 void OnRemoveFilter(MessageFilter* filter); |
| 180 void OnDispatchConnected(); |
| 181 void OnDispatchError(); |
| 182 |
| 183 MessageLoop* listener_message_loop_; |
| 184 Channel::Listener* listener_; |
| 185 |
| 186 // List of filters. This is only accessed on the IPC thread. |
| 187 std::vector<scoped_refptr<MessageFilter> > filters_; |
| 188 MessageLoop* ipc_message_loop_; |
| 189 Channel* channel_; |
| 190 std::string channel_id_; |
| 191 int peer_pid_; |
| 192 bool channel_connected_called_; |
| 193 }; |
| 194 |
| 195 Context* context() { return context_; } |
| 196 |
| 197 private: |
| 198 void Init(const std::string& channel_id, Channel::Mode mode, |
| 199 MessageLoop* ipc_thread_loop, bool create_pipe_now); |
| 200 |
| 201 // By maintaining this indirection (ref-counted) to our internal state, we |
| 202 // can safely be destroyed while the background thread continues to do stuff |
| 203 // that involves this data. |
| 204 scoped_refptr<Context> context_; |
| 205 }; |
| 206 |
| 207 } // namespace IPC |
| 208 |
| 209 #endif // IPC_IPC_CHANNEL_PROXY_H__ |
OLD | NEW |