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