src/mojo/public/cpp/bindings/interface_ptr.h

   1 // Copyright 2014 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_PUBLIC_CPP_BINDINGS_INTERFACE_PTR_H_
   6 #define MOJO_PUBLIC_CPP_BINDINGS_INTERFACE_PTR_H_
   7
   8 #include <algorithm>
   9
  10 #include "mojo/public/cpp/bindings/error_handler.h"
  11 #include "mojo/public/cpp/bindings/lib/interface_ptr_internal.h"
  12 #include "mojo/public/cpp/environment/environment.h"
  13 #include "mojo/public/cpp/system/macros.h"
  14
  15 namespace mojo {
  16 class ErrorHandler;
  17
  18 // InterfacePtr represents a proxy to a remote instance of an interface.
  19 template <typename Interface>
  20 class InterfacePtr {
  21   MOJO_MOVE_ONLY_TYPE_FOR_CPP_03(InterfacePtr, RValue)
  22  public:
  23   InterfacePtr() {}
  24
  25   InterfacePtr(RValue other) {
  26     internal_state_.Swap(&other.object->internal_state_);
  27   }
  28   InterfacePtr& operator=(RValue other) {
  29     reset();
  30     internal_state_.Swap(&other.object->internal_state_);
  31     return *this;
  32   }
  33
  34   ~InterfacePtr() {}
  35
  36   Interface* get() const { return internal_state_.instance(); }
  37   Interface* operator->() const { return get(); }
  38   Interface& operator*() const { return *get(); }
  39
  40   void reset() {
  41     State doomed;
  42     internal_state_.Swap(&doomed);
  43   }
  44
  45   // Blocks the current thread for the first incoming method call, i.e., either
  46   // a call to a client method or a callback method. Returns |true| if a method
  47   // has been called, |false| in case of error. It must only be called on a
  48   // bound object.
  49   bool WaitForIncomingMethodCall() {
  50     return internal_state_.WaitForIncomingMethodCall();
  51   }
  52
  53   // This method configures the InterfacePtr<..> to be a proxy to a remote
  54   // object on the other end of the given pipe.
  55   //
  56   // The proxy is bound to the current thread, which means its methods may
  57   // only be called on the current thread.
  58   //
  59   // To move a bound InterfacePtr<..> to another thread, call PassMessagePipe().
  60   // Then create a new InterfacePtr<..> on another thread, and bind the new
  61   // InterfacePtr<..> to the message pipe on that thread.
  62   void Bind(
  63       ScopedMessagePipeHandle handle,
  64       const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) {
  65     reset();
  66     internal_state_.Bind(handle.Pass(), waiter);
  67   }
  68
  69   // The client interface may only be set after this InterfacePtr<..> is bound.
  70   void set_client(typename Interface::Client* client) {
  71     internal_state_.set_client(client);
  72   }
  73
  74   // This method may be called to query if the underlying pipe has encountered
  75   // an error. If true, this means method calls made on this interface will be
  76   // dropped (and may have already been dropped) on the floor.
  77   bool encountered_error() const { return internal_state_.encountered_error(); }
  78
  79   // This method may be called to register an ErrorHandler to observe a
  80   // connection error on the underlying pipe. It must only be called on a bound
  81   // object.
  82   // The callback runs asynchronously from the current message loop.
  83   void set_error_handler(ErrorHandler* error_handler) {
  84     internal_state_.set_error_handler(error_handler);
  85   }
  86
  87   // Returns the underlying message pipe handle (if any) and resets the
  88   // InterfacePtr<..> to its uninitialized state. This method is helpful if you
  89   // need to move a proxy to another thread. See related notes for Bind.
  90   ScopedMessagePipeHandle PassMessagePipe() {
  91     State state;
  92     internal_state_.Swap(&state);
  93     return state.PassMessagePipe();
  94   }
  95
  96   // DO NOT USE. Exposed only for internal use and for testing.
  97   internal::InterfacePtrState<Interface>* internal_state() {
  98     return &internal_state_;
  99   }
 100
 101   // Allow InterfacePtr<> to be used in boolean expressions, but not
 102   // implicitly convertible to a real bool (which is dangerous).
 103  private:
 104   typedef internal::InterfacePtrState<Interface> InterfacePtr::*Testable;
 105
 106  public:
 107   operator Testable() const {
 108     return internal_state_.is_bound() ? &InterfacePtr::internal_state_
 109                                       : nullptr;
 110   }
 111
 112  private:
 113   typedef internal::InterfacePtrState<Interface> State;
 114   mutable State internal_state_;
 115 };
 116
 117 // Takes a handle to the proxy end-point of a pipe. On the other end is
 118 // presumed to be an interface implementation of type |Interface|. Returns a
 119 // generated proxy to that interface, which may be used on the current thread.
 120 // It is valid to call set_client on the returned InterfacePtr<..> to set an
 121 // instance of Interface::Client.
 122 template <typename Interface>
 123 InterfacePtr<Interface> MakeProxy(
 124     ScopedMessagePipeHandle handle,
 125     const MojoAsyncWaiter* waiter = Environment::GetDefaultAsyncWaiter()) {
 126   InterfacePtr<Interface> ptr;
 127   if (handle.is_valid())
 128     ptr.Bind(handle.Pass(), waiter);
 129   return ptr.Pass();
 130 }
 131
 132 }  // namespace mojo
 133
 134 #endif  // MOJO_PUBLIC_CPP_BINDINGS_INTERFACE_PTR_H_