diff options
Diffstat (limited to 'ipc/ipc_channel_proxy.h')
-rw-r--r-- | ipc/ipc_channel_proxy.h | 272 |
1 files changed, 272 insertions, 0 deletions
diff --git a/ipc/ipc_channel_proxy.h b/ipc/ipc_channel_proxy.h new file mode 100644 index 000000000000..792e3d6a506e --- /dev/null +++ b/ipc/ipc_channel_proxy.h @@ -0,0 +1,272 @@ +// Copyright (c) 2011 The Chromium Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +#ifndef IPC_IPC_CHANNEL_PROXY_H_ +#define IPC_IPC_CHANNEL_PROXY_H_ +#pragma once + +#include <vector> + +#include "base/memory/ref_counted.h" +#include "base/memory/scoped_ptr.h" +#include "base/message_loop_proxy.h" +#include "base/synchronization/lock.h" +#include "ipc/ipc_channel.h" +#include "ipc/ipc_channel_handle.h" + +namespace IPC { + +class SendTask; + +//----------------------------------------------------------------------------- +// IPC::ChannelProxy +// +// This class is a helper class that is useful when you wish to run an IPC +// channel on a background thread. It provides you with the option of either +// handling IPC messages on that background thread or having them dispatched to +// your main thread (the thread on which the IPC::ChannelProxy is created). +// +// The API for an IPC::ChannelProxy is very similar to that of an IPC::Channel. +// When you send a message to an IPC::ChannelProxy, the message is routed to +// the background thread, where it is then passed to the IPC::Channel's Send +// method. This means that you can send a message from your thread and your +// message will be sent over the IPC channel when possible instead of being +// delayed until your thread returns to its message loop. (Often IPC messages +// will queue up on the IPC::Channel when there is a lot of traffic, and the +// channel will not get cycles to flush its message queue until the thread, on +// which it is running, returns to its message loop.) +// +// An IPC::ChannelProxy can have a MessageFilter associated with it, which will +// be notified of incoming messages on the IPC::Channel's thread. This gives +// the consumer of IPC::ChannelProxy the ability to respond to incoming +// messages on this background thread instead of on their own thread, which may +// be bogged down with other processing. The result can be greatly improved +// latency for messages that can be handled on a background thread. +// +// The consumer of IPC::ChannelProxy is responsible for allocating the Thread +// instance where the IPC::Channel will be created and operated. +// +class IPC_EXPORT ChannelProxy : public Message::Sender { + public: + + struct MessageFilterTraits; + + // A class that receives messages on the thread where the IPC channel is + // running. It can choose to prevent the default action for an IPC message. + class IPC_EXPORT MessageFilter + : public base::RefCountedThreadSafe<MessageFilter, MessageFilterTraits> { + public: + MessageFilter(); + virtual ~MessageFilter(); + + // Called on the background thread to provide the filter with access to the + // channel. Called when the IPC channel is initialized or when AddFilter + // is called if the channel is already initialized. + virtual void OnFilterAdded(Channel* channel); + + // Called on the background thread when the filter has been removed from + // the ChannelProxy and when the Channel is closing. After a filter is + // removed, it will not be called again. + virtual void OnFilterRemoved(); + + // Called to inform the filter that the IPC channel is connected and we + // have received the internal Hello message from the peer. + virtual void OnChannelConnected(int32 peer_pid); + + // Called when there is an error on the channel, typically that the channel + // has been closed. + virtual void OnChannelError(); + + // Called to inform the filter that the IPC channel will be destroyed. + // OnFilterRemoved is called immediately after this. + virtual void OnChannelClosing(); + + // Return true to indicate that the message was handled, or false to let + // the message be handled in the default way. + virtual bool OnMessageReceived(const Message& message); + + // Called when the message filter is about to be deleted. This gives + // derived classes the option of controlling which thread they're deleted + // on etc. + virtual void OnDestruct() const; + }; + + struct MessageFilterTraits { + static void Destruct(const MessageFilter* filter) { + filter->OnDestruct(); + } + }; + + // Interface for a filter to be imposed on outgoing messages which can + // re-write the message. Used mainly for testing. + class OutgoingMessageFilter { + public: + // Returns a re-written message, freeing the original, or simply the + // original unchanged if no rewrite indicated. + virtual Message *Rewrite(Message *message) = 0; + }; + + // Initializes a channel proxy. The channel_handle and mode parameters are + // passed directly to the underlying IPC::Channel. The listener is called on + // the thread that creates the ChannelProxy. The filter's OnMessageReceived + // method is called on the thread where the IPC::Channel is running. The + // filter may be null if the consumer is not interested in handling messages + // on the background thread. Any message not handled by the filter will be + // dispatched to the listener. The given message loop indicates where the + // IPC::Channel should be created. + ChannelProxy(const IPC::ChannelHandle& channel_handle, + Channel::Mode mode, + Channel::Listener* listener, + base::MessageLoopProxy* ipc_thread_loop); + + virtual ~ChannelProxy(); + + // Close the IPC::Channel. This operation completes asynchronously, once the + // background thread processes the command to close the channel. It is ok to + // call this method multiple times. Redundant calls are ignored. + // + // WARNING: The MessageFilter object held by the ChannelProxy is also + // released asynchronously, and it may in fact have its final reference + // released on the background thread. The caller should be careful to deal + // with / allow for this possibility. + void Close(); + + // Send a message asynchronously. The message is routed to the background + // thread where it is passed to the IPC::Channel's Send method. + virtual bool Send(Message* message); + + // Used to intercept messages as they are received on the background thread. + // + // Ordinarily, messages sent to the ChannelProxy are routed to the matching + // listener on the worker thread. This API allows code to intercept messages + // before they are sent to the worker thread. + // If you call this before the target process is launched, then you're + // guaranteed to not miss any messages. But if you call this anytime after, + // then some messages might be missed since the filter is added internally on + // the IO thread. + void AddFilter(MessageFilter* filter); + void RemoveFilter(MessageFilter* filter); + + void set_outgoing_message_filter(OutgoingMessageFilter* filter) { + outgoing_message_filter_ = filter; + } + + // Called to clear the pointer to the IPC message loop when it's going away. + void ClearIPCMessageLoop(); + +#if defined(OS_POSIX) + // Calls through to the underlying channel's methods. + int GetClientFileDescriptor() const; + bool GetClientEuid(uid_t* client_euid) const; +#endif // defined(OS_POSIX) + + protected: + class Context; + // A subclass uses this constructor if it needs to add more information + // to the internal state. If create_pipe_now is true, the pipe is created + // immediately. Otherwise it's created on the IO thread. + ChannelProxy(const IPC::ChannelHandle& channel_handle, + Channel::Mode mode, + base::MessageLoopProxy* ipc_thread_loop, + Context* context, + bool create_pipe_now); + + // Used internally to hold state that is referenced on the IPC thread. + class Context : public base::RefCountedThreadSafe<Context>, + public Channel::Listener { + public: + Context(Channel::Listener* listener, base::MessageLoopProxy* ipc_thread); + void ClearIPCMessageLoop() { ipc_message_loop_ = NULL; } + base::MessageLoopProxy* ipc_message_loop() const { + return ipc_message_loop_.get(); + } + const std::string& channel_id() const { return channel_id_; } + + // Dispatches a message on the listener thread. + void OnDispatchMessage(const Message& message); + + protected: + friend class base::RefCountedThreadSafe<Context>; + virtual ~Context(); + + // IPC::Channel::Listener methods: + virtual bool OnMessageReceived(const Message& message) OVERRIDE; + virtual void OnChannelConnected(int32 peer_pid) OVERRIDE; + virtual void OnChannelError() OVERRIDE; + + // Like OnMessageReceived but doesn't try the filters. + bool OnMessageReceivedNoFilter(const Message& message); + + // Gives the filters a chance at processing |message|. + // Returns true if the message was processed, false otherwise. + bool TryFilters(const Message& message); + + // Like Open and Close, but called on the IPC thread. + virtual void OnChannelOpened(); + virtual void OnChannelClosed(); + + // Called on the consumers thread when the ChannelProxy is closed. At that + // point the consumer is telling us that they don't want to receive any + // more messages, so we honor that wish by forgetting them! + virtual void Clear() { listener_ = NULL; } + + private: + friend class ChannelProxy; + friend class SendTask; + + // Create the Channel + void CreateChannel(const IPC::ChannelHandle& channel_handle, + const Channel::Mode& mode); + + // Methods called on the IO thread. + void OnSendMessage(Message* message_ptr); + void OnAddFilter(); + void OnRemoveFilter(MessageFilter* filter); + + // Methods called on the listener thread. + void AddFilter(MessageFilter* filter); + void OnDispatchConnected(); + void OnDispatchError(); + + scoped_refptr<base::MessageLoopProxy> listener_message_loop_; + Channel::Listener* listener_; + + // List of filters. This is only accessed on the IPC thread. + std::vector<scoped_refptr<MessageFilter> > filters_; + scoped_refptr<base::MessageLoopProxy> ipc_message_loop_; + scoped_ptr<Channel> channel_; + std::string channel_id_; + int peer_pid_; + bool channel_connected_called_; + + // Holds filters between the AddFilter call on the listerner thread and the + // IPC thread when they're added to filters_. + std::vector<scoped_refptr<MessageFilter> > pending_filters_; + // Lock for pending_filters_. + base::Lock pending_filters_lock_; + }; + + Context* context() { return context_; } + + OutgoingMessageFilter* outgoing_message_filter() { + return outgoing_message_filter_; + } + + private: + friend class SendTask; + + void Init(const IPC::ChannelHandle& channel_handle, Channel::Mode mode, + base::MessageLoopProxy* ipc_thread_loop, bool create_pipe_now); + + // By maintaining this indirection (ref-counted) to our internal state, we + // can safely be destroyed while the background thread continues to do stuff + // that involves this data. + scoped_refptr<Context> context_; + + OutgoingMessageFilter* outgoing_message_filter_; +}; + +} // namespace IPC + +#endif // IPC_IPC_CHANNEL_PROXY_H_ |