base/bind.h

   1 // Copyright (c) 2011 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 BASE_BIND_H_
   6 #define BASE_BIND_H_
   7
   8 #include "base/bind_internal.h"
   9 #include "base/callback_internal.h"
  10
  11 // -----------------------------------------------------------------------------
  12 // Usage documentation
  13 // -----------------------------------------------------------------------------
  14 //
  15 // See base/callback.h for documentation.
  16 //
  17 //
  18 // -----------------------------------------------------------------------------
  19 // Implementation notes
  20 // -----------------------------------------------------------------------------
  21 //
  22 // If you're reading the implementation, before proceeding further, you should
  23 // read the top comment of base/bind_internal.h for a definition of common
  24 // terms and concepts.
  25 //
  26 // RETURN TYPES
  27 //
  28 // Though Bind()'s result is meant to be stored in a Callback<> type, it
  29 // cannot actually return the exact type without requiring a large amount
  30 // of extra template specializations. The problem is that in order to
  31 // discern the correct specialization of Callback<>, Bind would need to
  32 // unwrap the function signature to determine the signature's arity, and
  33 // whether or not it is a method.
  34 //
  35 // Each unique combination of (arity, function_type, num_prebound) where
  36 // function_type is one of {function, method, const_method} would require
  37 // one specialization.  We eventually have to do a similar number of
  38 // specializations anyways in the implementation (see the Invoker<>,
  39 // classes).  However, it is avoidable in Bind if we return the result
  40 // via an indirection like we do below.
  41 //
  42 // TODO(ajwong): We might be able to avoid this now, but need to test.
  43 //
  44 // It is possible to move most of the static_assert into BindState<>, but it
  45 // feels a little nicer to have the asserts here so people do not need to crack
  46 // open bind_internal.h.  On the other hand, it makes Bind() harder to read.
  47
  48 namespace base {
  49
  50 template <typename Functor>
  51 base::Callback<
  52     typename internal::BindState<
  53         typename internal::FunctorTraits<Functor>::RunnableType,
  54         typename internal::FunctorTraits<Functor>::RunType,
  55         void()>::UnboundRunType>
  56 Bind(Functor functor) {
  57   // Typedefs for how to store and run the functor.
  58   typedef typename internal::FunctorTraits<Functor>::RunnableType RunnableType;
  59   typedef typename internal::FunctorTraits<Functor>::RunType RunType;
  60
  61   typedef internal::BindState<RunnableType, RunType, void()> BindState;
  62
  63   return Callback<typename BindState::UnboundRunType>(
  64       new BindState(internal::MakeRunnable(functor)));
  65 }
  66
  67 template <typename Functor, typename... Args>
  68 base::Callback<
  69     typename internal::BindState<
  70         typename internal::FunctorTraits<Functor>::RunnableType,
  71         typename internal::FunctorTraits<Functor>::RunType,
  72         void(typename internal::CallbackParamTraits<Args>::StorageType...)>
  73             ::UnboundRunType>
  74 Bind(Functor functor, const Args&... args) {
  75   // Typedefs for how to store and run the functor.
  76   typedef typename internal::FunctorTraits<Functor>::RunnableType RunnableType;
  77   typedef typename internal::FunctorTraits<Functor>::RunType RunType;
  78
  79   // Use RunnableType::RunType instead of RunType above because our
  80   // checks should below for bound references need to know what the actual
  81   // functor is going to interpret the argument as.
  82   typedef typename RunnableType::RunType BoundRunType;
  83
  84   // Do not allow binding a non-const reference parameter. Non-const reference
  85   // parameters are disallowed by the Google style guide.  Also, binding a
  86   // non-const reference parameter can make for subtle bugs because the
  87   // invoked function will receive a reference to the stored copy of the
  88   // argument and not the original.
  89   static_assert(!internal::HasNonConstReferenceParam<BoundRunType>::value,
  90                 "do_not_bind_functions_with_nonconst_ref");
  91
  92   const bool is_method = internal::HasIsMethodTag<RunnableType>::value;
  93
  94   // For methods, we need to be careful for parameter 1.  We do not require
  95   // a scoped_refptr because BindState<> itself takes care of AddRef() for
  96   // methods. We also disallow binding of an array as the method's target
  97   // object.
  98   static_assert(!internal::BindsArrayToFirstArg<is_method, Args...>::value,
  99                 "first_bound_argument_to_method_cannot_be_array");
 100   static_assert(
 101       !internal::HasRefCountedParamAsRawPtr<is_method, Args...>::value,
 102       "a_parameter_is_refcounted_type_and_needs_scoped_refptr");
 103
 104   typedef internal::BindState<RunnableType, RunType,
 105       void(typename internal::CallbackParamTraits<Args>::StorageType...)>
 106       BindState;
 107
 108   return Callback<typename BindState::UnboundRunType>(
 109       new BindState(internal::MakeRunnable(functor), args...));
 110 }
 111
 112 }  // namespace base
 113
 114 #endif  // BASE_BIND_H_