src/base/bind_internal.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 $$ See comment for MAX_ARITY in base/bind.h.pump.
   9 $var MAX_ARITY = 7
  10 $range ARITY 0..MAX_ARITY
  11
  12 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
  13 // Use of this source code is governed by a BSD-style license that can be
  14 // found in the LICENSE file.
  15
  16 #ifndef BASE_BIND_INTERNAL_H_
  17 #define BASE_BIND_INTERNAL_H_
  18
  19 #include "base/bind_helpers.h"
  20 #include "base/callback_internal.h"
  21 #include "base/memory/raw_scoped_refptr_mismatch_checker.h"
  22 #include "base/memory/weak_ptr.h"
  23 #include "base/template_util.h"
  24 #include "build/build_config.h"
  25
  26 #if defined(OS_WIN)
  27 #include "base/bind_internal_win.h"
  28 #endif
  29
  30 namespace base {
  31 namespace internal {
  32
  33 // See base/callback.h for user documentation.
  34 //
  35 //
  36 // CONCEPTS:
  37 //  Runnable -- A type (really a type class) that has a single Run() method
  38 //              and a RunType typedef that corresponds to the type of Run().
  39 //              A Runnable can declare that it should treated like a method
  40 //              call by including a typedef named IsMethod.  The value of
  41 //              this typedef is NOT inspected, only the existence.  When a
  42 //              Runnable declares itself a method, Bind() will enforce special
  43 //              refcounting + WeakPtr handling semantics for the first
  44 //              parameter which is expected to be an object.
  45 //  Functor -- A copyable type representing something that should be called.
  46 //             All function pointers, Callback<>, and Runnables are functors
  47 //             even if the invocation syntax differs.
  48 //  RunType -- A function type (as opposed to function _pointer_ type) for
  49 //             a Run() function.  Usually just a convenience typedef.
  50 //  (Bound)ArgsType -- A function type that is being (ab)used to store the
  51 //                     types of set of arguments.  The "return" type is always
  52 //                     void here.  We use this hack so that we do not need
  53 //                     a new type name for each arity of type. (eg.,
  54 //                     BindState1, BindState2).  This makes forward
  55 //                     declarations and friending much much easier.
  56 //
  57 // Types:
  58 //  RunnableAdapter<> -- Wraps the various "function" pointer types into an
  59 //                       object that adheres to the Runnable interface.
  60 //                       There are |3*ARITY| RunnableAdapter types.
  61 //  FunctionTraits<> -- Type traits that unwrap a function signature into a
  62 //                      a set of easier to use typedefs.  Used mainly for
  63 //                      compile time asserts.
  64 //                      There are |ARITY| FunctionTraits types.
  65 //  ForceVoidReturn<> -- Helper class for translating function signatures to
  66 //                       equivalent forms with a "void" return type.
  67 //                    There are |ARITY| ForceVoidReturn types.
  68 //  FunctorTraits<> -- Type traits used determine the correct RunType and
  69 //                     RunnableType for a Functor.  This is where function
  70 //                     signature adapters are applied.
  71 //                    There are |ARITY| ForceVoidReturn types.
  72 //  MakeRunnable<> -- Takes a Functor and returns an object in the Runnable
  73 //                    type class that represents the underlying Functor.
  74 //                    There are |O(1)| MakeRunnable types.
  75 //  InvokeHelper<> -- Take a Runnable + arguments and actully invokes it.
  76 //                    Handle the differing syntaxes needed for WeakPtr<> support,
  77 //                    and for ignoring return values.  This is separate from
  78 //                    Invoker to avoid creating multiple version of Invoker<>
  79 //                    which grows at O(n^2) with the arity.
  80 //                    There are |k*ARITY| InvokeHelper types.
  81 //  Invoker<> -- Unwraps the curried parameters and executes the Runnable.
  82 //               There are |(ARITY^2 + ARITY)/2| Invoketypes.
  83 //  BindState<> -- Stores the curried parameters, and is the main entry point
  84 //                 into the Bind() system, doing most of the type resolution.
  85 //                 There are ARITY BindState types.
  86
  87 // RunnableAdapter<>
  88 //
  89 // The RunnableAdapter<> templates provide a uniform interface for invoking
  90 // a function pointer, method pointer, or const method pointer. The adapter
  91 // exposes a Run() method with an appropriate signature. Using this wrapper
  92 // allows for writing code that supports all three pointer types without
  93 // undue repetition.  Without it, a lot of code would need to be repeated 3
  94 // times.
  95 //
  96 // For method pointers and const method pointers the first argument to Run()
  97 // is considered to be the received of the method.  This is similar to STL's
  98 // mem_fun().
  99 //
 100 // This class also exposes a RunType typedef that is the function type of the
 101 // Run() function.
 102 //
 103 // If and only if the wrapper contains a method or const method pointer, an
 104 // IsMethod typedef is exposed.  The existence of this typedef (NOT the value)
 105 // marks that the wrapper should be considered a method wrapper.
 106
 107 template <typename Functor>
 108 class RunnableAdapter;
 109
 110 $for ARITY [[
 111 $range ARG 1..ARITY
 112
 113 // Function: Arity $(ARITY).
 114 template <typename R[[]]
 115 $if ARITY > 0[[, ]] $for ARG , [[typename A$(ARG)]]>
 116 class RunnableAdapter<R(*)($for ARG , [[A$(ARG)]])> {
 117  public:
 118   typedef R (RunType)($for ARG , [[A$(ARG)]]);
 119
 120   explicit RunnableAdapter(R(*function)($for ARG , [[A$(ARG)]]))
 121       : function_(function) {
 122   }
 123
 124   R Run($for ARG , [[typename CallbackParamTraits<A$(ARG)>::ForwardType a$(ARG)]]) {
 125     return function_($for ARG , [[CallbackForward(a$(ARG))]]);
 126   }
 127
 128  private:
 129   R (*function_)($for ARG , [[A$(ARG)]]);
 130 };
 131
 132 // Method: Arity $(ARITY).
 133 template <typename R, typename T[[]]
 134 $if ARITY > 0[[, ]] $for ARG , [[typename A$(ARG)]]>
 135 class RunnableAdapter<R(T::*)($for ARG , [[A$(ARG)]])> {
 136  public:
 137   typedef R (RunType)(T*[[]]
 138 $if ARITY > 0[[, ]] $for ARG , [[A$(ARG)]]);
 139   typedef true_type IsMethod;
 140
 141   explicit RunnableAdapter(R(T::*method)($for ARG , [[A$(ARG)]]))
 142       : method_(method) {
 143   }
 144
 145   R Run(T* object[[]]
 146 $if ARITY > 0[[, ]]  $for ARG, [[typename CallbackParamTraits<A$(ARG)>::ForwardType a$(ARG)]]) {
 147     return (object->*method_)($for ARG , [[CallbackForward(a$(ARG))]]);
 148   }
 149
 150  private:
 151   R (T::*method_)($for ARG , [[A$(ARG)]]);
 152 };
 153
 154 // Const Method: Arity $(ARITY).
 155 template <typename R, typename T[[]]
 156 $if ARITY > 0[[, ]] $for ARG , [[typename A$(ARG)]]>
 157 class RunnableAdapter<R(T::*)($for ARG , [[A$(ARG)]]) const> {
 158  public:
 159   typedef R (RunType)(const T*[[]]
 160 $if ARITY > 0[[, ]] $for ARG , [[A$(ARG)]]);
 161   typedef true_type IsMethod;
 162
 163   explicit RunnableAdapter(R(T::*method)($for ARG , [[A$(ARG)]]) const)
 164       : method_(method) {
 165   }
 166
 167   R Run(const T* object[[]]
 168 $if ARITY > 0[[, ]]  $for ARG, [[typename CallbackParamTraits<A$(ARG)>::ForwardType a$(ARG)]]) {
 169     return (object->*method_)($for ARG , [[CallbackForward(a$(ARG))]]);
 170   }
 171
 172  private:
 173   R (T::*method_)($for ARG , [[A$(ARG)]]) const;
 174 };
 175
 176 ]]  $$ for ARITY
 177
 178
 179 // FunctionTraits<>
 180 //
 181 // Breaks a function signature apart into typedefs for easier introspection.
 182 template <typename Sig>
 183 struct FunctionTraits;
 184
 185 $for ARITY [[
 186 $range ARG 1..ARITY
 187
 188 template <typename R[[]]
 189 $if ARITY > 0[[, ]] $for ARG , [[typename A$(ARG)]]>
 190 struct FunctionTraits<R($for ARG , [[A$(ARG)]])> {
 191   typedef R ReturnType;
 192 $for ARG [[
 193
 194   typedef A$(ARG) A$(ARG)Type;
 195 ]]
 196
 197 };
 198
 199 ]]
 200
 201
 202 // ForceVoidReturn<>
 203 //
 204 // Set of templates that support forcing the function return type to void.
 205 template <typename Sig>
 206 struct ForceVoidReturn;
 207
 208 $for ARITY [[
 209 $range ARG 1..ARITY
 210
 211 template <typename R[[]]
 212 $if ARITY > 0[[, ]] $for ARG , [[typename A$(ARG)]]>
 213 struct ForceVoidReturn<R($for ARG , [[A$(ARG)]])> {
 214   typedef void(RunType)($for ARG , [[A$(ARG)]]);
 215 };
 216
 217 ]]  $$ for ARITY
 218
 219
 220 // FunctorTraits<>
 221 //
 222 // See description at top of file.
 223 template <typename T>
 224 struct FunctorTraits {
 225   typedef RunnableAdapter<T> RunnableType;
 226   typedef typename RunnableType::RunType RunType;
 227 };
 228
 229 template <typename T>
 230 struct FunctorTraits<IgnoreResultHelper<T> > {
 231   typedef typename FunctorTraits<T>::RunnableType RunnableType;
 232   typedef typename ForceVoidReturn<
 233       typename RunnableType::RunType>::RunType RunType;
 234 };
 235
 236 template <typename T>
 237 struct FunctorTraits<Callback<T> > {
 238   typedef Callback<T> RunnableType;
 239   typedef typename Callback<T>::RunType RunType;
 240 };
 241
 242
 243 // MakeRunnable<>
 244 //
 245 // Converts a passed in functor to a RunnableType using type inference.
 246
 247 template <typename T>
 248 typename FunctorTraits<T>::RunnableType MakeRunnable(const T& t) {
 249   return RunnableAdapter<T>(t);
 250 }
 251
 252 template <typename T>
 253 typename FunctorTraits<T>::RunnableType
 254 MakeRunnable(const IgnoreResultHelper<T>& t) {
 255   return MakeRunnable(t.functor_);
 256 }
 257
 258 template <typename T>
 259 const typename FunctorTraits<Callback<T> >::RunnableType&
 260 MakeRunnable(const Callback<T>& t) {
 261   DCHECK(!t.is_null());
 262   return t;
 263 }
 264
 265
 266 // InvokeHelper<>
 267 //
 268 // There are 3 logical InvokeHelper<> specializations: normal, void-return,
 269 // WeakCalls.
 270 //
 271 // The normal type just calls the underlying runnable.
 272 //
 273 // We need a InvokeHelper to handle void return types in order to support
 274 // IgnoreResult().  Normally, if the Runnable's RunType had a void return,
 275 // the template system would just accept "return functor.Run()" ignoring
 276 // the fact that a void function is being used with return. This piece of
 277 // sugar breaks though when the Runnable's RunType is not void.  Thus, we
 278 // need a partial specialization to change the syntax to drop the "return"
 279 // from the invocation call.
 280 //
 281 // WeakCalls similarly need special syntax that is applied to the first
 282 // argument to check if they should no-op themselves.
 283 template <bool IsWeakCall, typename ReturnType, typename Runnable,
 284           typename ArgsType>
 285 struct InvokeHelper;
 286
 287 $for ARITY [[
 288 $range ARG 1..ARITY
 289 $range WEAKCALL_ARG 2..ARITY
 290
 291 template <typename ReturnType, typename Runnable[[]]
 292 $if ARITY > 0 [[,]] $for ARG , [[typename A$(ARG)]]>
 293 struct InvokeHelper<false, ReturnType, Runnable,
 294     void($for ARG , [[A$(ARG)]])>  {
 295   static ReturnType MakeItSo(Runnable runnable[[]]
 296 $if ARITY > 0[[, ]] $for ARG , [[A$(ARG) a$(ARG)]]) {
 297     return runnable.Run($for ARG , [[CallbackForward(a$(ARG))]]);
 298   }
 299 };
 300
 301 template <typename Runnable[[]]
 302 $if ARITY > 0 [[,]] $for ARG , [[typename A$(ARG)]]>
 303 struct InvokeHelper<false, void, Runnable,
 304     void($for ARG , [[A$(ARG)]])>  {
 305   static void MakeItSo(Runnable runnable[[]]
 306 $if ARITY > 0[[, ]] $for ARG , [[A$(ARG) a$(ARG)]]) {
 307     runnable.Run($for ARG , [[CallbackForward(a$(ARG))]]);
 308   }
 309 };
 310
 311 $if ARITY > 0 [[
 312
 313 template <typename Runnable[[]], typename BoundWeakPtr
 314 $if ARITY > 1[[, ]] $for WEAKCALL_ARG , [[typename A$(WEAKCALL_ARG)]]>
 315 struct InvokeHelper<true, void, Runnable,
 316     void(BoundWeakPtr
 317 $if ARITY > 1[[, ]] $for WEAKCALL_ARG , [[A$(WEAKCALL_ARG)]])>  {
 318   static void MakeItSo(Runnable runnable, BoundWeakPtr weak_ptr
 319 $if ARITY > 1[[, ]] $for WEAKCALL_ARG , [[A$(WEAKCALL_ARG) a$(WEAKCALL_ARG)]]) {
 320     if (!weak_ptr.get()) {
 321       return;
 322     }
 323     runnable.Run(weak_ptr.get()
 324 $if ARITY > 1[[, ]] $for WEAKCALL_ARG , [[CallbackForward(a$(WEAKCALL_ARG))]]);
 325   }
 326 };
 327
 328 ]]
 329
 330 ]] $$ for ARITY
 331
 332 #if !defined(_MSC_VER)
 333
 334 template <typename ReturnType, typename Runnable, typename ArgsType>
 335 struct InvokeHelper<true, ReturnType, Runnable, ArgsType> {
 336   // WeakCalls are only supported for functions with a void return type.
 337   // Otherwise, the function result would be undefined if the the WeakPtr<>
 338   // is invalidated.
 339   COMPILE_ASSERT(is_void<ReturnType>::value,
 340                  weak_ptrs_can_only_bind_to_methods_without_return_values);
 341 };
 342
 343 #endif
 344
 345 // Invoker<>
 346 //
 347 // See description at the top of the file.
 348 template <int NumBound, typename Storage, typename RunType>
 349 struct Invoker;
 350
 351 $for ARITY [[
 352
 353 $$ Number of bound arguments.
 354 $range BOUND 0..ARITY
 355 $for BOUND [[
 356
 357 $var UNBOUND = ARITY - BOUND
 358 $range ARG 1..ARITY
 359 $range BOUND_ARG 1..BOUND
 360 $range UNBOUND_ARG (ARITY - UNBOUND + 1)..ARITY
 361
 362 // Arity $(ARITY) -> $(UNBOUND).
 363 template <typename StorageType, typename R[[]]
 364 $if ARITY > 0 [[,]][[]]
 365 $for ARG , [[typename X$(ARG)]]>
 366 struct Invoker<$(BOUND), StorageType, R($for ARG , [[X$(ARG)]])> {
 367   typedef R(RunType)(BindStateBase*[[]]
 368 $if UNBOUND != 0 [[, ]]
 369 $for UNBOUND_ARG , [[typename CallbackParamTraits<X$(UNBOUND_ARG)>::ForwardType]]);
 370
 371   typedef R(UnboundRunType)($for UNBOUND_ARG , [[X$(UNBOUND_ARG)]]);
 372
 373   static R Run(BindStateBase* base[[]]
 374 $if UNBOUND != 0 [[, ]][[]]
 375 $for UNBOUND_ARG , [[
 376 typename CallbackParamTraits<X$(UNBOUND_ARG)>::ForwardType x$(UNBOUND_ARG)
 377 ]][[]]
 378 ) {
 379     StorageType* storage = static_cast<StorageType*>(base);
 380
 381     // Local references to make debugger stepping easier. If in a debugger,
 382     // you really want to warp ahead and step through the
 383     // InvokeHelper<>::MakeItSo() call below.
 384 $for BOUND_ARG
 385 [[
 386
 387     typedef typename StorageType::Bound$(BOUND_ARG)UnwrapTraits Bound$(BOUND_ARG)UnwrapTraits;
 388 ]]
 389
 390
 391 $for BOUND_ARG
 392 [[
 393
 394     typename Bound$(BOUND_ARG)UnwrapTraits::ForwardType x$(BOUND_ARG) =
 395         Bound$(BOUND_ARG)UnwrapTraits::Unwrap(storage->p$(BOUND_ARG)_);
 396 ]]
 397
 398     return InvokeHelper<StorageType::IsWeakCall::value, R,
 399            typename StorageType::RunnableType,
 400            void(
 401 $for BOUND_ARG , [[
 402 typename Bound$(BOUND_ARG)UnwrapTraits::ForwardType
 403 ]]
 404
 405 $if UNBOUND > 0 [[$if BOUND > 0 [[, ]]]][[]]
 406
 407 $for UNBOUND_ARG , [[
 408 typename CallbackParamTraits<X$(UNBOUND_ARG)>::ForwardType x$(UNBOUND_ARG)
 409 ]]
 410 )>
 411                ::MakeItSo(storage->runnable_
 412 $if ARITY > 0[[, ]] $for ARG , [[CallbackForward(x$(ARG))]]);
 413   }
 414 };
 415
 416 ]] $$ for BOUND
 417 ]] $$ for ARITY
 418
 419
 420 // BindState<>
 421 //
 422 // This stores all the state passed into Bind() and is also where most
 423 // of the template resolution magic occurs.
 424 //
 425 // Runnable is the functor we are binding arguments to.
 426 // RunType is type of the Run() function that the Invoker<> should use.
 427 // Normally, this is the same as the RunType of the Runnable, but it can
 428 // be different if an adapter like IgnoreResult() has been used.
 429 //
 430 // BoundArgsType contains the storage type for all the bound arguments by
 431 // (ab)using a function type.
 432 template <typename Runnable, typename RunType, typename BoundArgsType>
 433 struct BindState;
 434
 435 $for ARITY [[
 436 $range ARG 1..ARITY
 437
 438 template <typename Runnable, typename RunType[[]]
 439 $if ARITY > 0[[, ]] $for ARG , [[typename P$(ARG)]]>
 440 struct BindState<Runnable, RunType, void($for ARG , [[P$(ARG)]])> : public BindStateBase {
 441   typedef Runnable RunnableType;
 442
 443 $if ARITY > 0 [[
 444   typedef IsWeakMethod<HasIsMethodTag<Runnable>::value, P1> IsWeakCall;
 445 ]] $else [[
 446   typedef false_type IsWeakCall;
 447 ]]
 448
 449   typedef Invoker<$(ARITY), BindState, RunType> InvokerType;
 450   typedef typename InvokerType::UnboundRunType UnboundRunType;
 451
 452 $if ARITY > 0 [[
 453
 454   // Convenience typedefs for bound argument types.
 455
 456 $for ARG [[
 457   typedef UnwrapTraits<P$(ARG)> Bound$(ARG)UnwrapTraits;
 458
 459 ]]  $$ for ARG
 460
 461
 462 ]]  $$ if ARITY > 0
 463
 464 $$ The extra [[ ]] is needed to massage spacing. Silly pump.py.
 465 [[  ]]$if ARITY == 0 [[explicit ]]BindState(const Runnable& runnable
 466 $if ARITY > 0 [[, ]] $for ARG , [[const P$(ARG)& p$(ARG)]])
 467       : runnable_(runnable)[[]]
 468 $if ARITY == 0 [[
 469  {
 470
 471 ]] $else [[
 472 , $for ARG , [[
 473
 474         p$(ARG)_(p$(ARG))
 475 ]] {
 476     MaybeRefcount<HasIsMethodTag<Runnable>::value, P1>::AddRef(p1_);
 477
 478 ]]
 479   }
 480
 481   virtual ~BindState() {
 482 $if ARITY > 0 [[
 483     MaybeRefcount<HasIsMethodTag<Runnable>::value, P1>::Release(p1_);
 484 ]]
 485   }
 486
 487   RunnableType runnable_;
 488
 489 $for ARG [[
 490   P$(ARG) p$(ARG)_;
 491
 492 ]]
 493 };
 494
 495 ]] $$ for ARITY
 496
 497 }  // namespace internal
 498 }  // namespace base
 499
 500 #endif  // BASE_BIND_INTERNAL_H_