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