base/callback_internal.h

   1 // Copyright (c) 2012 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 // This file contains utility functions and classes that help the
   6 // implementation, and management of the Callback objects.
   7
   8 #ifndef BASE_CALLBACK_INTERNAL_H_
   9 #define BASE_CALLBACK_INTERNAL_H_
  10
  11 #include <stddef.h>
  12
  13 #include "base/base_export.h"
  14 #include "base/memory/ref_counted.h"
  15 #include "base/memory/scoped_ptr.h"
  16
  17 template <typename T>
  18 class ScopedVector;
  19
  20 namespace base {
  21 namespace internal {
  22
  23 // BindStateBase is used to provide an opaque handle that the Callback
  24 // class can use to represent a function object with bound arguments.  It
  25 // behaves as an existential type that is used by a corresponding
  26 // DoInvoke function to perform the function execution.  This allows
  27 // us to shield the Callback class from the types of the bound argument via
  28 // "type erasure."
  29 class BindStateBase : public RefCountedThreadSafe<BindStateBase> {
  30  protected:
  31   friend class RefCountedThreadSafe<BindStateBase>;
  32   virtual ~BindStateBase() {}
  33 };
  34
  35 // Holds the Callback methods that don't require specialization to reduce
  36 // template bloat.
  37 class BASE_EXPORT CallbackBase {
  38  public:
  39   // Returns true if Callback is null (doesn't refer to anything).
  40   bool is_null() const;
  41
  42   // Returns the Callback into an uninitialized state.
  43   void Reset();
  44
  45  protected:
  46   // In C++, it is safe to cast function pointers to function pointers of
  47   // another type. It is not okay to use void*. We create a InvokeFuncStorage
  48   // that that can store our function pointer, and then cast it back to
  49   // the original type on usage.
  50   typedef void(*InvokeFuncStorage)(void);
  51
  52   // Returns true if this callback equals |other|. |other| may be null.
  53   bool Equals(const CallbackBase& other) const;
  54
  55   // Allow initializing of |bind_state_| via the constructor to avoid default
  56   // initialization of the scoped_refptr.  We do not also initialize
  57   // |polymorphic_invoke_| here because doing a normal assignment in the
  58   // derived Callback templates makes for much nicer compiler errors.
  59   explicit CallbackBase(BindStateBase* bind_state);
  60
  61   // Force the destructor to be instantiated inside this translation unit so
  62   // that our subclasses will not get inlined versions.  Avoids more template
  63   // bloat.
  64   ~CallbackBase();
  65
  66   scoped_refptr<BindStateBase> bind_state_;
  67   InvokeFuncStorage polymorphic_invoke_;
  68 };
  69
  70 // This is a typetraits object that's used to take an argument type, and
  71 // extract a suitable type for storing and forwarding arguments.
  72 //
  73 // In particular, it strips off references, and converts arrays to
  74 // pointers for storage; and it avoids accidentally trying to create a
  75 // "reference of a reference" if the argument is a reference type.
  76 //
  77 // This array type becomes an issue for storage because we are passing bound
  78 // parameters by const reference. In this case, we end up passing an actual
  79 // array type in the initializer list which C++ does not allow.  This will
  80 // break passing of C-string literals.
  81 template <typename T>
  82 struct CallbackParamTraits {
  83   typedef const T& ForwardType;
  84   typedef T StorageType;
  85 };
  86
  87 // The Storage should almost be impossible to trigger unless someone manually
  88 // specifies type of the bind parameters.  However, in case they do,
  89 // this will guard against us accidentally storing a reference parameter.
  90 //
  91 // The ForwardType should only be used for unbound arguments.
  92 template <typename T>
  93 struct CallbackParamTraits<T&> {
  94   typedef T& ForwardType;
  95   typedef T StorageType;
  96 };
  97
  98 // Note that for array types, we implicitly add a const in the conversion. This
  99 // means that it is not possible to bind array arguments to functions that take
 100 // a non-const pointer. Trying to specialize the template based on a "const
 101 // T[n]" does not seem to match correctly, so we are stuck with this
 102 // restriction.
 103 template <typename T, size_t n>
 104 struct CallbackParamTraits<T[n]> {
 105   typedef const T* ForwardType;
 106   typedef const T* StorageType;
 107 };
 108
 109 // See comment for CallbackParamTraits<T[n]>.
 110 template <typename T>
 111 struct CallbackParamTraits<T[]> {
 112   typedef const T* ForwardType;
 113   typedef const T* StorageType;
 114 };
 115
 116 // Parameter traits for movable-but-not-copyable scopers.
 117 //
 118 // Callback<>/Bind() understands movable-but-not-copyable semantics where
 119 // the type cannot be copied but can still have its state destructively
 120 // transferred (aka. moved) to another instance of the same type by calling a
 121 // helper function.  When used with Bind(), this signifies transferal of the
 122 // object's state to the target function.
 123 //
 124 // For these types, the ForwardType must not be a const reference, or a
 125 // reference.  A const reference is inappropriate, and would break const
 126 // correctness, because we are implementing a destructive move.  A non-const
 127 // reference cannot be used with temporaries which means the result of a
 128 // function or a cast would not be usable with Callback<> or Bind().
 129 //
 130 // TODO(ajwong): We might be able to use SFINAE to search for the existence of
 131 // a Pass() function in the type and avoid the whitelist in CallbackParamTraits
 132 // and CallbackForward.
 133 template <typename T, typename D>
 134 struct CallbackParamTraits<scoped_ptr<T, D> > {
 135   typedef scoped_ptr<T, D> ForwardType;
 136   typedef scoped_ptr<T, D> StorageType;
 137 };
 138
 139 template <typename T, typename R>
 140 struct CallbackParamTraits<scoped_ptr_malloc<T, R> > {
 141   typedef scoped_ptr_malloc<T, R> ForwardType;
 142   typedef scoped_ptr_malloc<T, R> StorageType;
 143 };
 144
 145 template <typename T>
 146 struct CallbackParamTraits<ScopedVector<T> > {
 147   typedef ScopedVector<T> ForwardType;
 148   typedef ScopedVector<T> StorageType;
 149 };
 150
 151 // CallbackForward() is a very limited simulation of C++11's std::forward()
 152 // used by the Callback/Bind system for a set of movable-but-not-copyable
 153 // types.  It is needed because forwarding a movable-but-not-copyable
 154 // argument to another function requires us to invoke the proper move
 155 // operator to create a rvalue version of the type.  The supported types are
 156 // whitelisted below as overloads of the CallbackForward() function. The
 157 // default template compiles out to be a no-op.
 158 //
 159 // In C++11, std::forward would replace all uses of this function.  However, it
 160 // is impossible to implement a general std::forward with C++11 due to a lack
 161 // of rvalue references.
 162 //
 163 // In addition to Callback/Bind, this is used by PostTaskAndReplyWithResult to
 164 // simulate std::forward() and forward the result of one Callback as a
 165 // parameter to another callback. This is to support Callbacks that return
 166 // the movable-but-not-copyable types whitelisted above.
 167 template <typename T>
 168 T& CallbackForward(T& t) { return t; }
 169
 170 template <typename T, typename D>
 171 scoped_ptr<T, D> CallbackForward(scoped_ptr<T, D>& p) { return p.Pass(); }
 172
 173 template <typename T, typename R>
 174 scoped_ptr_malloc<T, R> CallbackForward(scoped_ptr_malloc<T, R>& p) {
 175   return p.Pass();
 176 }
 177
 178 template <typename T>
 179 ScopedVector<T> CallbackForward(ScopedVector<T>& p) { return p.Pass(); }
 180
 181 }  // namespace internal
 182 }  // namespace base
 183
 184 #endif  // BASE_CALLBACK_INTERNAL_H_