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