mojo/system/channel.h

   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/basictypes.h"
  11 #include "base/compiler_specific.h"
  12 #include "base/containers/hash_tables.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/core.h"
  20 #include "mojo/system/message_in_transit.h"
  21 #include "mojo/system/message_pipe.h"
  22 #include "mojo/system/raw_channel.h"
  23 #include "mojo/system/system_impl_export.h"
  24
  25 namespace mojo {
  26 namespace system {
  27
  28 // This class is mostly thread-safe. It must be created on an I/O thread.
  29 // |Init()| must be called on that same thread before it becomes thread-safe (in
  30 // particular, before references are given to any other thread) and |Shutdown()|
  31 // must be called on that same thread before destruction. Its public methods are
  32 // otherwise thread-safe. It may be destroyed on any thread, in the sense that
  33 // the last reference to it may be released on any thread, with the proviso that
  34 // |Shutdown()| must have been called first (so the pattern is that a "main"
  35 // reference is kept on its creation thread and is released after |Shutdown()|
  36 // is called, but other threads may have temporarily "dangling" references).
  37 //
  38 // Note that |MessagePipe| calls into |Channel| and the former's |lock_| must be
  39 // acquired before the latter's. When |Channel| wants to call into a
  40 // |MessagePipe|, it must obtain a reference to the |MessagePipe| (from
  41 // |local_id_to_endpoint_info_map_|) under |Channel::lock_| and then release the
  42 // lock.
  43 //
  44 // Also, care must be taken with respect to references: While a |Channel| has
  45 // references to |MessagePipe|s, |MessagePipe|s (via |ProxyMessagePipeEndpoint|)
  46 // may also have references to |Channel|s. These references are set up by
  47 // calling |AttachMessagePipeEndpoint()|. The reference to |MessagePipe| owned
  48 // by |Channel| must be removed by calling |DetachMessagePipeEndpoint()| (which
  49 // is done by |MessagePipe|/|ProxyMessagePipeEndpoint|, which simultaneously
  50 // removes its reference to |Channel|).
  51 class MOJO_SYSTEM_IMPL_EXPORT Channel
  52     : public base::RefCountedThreadSafe<Channel>,
  53       public RawChannel::Delegate {
  54  public:
  55   // The first message pipe endpoint attached will have this as its local ID.
  56   static const MessageInTransit::EndpointId kBootstrapEndpointId = 1;
  57
  58   Channel();
  59
  60   // This must be called on the creation thread before any other methods are
  61   // called, and before references to this object are given to any other
  62   // threads. |raw_channel| should be uninitialized. Returns true on success. On
  63   // failure, no other methods should be called (including |Shutdown()|).
  64   bool Init(scoped_ptr<RawChannel> raw_channel);
  65
  66   // This must be called on the creation thread before destruction (which can
  67   // happen on any thread).
  68   void Shutdown();
  69
  70   // Attaches the given message pipe/port's endpoint (which must be a
  71   // |ProxyMessagePipeEndpoint|) to this channel. This assigns it a local ID,
  72   // which it returns. The first message pipe endpoint attached will always have
  73   // |kBootstrapEndpointId| as its local ID. (For bootstrapping, this occurs on
  74   // both sides, so one should use |kBootstrapEndpointId| for the remote ID for
  75   // the first message pipe across a channel.)
  76   // TODO(vtl): Maybe limit the number of attached message pipes and allow this
  77   // to fail.
  78   MessageInTransit::EndpointId AttachMessagePipeEndpoint(
  79       scoped_refptr<MessagePipe> message_pipe, unsigned port);
  80
  81   // Runs the message pipe with the given |local_id| (previously attached), with
  82   // the given |remote_id| (negotiated using some other means, e.g., over an
  83   // existing message pipe; see comments above for the bootstrap case). Returns
  84   // false on failure, in particular if no message pipe with |local_id| is
  85   // attached.
  86   bool RunMessagePipeEndpoint(MessageInTransit::EndpointId local_id,
  87                               MessageInTransit::EndpointId remote_id);
  88
  89   // Tells the other side of the channel to run a message pipe endpoint (which
  90   // must already be attached); |local_id| and |remote_id| are relative to this
  91   // channel (i.e., |local_id| is the other side's remote ID and |remote_id| is
  92   // its local ID).
  93   // TODO(vtl): Maybe we should just have a flag argument to
  94   // |RunMessagePipeEndpoint()| that tells it to do this.
  95   void RunRemoteMessagePipeEndpoint(MessageInTransit::EndpointId local_id,
  96                                     MessageInTransit::EndpointId remote_id);
  97
  98   // This forwards |message| verbatim to |raw_channel_|.
  99   bool WriteMessage(scoped_ptr<MessageInTransit> message);
 100
 101   // See |RawChannel::IsWriteBufferEmpty()|.
 102   // TODO(vtl): Maybe we shouldn't expose this, and instead have a
 103   // |FlushWriteBufferAndShutdown()| or something like that.
 104   bool IsWriteBufferEmpty();
 105
 106   // This removes the message pipe/port's endpoint (with the given local ID,
 107   // returned by |AttachMessagePipeEndpoint()| from this channel. After this is
 108   // called, |local_id| may be reused for another message pipe.
 109   void DetachMessagePipeEndpoint(MessageInTransit::EndpointId local_id);
 110
 111  private:
 112   friend class base::RefCountedThreadSafe<Channel>;
 113   virtual ~Channel();
 114
 115   // |RawChannel::Delegate| implementation:
 116   virtual void OnReadMessage(
 117       const MessageInTransit::View& message_view) OVERRIDE;
 118   virtual void OnFatalError(FatalError fatal_error) OVERRIDE;
 119
 120   // Helpers for |OnReadMessage|:
 121   bool ValidateReadMessage(const MessageInTransit::View& message_view);
 122   void OnReadMessageForDownstream(const MessageInTransit::View& message_view);
 123   void OnReadMessageForChannel(const MessageInTransit::View& message_view);
 124
 125   // Handles errors (e.g., invalid messages) from the remote side.
 126   void HandleRemoteError(const base::StringPiece& error_message);
 127   // Handles internal errors/failures from the local side.
 128   void HandleLocalError(const base::StringPiece& error_message);
 129
 130   struct EndpointInfo {
 131     EndpointInfo();
 132     EndpointInfo(scoped_refptr<MessagePipe> message_pipe, unsigned port);
 133     ~EndpointInfo();
 134
 135     scoped_refptr<MessagePipe> message_pipe;
 136     unsigned port;
 137   };
 138
 139   base::ThreadChecker creation_thread_checker_;
 140
 141   // Note: |MessagePipe|s MUST NOT be used under |lock_|. I.e., |lock_| can only
 142   // be acquired after |MessagePipe::lock_|, never before. Thus to call into a
 143   // |MessagePipe|, a reference should be acquired from
 144   // |local_id_to_endpoint_info_map_| under |lock_| (e.g., by copying the
 145   // |EndpointInfo|) and then the lock released.
 146   base::Lock lock_;  // Protects the members below.
 147
 148   scoped_ptr<RawChannel> raw_channel_;
 149
 150   typedef base::hash_map<MessageInTransit::EndpointId, EndpointInfo>
 151       IdToEndpointInfoMap;
 152   IdToEndpointInfoMap local_id_to_endpoint_info_map_;
 153   // The next local ID to try (when allocating new local IDs). Note: It should
 154   // be checked for existence before use.
 155   MessageInTransit::EndpointId next_local_id_;
 156
 157   DISALLOW_COPY_AND_ASSIGN(Channel);
 158 };
 159
 160 }  // namespace system
 161 }  // namespace mojo
 162
 163 #endif  // MOJO_SYSTEM_CHANNEL_H_