michael@0: // Copyright (c) 2006-2008 The Chromium Authors. All rights reserved. michael@0: // Use of this source code is governed by a BSD-style license that can be michael@0: // found in the LICENSE file. michael@0: michael@0: #ifndef CHROME_COMMON_IPC_CHANNEL_PROXY_H__ michael@0: #define CHROME_COMMON_IPC_CHANNEL_PROXY_H__ michael@0: michael@0: #include michael@0: #include "base/lock.h" michael@0: #include "base/ref_counted.h" michael@0: #include "chrome/common/ipc_channel.h" michael@0: michael@0: class MessageLoop; michael@0: michael@0: namespace IPC { michael@0: michael@0: //----------------------------------------------------------------------------- michael@0: // IPC::ChannelProxy michael@0: // michael@0: // This class is a helper class that is useful when you wish to run an IPC michael@0: // channel on a background thread. It provides you with the option of either michael@0: // handling IPC messages on that background thread or having them dispatched to michael@0: // your main thread (the thread on which the IPC::ChannelProxy is created). michael@0: // michael@0: // The API for an IPC::ChannelProxy is very similar to that of an IPC::Channel. michael@0: // When you send a message to an IPC::ChannelProxy, the message is routed to michael@0: // the background thread, where it is then passed to the IPC::Channel's Send michael@0: // method. This means that you can send a message from your thread and your michael@0: // message will be sent over the IPC channel when possible instead of being michael@0: // delayed until your thread returns to its message loop. (Often IPC messages michael@0: // will queue up on the IPC::Channel when there is a lot of traffic, and the michael@0: // channel will not get cycles to flush its message queue until the thread, on michael@0: // which it is running, returns to its message loop.) michael@0: // michael@0: // An IPC::ChannelProxy can have a MessageFilter associated with it, which will michael@0: // be notified of incoming messages on the IPC::Channel's thread. This gives michael@0: // the consumer of IPC::ChannelProxy the ability to respond to incoming michael@0: // messages on this background thread instead of on their own thread, which may michael@0: // be bogged down with other processing. The result can be greatly improved michael@0: // latency for messages that can be handled on a background thread. michael@0: // michael@0: // The consumer of IPC::ChannelProxy is responsible for allocating the Thread michael@0: // instance where the IPC::Channel will be created and operated. michael@0: // michael@0: class ChannelProxy : public Message::Sender { michael@0: public: michael@0: // A class that receives messages on the thread where the IPC channel is michael@0: // running. It can choose to prevent the default action for an IPC message. michael@0: class MessageFilter : public base::RefCountedThreadSafe { michael@0: public: michael@0: virtual ~MessageFilter() {} michael@0: michael@0: // Called on the background thread to provide the filter with access to the michael@0: // channel. Called when the IPC channel is initialized or when AddFilter michael@0: // is called if the channel is already initialized. michael@0: virtual void OnFilterAdded(Channel* channel) {} michael@0: michael@0: // Called on the background thread when the filter has been removed from michael@0: // the ChannelProxy and when the Channel is closing. After a filter is michael@0: // removed, it will not be called again. michael@0: virtual void OnFilterRemoved() {} michael@0: michael@0: // Called to inform the filter that the IPC channel is connected and we michael@0: // have received the internal Hello message from the peer. michael@0: virtual void OnChannelConnected(int32_t peer_pid) {} michael@0: michael@0: // Called when there is an error on the channel, typically that the channel michael@0: // has been closed. michael@0: virtual void OnChannelError() {} michael@0: michael@0: // Called to inform the filter that the IPC channel will be destroyed. michael@0: // OnFilterRemoved is called immediately after this. michael@0: virtual void OnChannelClosing() {} michael@0: michael@0: // Return true to indicate that the message was handled, or false to let michael@0: // the message be handled in the default way. michael@0: virtual bool OnMessageReceived(const Message& message) { michael@0: return false; michael@0: } michael@0: }; michael@0: michael@0: // Initializes a channel proxy. The channel_id and mode parameters are michael@0: // passed directly to the underlying IPC::Channel. The listener is called on michael@0: // the thread that creates the ChannelProxy. The filter's OnMessageReceived michael@0: // method is called on the thread where the IPC::Channel is running. The michael@0: // filter may be null if the consumer is not interested in handling messages michael@0: // on the background thread. Any message not handled by the filter will be michael@0: // dispatched to the listener. The given message loop indicates where the michael@0: // IPC::Channel should be created. michael@0: ChannelProxy(const std::wstring& channel_id, Channel::Mode mode, michael@0: Channel::Listener* listener, MessageFilter* filter, michael@0: MessageLoop* ipc_thread_loop); michael@0: michael@0: ~ChannelProxy() { michael@0: Close(); michael@0: } michael@0: michael@0: // Close the IPC::Channel. This operation completes asynchronously, once the michael@0: // background thread processes the command to close the channel. It is ok to michael@0: // call this method multiple times. Redundant calls are ignored. michael@0: // michael@0: // WARNING: The MessageFilter object held by the ChannelProxy is also michael@0: // released asynchronously, and it may in fact have its final reference michael@0: // released on the background thread. The caller should be careful to deal michael@0: // with / allow for this possibility. michael@0: void Close(); michael@0: michael@0: // Send a message asynchronously. The message is routed to the background michael@0: // thread where it is passed to the IPC::Channel's Send method. michael@0: virtual bool Send(Message* message); michael@0: michael@0: // Used to intercept messages as they are received on the background thread. michael@0: // michael@0: // Ordinarily, messages sent to the ChannelProxy are routed to the matching michael@0: // listener on the worker thread. This API allows code to intercept messages michael@0: // before they are sent to the worker thread. michael@0: void AddFilter(MessageFilter* filter); michael@0: void RemoveFilter(MessageFilter* filter); michael@0: michael@0: #if defined(OS_POSIX) michael@0: // Calls through to the underlying channel's methods. michael@0: // TODO(playmobil): For now this is only implemented in the case of michael@0: // create_pipe_now = true, we need to figure this out for the latter case. michael@0: void GetClientFileDescriptorMapping(int *src_fd, int *dest_fd) const; michael@0: #endif // defined(OS_POSIX) michael@0: michael@0: protected: michael@0: class Context; michael@0: // A subclass uses this constructor if it needs to add more information michael@0: // to the internal state. If create_pipe_now is true, the pipe is created michael@0: // immediately. Otherwise it's created on the IO thread. michael@0: ChannelProxy(const std::wstring& channel_id, Channel::Mode mode, michael@0: MessageLoop* ipc_thread_loop, Context* context, michael@0: bool create_pipe_now); michael@0: michael@0: // Used internally to hold state that is referenced on the IPC thread. michael@0: class Context : public base::RefCountedThreadSafe, michael@0: public Channel::Listener { michael@0: public: michael@0: Context(Channel::Listener* listener, MessageFilter* filter, michael@0: MessageLoop* ipc_thread); michael@0: virtual ~Context() { } michael@0: MessageLoop* ipc_message_loop() const { return ipc_message_loop_; } michael@0: const std::wstring& channel_id() const { return channel_id_; } michael@0: michael@0: // Dispatches a message on the listener thread. michael@0: void OnDispatchMessage(const Message& message); michael@0: michael@0: protected: michael@0: // IPC::Channel::Listener methods: michael@0: virtual void OnMessageReceived(const Message& message); michael@0: virtual void OnChannelConnected(int32_t peer_pid); michael@0: virtual void OnChannelError(); michael@0: michael@0: // Like OnMessageReceived but doesn't try the filters. michael@0: void OnMessageReceivedNoFilter(const Message& message); michael@0: michael@0: // Gives the filters a chance at processing |message|. michael@0: // Returns true if the message was processed, false otherwise. michael@0: bool TryFilters(const Message& message); michael@0: michael@0: // Like Open and Close, but called on the IPC thread. michael@0: virtual void OnChannelOpened(); michael@0: virtual void OnChannelClosed(); michael@0: michael@0: // Called on the consumers thread when the ChannelProxy is closed. At that michael@0: // point the consumer is telling us that they don't want to receive any michael@0: // more messages, so we honor that wish by forgetting them! michael@0: virtual void Clear() { listener_ = NULL; } michael@0: michael@0: private: michael@0: friend class ChannelProxy; michael@0: // Create the Channel michael@0: void CreateChannel(const std::wstring& id, const Channel::Mode& mode); michael@0: michael@0: // Methods called via InvokeLater: michael@0: void OnSendMessage(Message* message_ptr); michael@0: void OnAddFilter(MessageFilter* filter); michael@0: void OnRemoveFilter(MessageFilter* filter); michael@0: void OnDispatchConnected(); michael@0: void OnDispatchError(); michael@0: michael@0: MessageLoop* listener_message_loop_; michael@0: Channel::Listener* listener_; michael@0: michael@0: // List of filters. This is only accessed on the IPC thread. michael@0: std::vector > filters_; michael@0: MessageLoop* ipc_message_loop_; michael@0: Channel* channel_; michael@0: std::wstring channel_id_; michael@0: int peer_pid_; michael@0: bool channel_connected_called_; michael@0: }; michael@0: michael@0: Context* context() { return context_; } michael@0: michael@0: private: michael@0: void Init(const std::wstring& channel_id, Channel::Mode mode, michael@0: MessageLoop* ipc_thread_loop, bool create_pipe_now); michael@0: michael@0: // By maintaining this indirection (ref-counted) to our internal state, we michael@0: // can safely be destroyed while the background thread continues to do stuff michael@0: // that involves this data. michael@0: scoped_refptr context_; michael@0: }; michael@0: michael@0: } // namespace IPC michael@0: michael@0: #endif // CHROME_COMMON_IPC_CHANNEL_PROXY_H__