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
 290 template <typename ReturnType, typename Runnable[[]]
 291 $if ARITY > 0 [[,]] $for ARG , [[typename A$(ARG)]]>
 292 struct InvokeHelper<false, ReturnType, Runnable,
 293     void($for ARG , [[A$(ARG)]])>  {
 294   static ReturnType MakeItSo(Runnable runnable[[]]
 295 $if ARITY > 0[[, ]] $for ARG , [[A$(ARG) a$(ARG)]]) {
 296     return runnable.Run($for ARG , [[CallbackForward(a$(ARG))]]);
 297   }
 298 };
 299
 300 template <typename Runnable[[]]
 301 $if ARITY > 0 [[,]] $for ARG , [[typename A$(ARG)]]>
 302 struct InvokeHelper<false, void, Runnable,
 303     void($for ARG , [[A$(ARG)]])>  {
 304   static void MakeItSo(Runnable runnable[[]]
 305 $if ARITY > 0[[, ]] $for ARG , [[A$(ARG) a$(ARG)]]) {
 306     runnable.Run($for ARG , [[CallbackForward(a$(ARG))]]);
 307   }
 308 };
 309
 310 $if ARITY > 0 [[
 311
 312 template <typename Runnable[[]], $for ARG , [[typename A$(ARG)]]>
 313 struct InvokeHelper<true, void, Runnable,
 314     void($for ARG , [[A$(ARG)]])>  {
 315   static void MakeItSo(Runnable runnable[[]]
 316 $if ARITY > 0[[, ]] $for ARG , [[A$(ARG) a$(ARG)]]) {
 317     if (!a1.get()) {
 318       return;
 319     }
 320
 321     runnable.Run($for ARG , [[CallbackForward(a$(ARG))]]);
 322   }
 323 };
 324
 325 ]]
 326
 327 ]] $$ for ARITY
 328
 329 #if !defined(_MSC_VER)
 330
 331 template <typename ReturnType, typename Runnable, typename ArgsType>
 332 struct InvokeHelper<true, ReturnType, Runnable, ArgsType> {
 333   // WeakCalls are only supported for functions with a void return type.
 334   // Otherwise, the function result would be undefined if the the WeakPtr<>
 335   // is invalidated.
 336   COMPILE_ASSERT(is_void<ReturnType>::value,
 337                  weak_ptrs_can_only_bind_to_methods_without_return_values);
 338 };
 339
 340 #endif
 341
 342 // Invoker<>
 343 //
 344 // See description at the top of the file.
 345 template <int NumBound, typename Storage, typename RunType>
 346 struct Invoker;
 347
 348 $for ARITY [[
 349
 350 $$ Number of bound arguments.
 351 $range BOUND 0..ARITY
 352 $for BOUND [[
 353
 354 $var UNBOUND = ARITY - BOUND
 355 $range ARG 1..ARITY
 356 $range BOUND_ARG 1..BOUND
 357 $range UNBOUND_ARG (ARITY - UNBOUND + 1)..ARITY
 358
 359 // Arity $(ARITY) -> $(UNBOUND).
 360 template <typename StorageType, typename R[[]]
 361 $if ARITY > 0 [[,]][[]]
 362 $for ARG , [[typename X$(ARG)]]>
 363 struct Invoker<$(BOUND), StorageType, R($for ARG , [[X$(ARG)]])> {
 364   typedef R(RunType)(BindStateBase*[[]]
 365 $if UNBOUND != 0 [[, ]]
 366 $for UNBOUND_ARG , [[typename CallbackParamTraits<X$(UNBOUND_ARG)>::ForwardType]]);
 367
 368   typedef R(UnboundRunType)($for UNBOUND_ARG , [[X$(UNBOUND_ARG)]]);
 369
 370   static R Run(BindStateBase* base[[]]
 371 $if UNBOUND != 0 [[, ]][[]]
 372 $for UNBOUND_ARG , [[
 373 typename CallbackParamTraits<X$(UNBOUND_ARG)>::ForwardType x$(UNBOUND_ARG)
 374 ]][[]]
 375 ) {
 376     StorageType* storage = static_cast<StorageType*>(base);
 377
 378     // Local references to make debugger stepping easier. If in a debugger,
 379     // you really want to warp ahead and step through the
 380     // InvokeHelper<>::MakeItSo() call below.
 381 $for BOUND_ARG
 382 [[
 383
 384     typedef typename StorageType::Bound$(BOUND_ARG)UnwrapTraits Bound$(BOUND_ARG)UnwrapTraits;
 385 ]]
 386
 387
 388 $for BOUND_ARG
 389 [[
 390
 391     typename Bound$(BOUND_ARG)UnwrapTraits::ForwardType x$(BOUND_ARG) =
 392         Bound$(BOUND_ARG)UnwrapTraits::Unwrap(storage->p$(BOUND_ARG)_);
 393 ]]
 394
 395     return InvokeHelper<StorageType::IsWeakCall::value, R,
 396            typename StorageType::RunnableType,
 397            void(
 398 $for BOUND_ARG , [[
 399 typename Bound$(BOUND_ARG)UnwrapTraits::ForwardType
 400 ]]
 401
 402 $if UNBOUND > 0 [[$if BOUND > 0 [[, ]]]][[]]
 403
 404 $for UNBOUND_ARG , [[
 405 typename CallbackParamTraits<X$(UNBOUND_ARG)>::ForwardType x$(UNBOUND_ARG)
 406 ]]
 407 )>
 408                ::MakeItSo(storage->runnable_
 409 $if ARITY > 0[[, ]] $for ARG , [[CallbackForward(x$(ARG))]]);
 410   }
 411 };
 412
 413 ]] $$ for BOUND
 414 ]] $$ for ARITY
 415
 416
 417 // BindState<>
 418 //
 419 // This stores all the state passed into Bind() and is also where most
 420 // of the template resolution magic occurs.
 421 //
 422 // Runnable is the functor we are binding arguments to.
 423 // RunType is type of the Run() function that the Invoker<> should use.
 424 // Normally, this is the same as the RunType of the Runnable, but it can
 425 // be different if an adapter like IgnoreResult() has been used.
 426 //
 427 // BoundArgsType contains the storage type for all the bound arguments by
 428 // (ab)using a function type.
 429 template <typename Runnable, typename RunType, typename BoundArgsType>
 430 struct BindState;
 431
 432 $for ARITY [[
 433 $range ARG 1..ARITY
 434
 435 template <typename Runnable, typename RunType[[]]
 436 $if ARITY > 0[[, ]] $for ARG , [[typename P$(ARG)]]>
 437 struct BindState<Runnable, RunType, void($for ARG , [[P$(ARG)]])> : public BindStateBase {
 438   typedef Runnable RunnableType;
 439
 440 $if ARITY > 0 [[
 441   typedef IsWeakMethod<HasIsMethodTag<Runnable>::value, P1> IsWeakCall;
 442 ]] $else [[
 443   typedef false_type IsWeakCall;
 444 ]]
 445
 446   typedef Invoker<$(ARITY), BindState, RunType> InvokerType;
 447   typedef typename InvokerType::UnboundRunType UnboundRunType;
 448
 449 $if ARITY > 0 [[
 450
 451   // Convenience typedefs for bound argument types.
 452
 453 $for ARG [[
 454   typedef UnwrapTraits<P$(ARG)> Bound$(ARG)UnwrapTraits;
 455
 456 ]]  $$ for ARG
 457
 458
 459 ]]  $$ if ARITY > 0
 460
 461 $$ The extra [[ ]] is needed to massage spacing. Silly pump.py.
 462 [[  ]]$if ARITY == 0 [[explicit ]]BindState(const Runnable& runnable
 463 $if ARITY > 0 [[, ]] $for ARG , [[const P$(ARG)& p$(ARG)]])
 464       : runnable_(runnable)[[]]
 465 $if ARITY == 0 [[
 466  {
 467
 468 ]] $else [[
 469 , $for ARG , [[
 470
 471         p$(ARG)_(p$(ARG))
 472 ]] {
 473     MaybeRefcount<HasIsMethodTag<Runnable>::value, P1>::AddRef(p1_);
 474
 475 ]]
 476   }
 477
 478   virtual ~BindState() {
 479 $if ARITY > 0 [[
 480     MaybeRefcount<HasIsMethodTag<Runnable>::value, P1>::Release(p1_);
 481 ]]
 482   }
 483
 484   RunnableType runnable_;
 485
 486 $for ARG [[
 487   P$(ARG) p$(ARG)_;
 488
 489 ]]
 490 };
 491
 492 ]] $$ for ARITY
 493
 494 }  // namespace internal
 495 }  // namespace base
 496
 497 #endif  // BASE_BIND_INTERNAL_H_