base/bind.h.pump

   1 $$ This is a pump file for generating file templates.  Pump is a python
   2 $$ script that is part of the Google Test suite of utilities.  Description
   3 $$ can be found here:
   4 $$
   5 $$ http://code.google.com/p/googletest/wiki/PumpManual
   6 $$
   7
   8 $$
   9 $$ MAX_ARITY controls the number of arguments that Bind() supports.
  10 $$ The amount of code, and more importantly, the number of template types
  11 $$ generated by pump grows at O(MAX_ARITY^2).
  12 $$
  13 $$ We tried going to 11 and found it imposed an extra 10 penalty on windows
  14 $$ cycle times compared to our original baseline of 6.
  15 $$
  16 $$ Currently 7 is chosen as a compromise between supporting a convenient
  17 $$ number of arguments and keeping compile times low.  At 7, we have 115
  18 $$ templates being generated by pump.
  19 $$
  20 $$ Be careful when adjusting this number.  If people find a need to bind
  21 $$ a larger number of arguments, consider refactoring the function to use
  22 $$ a param struct instead of raising the MAX_ARITY.
  23 $$
  24 $$ See http://crbug.com/98542 for more context.
  25 $$
  26 $var MAX_ARITY = 7
  27
  28 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
  29 // Use of this source code is governed by a BSD-style license that can be
  30 // found in the LICENSE file.
  31
  32 #ifndef BASE_BIND_H_
  33 #define BASE_BIND_H_
  34 #pragma once
  35
  36 #include "base/bind_internal.h"
  37 #include "base/callback_internal.h"
  38
  39 // See base/callback.h for how to use these functions. If reading the
  40 // implementation, before proceeding further, you should read the top
  41 // comment of base/bind_internal.h for a definition of common terms and
  42 // concepts.
  43 //
  44 // IMPLEMENTATION NOTE
  45 // Though Bind()'s result is meant to be stored in a Callback<> type, it
  46 // cannot actually return the exact type without requiring a large amount
  47 // of extra template specializations. The problem is that in order to
  48 // discern the correct specialization of Callback<>, Bind would need to
  49 // unwrap the function signature to determine the signature's arity, and
  50 // whether or not it is a method.
  51 //
  52 // Each unique combination of (arity, function_type, num_prebound) where
  53 // function_type is one of {function, method, const_method} would require
  54 // one specialization.  We eventually have to do a similar number of
  55 // specializations anyways in the implementation (see the Invoker<>,
  56 // classes).  However, it is avoidable in Bind if we return the result
  57 // via an indirection like we do below.
  58 //
  59 // TODO(ajwong): We might be able to avoid this now, but need to test.
  60 //
  61 // It is possible to move most of the COMPILE_ASSERT asserts into BindState<>,
  62 // but it feels a little nicer to have the asserts here so people do not
  63 // need to crack open bind_internal.h.  On the other hand, it makes Bind()
  64 // harder to read.
  65
  66 namespace base {
  67
  68 $range ARITY 0..MAX_ARITY
  69 $for ARITY [[
  70 $range ARG 1..ARITY
  71
  72 template <typename Functor[[]]
  73 $if ARITY > 0 [[, ]] $for ARG , [[typename P$(ARG)]]>
  74 base::Callback<
  75     typename internal::BindState<
  76         typename internal::FunctorTraits<Functor>::RunnableType,
  77         typename internal::FunctorTraits<Functor>::RunType,
  78         void($for ARG , [[typename internal::CallbackParamTraits<P$(ARG)>::StorageType]])>
  79             ::UnboundRunType>
  80 Bind(Functor functor
  81 $if ARITY > 0 [[, ]] $for ARG , [[const P$(ARG)& p$(ARG)]]) {
  82   // Typedefs for how to store and run the functor.
  83   typedef typename internal::FunctorTraits<Functor>::RunnableType RunnableType;
  84   typedef typename internal::FunctorTraits<Functor>::RunType RunType;
  85
  86   // Use RunnableType::RunType instead of RunType above because our
  87   // checks should below for bound references need to know what the actual
  88   // functor is going to interpret the argument as.
  89   typedef internal::FunctionTraits<typename RunnableType::RunType>
  90       BoundFunctorTraits;
  91
  92 $if ARITY > 0 [[
  93
  94   // Do not allow binding a non-const reference parameter. Non-const reference
  95   // parameters are disallowed by the Google style guide.  Also, binding a
  96   // non-const reference parameter can make for subtle bugs because the
  97   // invoked function will receive a reference to the stored copy of the
  98   // argument and not the original.
  99   COMPILE_ASSERT(
 100       !($for ARG || [[
 101 is_non_const_reference<typename BoundFunctorTraits::A$(ARG)Type>::value ]]),
 102       do_not_bind_functions_with_nonconst_ref);
 103
 104 ]]
 105
 106
 107 $for ARG [[
 108
 109
 110 $if ARG == 1 [[
 111   // For methods, we need to be careful for parameter 1.  We do not require
 112   // a scoped_refptr because BindState<> itself takes care of AddRef() for
 113   // methods. We also disallow binding of an array as the method's target
 114   // object.
 115   COMPILE_ASSERT(
 116       internal::HasIsMethodTag<RunnableType>::value ||
 117           !internal::NeedsScopedRefptrButGetsRawPtr<P$(ARG)>::value,
 118       p$(ARG)_is_refcounted_type_and_needs_scoped_refptr);
 119   COMPILE_ASSERT(!internal::HasIsMethodTag<RunnableType>::value ||
 120                      !is_array<P$(ARG)>::value,
 121                  first_bound_argument_to_method_cannot_be_array);
 122 ]] $else [[
 123   COMPILE_ASSERT(!internal::NeedsScopedRefptrButGetsRawPtr<P$(ARG)>::value,
 124                  p$(ARG)_is_refcounted_type_and_needs_scoped_refptr);
 125 ]]  $$ $if ARG
 126
 127 ]]  $$ $for ARG
 128
 129   typedef internal::BindState<RunnableType, RunType, [[]]
 130 void($for ARG , [[typename internal::CallbackParamTraits<P$(ARG)>::StorageType]])> [[]]
 131 BindState;
 132
 133
 134   return Callback<typename BindState::UnboundRunType>(
 135       new BindState(internal::MakeRunnable(functor)[[]]
 136 $if ARITY > 0 [[, ]] $for ARG , [[p$(ARG)]]));
 137 }
 138
 139 ]]  $$ for ARITY
 140
 141 }  // namespace base
 142
 143 #endif  // BASE_BIND_H_