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