michael@0: // Copyright (c) 2012 The Chromium Authors. All rights reserved.
michael@0: // Use of this source code is governed by a BSD-style license that can be
michael@0: // found in the LICENSE file.
michael@0: 
michael@0: // This file contains utility functions and classes that help the
michael@0: // implementation, and management of the Callback objects.
michael@0: 
michael@0: #ifndef BASE_CALLBACK_INTERNAL_H_
michael@0: #define BASE_CALLBACK_INTERNAL_H_
michael@0: 
michael@0: #include <stddef.h>
michael@0: 
michael@0: #include "base/base_export.h"
michael@0: #include "base/memory/ref_counted.h"
michael@0: #include "base/memory/scoped_ptr.h"
michael@0: 
michael@0: template <typename T>
michael@0: class ScopedVector;
michael@0: 
michael@0: namespace base {
michael@0: namespace internal {
michael@0: 
michael@0: // BindStateBase is used to provide an opaque handle that the Callback
michael@0: // class can use to represent a function object with bound arguments.  It
michael@0: // behaves as an existential type that is used by a corresponding
michael@0: // DoInvoke function to perform the function execution.  This allows
michael@0: // us to shield the Callback class from the types of the bound argument via
michael@0: // "type erasure."
michael@0: class BindStateBase : public RefCountedThreadSafe<BindStateBase> {
michael@0:  protected:
michael@0:   friend class RefCountedThreadSafe<BindStateBase>;
michael@0:   virtual ~BindStateBase() {}
michael@0: };
michael@0: 
michael@0: // Holds the Callback methods that don't require specialization to reduce
michael@0: // template bloat.
michael@0: class BASE_EXPORT CallbackBase {
michael@0:  public:
michael@0:   // Returns true if Callback is null (doesn't refer to anything).
michael@0:   bool is_null() const;
michael@0: 
michael@0:   // Returns the Callback into an uninitialized state.
michael@0:   void Reset();
michael@0: 
michael@0:  protected:
michael@0:   // In C++, it is safe to cast function pointers to function pointers of
michael@0:   // another type. It is not okay to use void*. We create a InvokeFuncStorage
michael@0:   // that that can store our function pointer, and then cast it back to
michael@0:   // the original type on usage.
michael@0:   typedef void(*InvokeFuncStorage)(void);
michael@0: 
michael@0:   // Returns true if this callback equals |other|. |other| may be null.
michael@0:   bool Equals(const CallbackBase& other) const;
michael@0: 
michael@0:   // Allow initializing of |bind_state_| via the constructor to avoid default
michael@0:   // initialization of the scoped_refptr.  We do not also initialize
michael@0:   // |polymorphic_invoke_| here because doing a normal assignment in the
michael@0:   // derived Callback templates makes for much nicer compiler errors.
michael@0:   explicit CallbackBase(BindStateBase* bind_state);
michael@0: 
michael@0:   // Force the destructor to be instantiated inside this translation unit so
michael@0:   // that our subclasses will not get inlined versions.  Avoids more template
michael@0:   // bloat.
michael@0:   ~CallbackBase();
michael@0: 
michael@0:   scoped_refptr<BindStateBase> bind_state_;
michael@0:   InvokeFuncStorage polymorphic_invoke_;
michael@0: };
michael@0: 
michael@0: // This is a typetraits object that's used to take an argument type, and
michael@0: // extract a suitable type for storing and forwarding arguments.
michael@0: //
michael@0: // In particular, it strips off references, and converts arrays to
michael@0: // pointers for storage; and it avoids accidentally trying to create a
michael@0: // "reference of a reference" if the argument is a reference type.
michael@0: //
michael@0: // This array type becomes an issue for storage because we are passing bound
michael@0: // parameters by const reference. In this case, we end up passing an actual
michael@0: // array type in the initializer list which C++ does not allow.  This will
michael@0: // break passing of C-string literals.
michael@0: template <typename T>
michael@0: struct CallbackParamTraits {
michael@0:   typedef const T& ForwardType;
michael@0:   typedef T StorageType;
michael@0: };
michael@0: 
michael@0: // The Storage should almost be impossible to trigger unless someone manually
michael@0: // specifies type of the bind parameters.  However, in case they do,
michael@0: // this will guard against us accidentally storing a reference parameter.
michael@0: //
michael@0: // The ForwardType should only be used for unbound arguments.
michael@0: template <typename T>
michael@0: struct CallbackParamTraits<T&> {
michael@0:   typedef T& ForwardType;
michael@0:   typedef T StorageType;
michael@0: };
michael@0: 
michael@0: // Note that for array types, we implicitly add a const in the conversion. This
michael@0: // means that it is not possible to bind array arguments to functions that take
michael@0: // a non-const pointer. Trying to specialize the template based on a "const
michael@0: // T[n]" does not seem to match correctly, so we are stuck with this
michael@0: // restriction.
michael@0: template <typename T, size_t n>
michael@0: struct CallbackParamTraits<T[n]> {
michael@0:   typedef const T* ForwardType;
michael@0:   typedef const T* StorageType;
michael@0: };
michael@0: 
michael@0: // See comment for CallbackParamTraits<T[n]>.
michael@0: template <typename T>
michael@0: struct CallbackParamTraits<T[]> {
michael@0:   typedef const T* ForwardType;
michael@0:   typedef const T* StorageType;
michael@0: };
michael@0: 
michael@0: // Parameter traits for movable-but-not-copyable scopers.
michael@0: //
michael@0: // Callback<>/Bind() understands movable-but-not-copyable semantics where
michael@0: // the type cannot be copied but can still have its state destructively
michael@0: // transferred (aka. moved) to another instance of the same type by calling a
michael@0: // helper function.  When used with Bind(), this signifies transferal of the
michael@0: // object's state to the target function.
michael@0: //
michael@0: // For these types, the ForwardType must not be a const reference, or a
michael@0: // reference.  A const reference is inappropriate, and would break const
michael@0: // correctness, because we are implementing a destructive move.  A non-const
michael@0: // reference cannot be used with temporaries which means the result of a
michael@0: // function or a cast would not be usable with Callback<> or Bind().
michael@0: //
michael@0: // TODO(ajwong): We might be able to use SFINAE to search for the existence of
michael@0: // a Pass() function in the type and avoid the whitelist in CallbackParamTraits
michael@0: // and CallbackForward.
michael@0: template <typename T, typename D>
michael@0: struct CallbackParamTraits<scoped_ptr<T, D> > {
michael@0:   typedef scoped_ptr<T, D> ForwardType;
michael@0:   typedef scoped_ptr<T, D> StorageType;
michael@0: };
michael@0: 
michael@0: template <typename T, typename R>
michael@0: struct CallbackParamTraits<scoped_ptr_malloc<T, R> > {
michael@0:   typedef scoped_ptr_malloc<T, R> ForwardType;
michael@0:   typedef scoped_ptr_malloc<T, R> StorageType;
michael@0: };
michael@0: 
michael@0: template <typename T>
michael@0: struct CallbackParamTraits<ScopedVector<T> > {
michael@0:   typedef ScopedVector<T> ForwardType;
michael@0:   typedef ScopedVector<T> StorageType;
michael@0: };
michael@0: 
michael@0: // CallbackForward() is a very limited simulation of C++11's std::forward()
michael@0: // used by the Callback/Bind system for a set of movable-but-not-copyable
michael@0: // types.  It is needed because forwarding a movable-but-not-copyable
michael@0: // argument to another function requires us to invoke the proper move
michael@0: // operator to create a rvalue version of the type.  The supported types are
michael@0: // whitelisted below as overloads of the CallbackForward() function. The
michael@0: // default template compiles out to be a no-op.
michael@0: //
michael@0: // In C++11, std::forward would replace all uses of this function.  However, it
michael@0: // is impossible to implement a general std::forward with C++11 due to a lack
michael@0: // of rvalue references.
michael@0: //
michael@0: // In addition to Callback/Bind, this is used by PostTaskAndReplyWithResult to
michael@0: // simulate std::forward() and forward the result of one Callback as a
michael@0: // parameter to another callback. This is to support Callbacks that return
michael@0: // the movable-but-not-copyable types whitelisted above.
michael@0: template <typename T>
michael@0: T& CallbackForward(T& t) { return t; }
michael@0: 
michael@0: template <typename T, typename D>
michael@0: scoped_ptr<T, D> CallbackForward(scoped_ptr<T, D>& p) { return p.Pass(); }
michael@0: 
michael@0: template <typename T, typename R>
michael@0: scoped_ptr_malloc<T, R> CallbackForward(scoped_ptr_malloc<T, R>& p) {
michael@0:   return p.Pass();
michael@0: }
michael@0: 
michael@0: template <typename T>
michael@0: ScopedVector<T> CallbackForward(ScopedVector<T>& p) { return p.Pass(); }
michael@0: 
michael@0: }  // namespace internal
michael@0: }  // namespace base
michael@0: 
michael@0: #endif  // BASE_CALLBACK_INTERNAL_H_