1 // Copyright (c) 2012 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.
5 #ifndef IPC_IPC_CHANNEL_PROXY_H_
6 #define IPC_IPC_CHANNEL_PROXY_H_
10 #include "base/memory/ref_counted.h"
11 #include "base/memory/scoped_ptr.h"
12 #include "base/synchronization/lock.h"
13 #include "ipc/ipc_channel.h"
14 #include "ipc/ipc_channel_handle.h"
15 #include "ipc/ipc_listener.h"
16 #include "ipc/ipc_sender.h"
19 class SingleThreadTaskRunner
;
24 class SendCallbackHelper
;
26 //-----------------------------------------------------------------------------
29 // This class is a helper class that is useful when you wish to run an IPC
30 // channel on a background thread. It provides you with the option of either
31 // handling IPC messages on that background thread or having them dispatched to
32 // your main thread (the thread on which the IPC::ChannelProxy is created).
34 // The API for an IPC::ChannelProxy is very similar to that of an IPC::Channel.
35 // When you send a message to an IPC::ChannelProxy, the message is routed to
36 // the background thread, where it is then passed to the IPC::Channel's Send
37 // method. This means that you can send a message from your thread and your
38 // message will be sent over the IPC channel when possible instead of being
39 // delayed until your thread returns to its message loop. (Often IPC messages
40 // will queue up on the IPC::Channel when there is a lot of traffic, and the
41 // channel will not get cycles to flush its message queue until the thread, on
42 // which it is running, returns to its message loop.)
44 // An IPC::ChannelProxy can have a MessageFilter associated with it, which will
45 // be notified of incoming messages on the IPC::Channel's thread. This gives
46 // the consumer of IPC::ChannelProxy the ability to respond to incoming
47 // messages on this background thread instead of on their own thread, which may
48 // be bogged down with other processing. The result can be greatly improved
49 // latency for messages that can be handled on a background thread.
51 // The consumer of IPC::ChannelProxy is responsible for allocating the Thread
52 // instance where the IPC::Channel will be created and operated.
54 class IPC_EXPORT ChannelProxy
: public Sender
{
56 struct MessageFilterTraits
;
58 // A class that receives messages on the thread where the IPC channel is
59 // running. It can choose to prevent the default action for an IPC message.
60 class IPC_EXPORT MessageFilter
61 : public base::RefCountedThreadSafe
<MessageFilter
, MessageFilterTraits
> {
65 // Called on the background thread to provide the filter with access to the
66 // channel. Called when the IPC channel is initialized or when AddFilter
67 // is called if the channel is already initialized.
68 virtual void OnFilterAdded(Channel
* channel
);
70 // Called on the background thread when the filter has been removed from
71 // the ChannelProxy and when the Channel is closing. After a filter is
72 // removed, it will not be called again.
73 virtual void OnFilterRemoved();
75 // Called to inform the filter that the IPC channel is connected and we
76 // have received the internal Hello message from the peer.
77 virtual void OnChannelConnected(int32 peer_pid
);
79 // Called when there is an error on the channel, typically that the channel
81 virtual void OnChannelError();
83 // Called to inform the filter that the IPC channel will be destroyed.
84 // OnFilterRemoved is called immediately after this.
85 virtual void OnChannelClosing();
87 // Return true to indicate that the message was handled, or false to let
88 // the message be handled in the default way.
89 virtual bool OnMessageReceived(const Message
& message
);
91 // Called when the message filter is about to be deleted. This gives
92 // derived classes the option of controlling which thread they're deleted
94 virtual void OnDestruct() const;
97 virtual ~MessageFilter();
100 friend class base::RefCountedThreadSafe
<MessageFilter
,
101 MessageFilterTraits
>;
104 struct MessageFilterTraits
{
105 static void Destruct(const MessageFilter
* filter
) {
106 filter
->OnDestruct();
111 // Interface for a filter to be imposed on outgoing messages which can
112 // re-write the message. Used mainly for testing.
113 class OutgoingMessageFilter
{
115 // Returns a re-written message, freeing the original, or simply the
116 // original unchanged if no rewrite indicated.
117 virtual Message
*Rewrite(Message
*message
) = 0;
120 // Initializes a channel proxy. The channel_handle and mode parameters are
121 // passed directly to the underlying IPC::Channel. The listener is called on
122 // the thread that creates the ChannelProxy. The filter's OnMessageReceived
123 // method is called on the thread where the IPC::Channel is running. The
124 // filter may be null if the consumer is not interested in handling messages
125 // on the background thread. Any message not handled by the filter will be
126 // dispatched to the listener. The given task runner correspond to a thread
127 // on which IPC::Channel is created and used (e.g. IO thread).
128 ChannelProxy(const IPC::ChannelHandle
& channel_handle
,
131 base::SingleThreadTaskRunner
* ipc_task_runner
);
133 virtual ~ChannelProxy();
135 // Initializes the channel proxy. Only call this once to initialize a channel
136 // proxy that was not initialized in its constructor. If create_pipe_now is
137 // true, the pipe is created synchronously. Otherwise it's created on the IO
139 void Init(const IPC::ChannelHandle
& channel_handle
, Channel::Mode mode
,
140 bool create_pipe_now
);
142 // Close the IPC::Channel. This operation completes asynchronously, once the
143 // background thread processes the command to close the channel. It is ok to
144 // call this method multiple times. Redundant calls are ignored.
146 // WARNING: The MessageFilter object held by the ChannelProxy is also
147 // released asynchronously, and it may in fact have its final reference
148 // released on the background thread. The caller should be careful to deal
149 // with / allow for this possibility.
152 // Send a message asynchronously. The message is routed to the background
153 // thread where it is passed to the IPC::Channel's Send method.
154 virtual bool Send(Message
* message
) OVERRIDE
;
156 // Used to intercept messages as they are received on the background thread.
158 // Ordinarily, messages sent to the ChannelProxy are routed to the matching
159 // listener on the worker thread. This API allows code to intercept messages
160 // before they are sent to the worker thread.
161 // If you call this before the target process is launched, then you're
162 // guaranteed to not miss any messages. But if you call this anytime after,
163 // then some messages might be missed since the filter is added internally on
165 void AddFilter(MessageFilter
* filter
);
166 void RemoveFilter(MessageFilter
* filter
);
168 void set_outgoing_message_filter(OutgoingMessageFilter
* filter
) {
169 outgoing_message_filter_
= filter
;
172 // Called to clear the pointer to the IPC task runner when it's going away.
173 void ClearIPCTaskRunner();
175 // Get the process ID for the connected peer.
176 // Returns base::kNullProcessId if the peer is not connected yet.
177 base::ProcessId
peer_pid() const { return context_
->peer_pid_
; }
179 #if defined(OS_POSIX) && !defined(OS_NACL)
180 // Calls through to the underlying channel's methods.
181 int GetClientFileDescriptor();
182 int TakeClientFileDescriptor();
183 bool GetClientEuid(uid_t
* client_euid
) const;
184 #endif // defined(OS_POSIX)
188 // A subclass uses this constructor if it needs to add more information
189 // to the internal state.
190 ChannelProxy(Context
* context
);
192 // Used internally to hold state that is referenced on the IPC thread.
193 class Context
: public base::RefCountedThreadSafe
<Context
>,
196 Context(Listener
* listener
, base::SingleThreadTaskRunner
* ipc_thread
);
197 void ClearIPCTaskRunner();
198 base::SingleThreadTaskRunner
* ipc_task_runner() const {
199 return ipc_task_runner_
;
201 const std::string
& channel_id() const { return channel_id_
; }
203 // Dispatches a message on the listener thread.
204 void OnDispatchMessage(const Message
& message
);
207 friend class base::RefCountedThreadSafe
<Context
>;
210 // IPC::Listener methods:
211 virtual bool OnMessageReceived(const Message
& message
) OVERRIDE
;
212 virtual void OnChannelConnected(int32 peer_pid
) OVERRIDE
;
213 virtual void OnChannelError() OVERRIDE
;
215 // Like OnMessageReceived but doesn't try the filters.
216 bool OnMessageReceivedNoFilter(const Message
& message
);
218 // Gives the filters a chance at processing |message|.
219 // Returns true if the message was processed, false otherwise.
220 bool TryFilters(const Message
& message
);
222 // Like Open and Close, but called on the IPC thread.
223 virtual void OnChannelOpened();
224 virtual void OnChannelClosed();
226 // Called on the consumers thread when the ChannelProxy is closed. At that
227 // point the consumer is telling us that they don't want to receive any
228 // more messages, so we honor that wish by forgetting them!
229 virtual void Clear();
232 friend class ChannelProxy
;
233 friend class SendCallbackHelper
;
235 // Create the Channel
236 void CreateChannel(const IPC::ChannelHandle
& channel_handle
,
237 const Channel::Mode
& mode
);
239 // Methods called on the IO thread.
240 void OnSendMessage(scoped_ptr
<Message
> message_ptr
);
242 void OnRemoveFilter(MessageFilter
* filter
);
244 // Methods called on the listener thread.
245 void AddFilter(MessageFilter
* filter
);
246 void OnDispatchConnected();
247 void OnDispatchError();
249 scoped_refptr
<base::SingleThreadTaskRunner
> listener_task_runner_
;
252 // List of filters. This is only accessed on the IPC thread.
253 std::vector
<scoped_refptr
<MessageFilter
> > filters_
;
254 scoped_refptr
<base::SingleThreadTaskRunner
> ipc_task_runner_
;
255 scoped_ptr
<Channel
> channel_
;
256 std::string channel_id_
;
257 bool channel_connected_called_
;
259 // Holds filters between the AddFilter call on the listerner thread and the
260 // IPC thread when they're added to filters_.
261 std::vector
<scoped_refptr
<MessageFilter
> > pending_filters_
;
262 // Lock for pending_filters_.
263 base::Lock pending_filters_lock_
;
265 // Cached copy of the peer process ID. Set on IPC but read on both IPC and
267 base::ProcessId peer_pid_
;
270 Context
* context() { return context_
; }
272 OutgoingMessageFilter
* outgoing_message_filter() {
273 return outgoing_message_filter_
;
277 friend class SendCallbackHelper
;
279 // By maintaining this indirection (ref-counted) to our internal state, we
280 // can safely be destroyed while the background thread continues to do stuff
281 // that involves this data.
282 scoped_refptr
<Context
> context_
;
284 OutgoingMessageFilter
* outgoing_message_filter_
;
286 // Whether the channel has been initialized.
292 #endif // IPC_IPC_CHANNEL_PROXY_H_