bind_helpers.h revision a36e5920737c6adbddd3e43b760e5de8431db6e0
1// Copyright (c) 2011 The Chromium Authors. All rights reserved. 2// Use of this source code is governed by a BSD-style license that can be 3// found in the LICENSE file. 4 5// This defines a set of argument wrappers and related factory methods that 6// can be used specify the refcounting and reference semantics of arguments 7// that are bound by the Bind() function in base/bind.h. 8// 9// It also defines a set of simple functions and utilities that people want 10// when using Callback<> and Bind(). 11// 12// 13// ARGUMENT BINDING WRAPPERS 14// 15// The wrapper functions are base::Unretained(), base::Owned(), bass::Passed(), 16// base::ConstRef(), and base::IgnoreResult(). 17// 18// Unretained() allows Bind() to bind a non-refcounted class, and to disable 19// refcounting on arguments that are refcounted objects. 20// 21// Owned() transfers ownership of an object to the Callback resulting from 22// bind; the object will be deleted when the Callback is deleted. 23// 24// Passed() is for transferring movable-but-not-copyable types (eg. scoped_ptr) 25// through a Callback. Logically, this signifies a destructive transfer of 26// the state of the argument into the target function. Invoking 27// Callback::Run() twice on a Callback that was created with a Passed() 28// argument will CHECK() because the first invocation would have already 29// transferred ownership to the target function. 30// 31// ConstRef() allows binding a constant reference to an argument rather 32// than a copy. 33// 34// IgnoreResult() is used to adapt a function or Callback with a return type to 35// one with a void return. This is most useful if you have a function with, 36// say, a pesky ignorable bool return that you want to use with PostTask or 37// something else that expect a Callback with a void return. 38// 39// EXAMPLE OF Unretained(): 40// 41// class Foo { 42// public: 43// void func() { cout << "Foo:f" << endl; } 44// }; 45// 46// // In some function somewhere. 47// Foo foo; 48// Closure foo_callback = 49// Bind(&Foo::func, Unretained(&foo)); 50// foo_callback.Run(); // Prints "Foo:f". 51// 52// Without the Unretained() wrapper on |&foo|, the above call would fail 53// to compile because Foo does not support the AddRef() and Release() methods. 54// 55// 56// EXAMPLE OF Owned(): 57// 58// void foo(int* arg) { cout << *arg << endl } 59// 60// int* pn = new int(1); 61// Closure foo_callback = Bind(&foo, Owned(pn)); 62// 63// foo_callback.Run(); // Prints "1" 64// foo_callback.Run(); // Prints "1" 65// *n = 2; 66// foo_callback.Run(); // Prints "2" 67// 68// foo_callback.Reset(); // |pn| is deleted. Also will happen when 69// // |foo_callback| goes out of scope. 70// 71// Without Owned(), someone would have to know to delete |pn| when the last 72// reference to the Callback is deleted. 73// 74// 75// EXAMPLE OF ConstRef(): 76// 77// void foo(int arg) { cout << arg << endl } 78// 79// int n = 1; 80// Closure no_ref = Bind(&foo, n); 81// Closure has_ref = Bind(&foo, ConstRef(n)); 82// 83// no_ref.Run(); // Prints "1" 84// has_ref.Run(); // Prints "1" 85// 86// n = 2; 87// no_ref.Run(); // Prints "1" 88// has_ref.Run(); // Prints "2" 89// 90// Note that because ConstRef() takes a reference on |n|, |n| must outlive all 91// its bound callbacks. 92// 93// 94// EXAMPLE OF IgnoreResult(): 95// 96// int DoSomething(int arg) { cout << arg << endl; } 97// 98// // Assign to a Callback with a void return type. 99// Callback<void(int)> cb = Bind(IgnoreResult(&DoSomething)); 100// cb->Run(1); // Prints "1". 101// 102// // Prints "1" on |ml|. 103// ml->PostTask(FROM_HERE, Bind(IgnoreResult(&DoSomething), 1); 104// 105// 106// EXAMPLE OF Passed(): 107// 108// void TakesOwnership(scoped_ptr<Foo> arg) { } 109// scoped_ptr<Foo> CreateFoo() { return scoped_ptr<Foo>(new Foo()); } 110// 111// scoped_ptr<Foo> f(new Foo()); 112// 113// // |cb| is given ownership of Foo(). |f| is now NULL. 114// // You can use f.Pass() in place of &f, but it's more verbose. 115// Closure cb = Bind(&TakesOwnership, Passed(&f)); 116// 117// // Run was never called so |cb| still owns Foo() and deletes 118// // it on Reset(). 119// cb.Reset(); 120// 121// // |cb| is given a new Foo created by CreateFoo(). 122// cb = Bind(&TakesOwnership, Passed(CreateFoo())); 123// 124// // |arg| in TakesOwnership() is given ownership of Foo(). |cb| 125// // no longer owns Foo() and, if reset, would not delete Foo(). 126// cb.Run(); // Foo() is now transferred to |arg| and deleted. 127// cb.Run(); // This CHECK()s since Foo() already been used once. 128// 129// Passed() is particularly useful with PostTask() when you are transferring 130// ownership of an argument into a task, but don't necessarily know if the 131// task will always be executed. This can happen if the task is cancellable 132// or if it is posted to a MessageLoopProxy. 133// 134// 135// SIMPLE FUNCTIONS AND UTILITIES. 136// 137// DoNothing() - Useful for creating a Closure that does nothing when called. 138// DeletePointer<T>() - Useful for creating a Closure that will delete a 139// pointer when invoked. Only use this when necessary. 140// In most cases MessageLoop::DeleteSoon() is a better 141// fit. 142// ScopedClosureRunner - Scoper object that runs the wrapped closure when it 143// goes out of scope. It's conceptually similar to 144// scoped_ptr<> but calls Run() instead of deleting 145// the pointer. 146 147#ifndef BASE_BIND_HELPERS_H_ 148#define BASE_BIND_HELPERS_H_ 149 150#include "base/basictypes.h" 151#include "base/callback.h" 152#include "base/memory/weak_ptr.h" 153#include "base/template_util.h" 154 155namespace base { 156namespace internal { 157 158// Use the Substitution Failure Is Not An Error (SFINAE) trick to inspect T 159// for the existence of AddRef() and Release() functions of the correct 160// signature. 161// 162// http://en.wikipedia.org/wiki/Substitution_failure_is_not_an_error 163// http://stackoverflow.com/questions/257288/is-it-possible-to-write-a-c-template-to-check-for-a-functions-existence 164// http://stackoverflow.com/questions/4358584/sfinae-approach-comparison 165// http://stackoverflow.com/questions/1966362/sfinae-to-check-for-inherited-member-functions 166// 167// The last link in particular show the method used below. 168// 169// For SFINAE to work with inherited methods, we need to pull some extra tricks 170// with multiple inheritance. In the more standard formulation, the overloads 171// of Check would be: 172// 173// template <typename C> 174// Yes NotTheCheckWeWant(Helper<&C::TargetFunc>*); 175// 176// template <typename C> 177// No NotTheCheckWeWant(...); 178// 179// static const bool value = sizeof(NotTheCheckWeWant<T>(0)) == sizeof(Yes); 180// 181// The problem here is that template resolution will not match 182// C::TargetFunc if TargetFunc does not exist directly in C. That is, if 183// TargetFunc in inherited from an ancestor, &C::TargetFunc will not match, 184// |value| will be false. This formulation only checks for whether or 185// not TargetFunc exist directly in the class being introspected. 186// 187// To get around this, we play a dirty trick with multiple inheritance. 188// First, We create a class BaseMixin that declares each function that we 189// want to probe for. Then we create a class Base that inherits from both T 190// (the class we wish to probe) and BaseMixin. Note that the function 191// signature in BaseMixin does not need to match the signature of the function 192// we are probing for; thus it's easiest to just use void(void). 193// 194// Now, if TargetFunc exists somewhere in T, then &Base::TargetFunc has an 195// ambiguous resolution between BaseMixin and T. This lets us write the 196// following: 197// 198// template <typename C> 199// No GoodCheck(Helper<&C::TargetFunc>*); 200// 201// template <typename C> 202// Yes GoodCheck(...); 203// 204// static const bool value = sizeof(GoodCheck<Base>(0)) == sizeof(Yes); 205// 206// Notice here that the variadic version of GoodCheck() returns Yes here 207// instead of No like the previous one. Also notice that we calculate |value| 208// by specializing GoodCheck() on Base instead of T. 209// 210// We've reversed the roles of the variadic, and Helper overloads. 211// GoodCheck(Helper<&C::TargetFunc>*), when C = Base, fails to be a valid 212// substitution if T::TargetFunc exists. Thus GoodCheck<Base>(0) will resolve 213// to the variadic version if T has TargetFunc. If T::TargetFunc does not 214// exist, then &C::TargetFunc is not ambiguous, and the overload resolution 215// will prefer GoodCheck(Helper<&C::TargetFunc>*). 216// 217// This method of SFINAE will correctly probe for inherited names, but it cannot 218// typecheck those names. It's still a good enough sanity check though. 219// 220// Works on gcc-4.2, gcc-4.4, and Visual Studio 2008. 221// 222// TODO(ajwong): Move to ref_counted.h or template_util.h when we've vetted 223// this works well. 224// 225// TODO(ajwong): Make this check for Release() as well. 226// See http://crbug.com/82038. 227template <typename T> 228class SupportsAddRefAndRelease { 229 typedef char Yes[1]; 230 typedef char No[2]; 231 232 struct BaseMixin { 233 void AddRef(); 234 }; 235 236// MSVC warns when you try to use Base if T has a private destructor, the 237// common pattern for refcounted types. It does this even though no attempt to 238// instantiate Base is made. We disable the warning for this definition. 239#if defined(OS_WIN) 240#pragma warning(push) 241#pragma warning(disable:4624) 242#endif 243 struct Base : public T, public BaseMixin { 244 }; 245#if defined(OS_WIN) 246#pragma warning(pop) 247#endif 248 249 template <void(BaseMixin::*)(void)> struct Helper {}; 250 251 template <typename C> 252 static No& Check(Helper<&C::AddRef>*); 253 254 template <typename > 255 static Yes& Check(...); 256 257 public: 258 static const bool value = sizeof(Check<Base>(0)) == sizeof(Yes); 259}; 260 261// Helpers to assert that arguments of a recounted type are bound with a 262// scoped_refptr. 263template <bool IsClasstype, typename T> 264struct UnsafeBindtoRefCountedArgHelper : false_type { 265}; 266 267template <typename T> 268struct UnsafeBindtoRefCountedArgHelper<true, T> 269 : integral_constant<bool, SupportsAddRefAndRelease<T>::value> { 270}; 271 272template <typename T> 273struct UnsafeBindtoRefCountedArg : false_type { 274}; 275 276template <typename T> 277struct UnsafeBindtoRefCountedArg<T*> 278 : UnsafeBindtoRefCountedArgHelper<is_class<T>::value, T> { 279}; 280 281template <typename T> 282class HasIsMethodTag { 283 typedef char Yes[1]; 284 typedef char No[2]; 285 286 template <typename U> 287 static Yes& Check(typename U::IsMethod*); 288 289 template <typename U> 290 static No& Check(...); 291 292 public: 293 static const bool value = sizeof(Check<T>(0)) == sizeof(Yes); 294}; 295 296template <typename T> 297class UnretainedWrapper { 298 public: 299 explicit UnretainedWrapper(T* o) : ptr_(o) {} 300 T* get() const { return ptr_; } 301 private: 302 T* ptr_; 303}; 304 305template <typename T> 306class ConstRefWrapper { 307 public: 308 explicit ConstRefWrapper(const T& o) : ptr_(&o) {} 309 const T& get() const { return *ptr_; } 310 private: 311 const T* ptr_; 312}; 313 314template <typename T> 315struct IgnoreResultHelper { 316 explicit IgnoreResultHelper(T functor) : functor_(functor) {} 317 318 T functor_; 319}; 320 321template <typename T> 322struct IgnoreResultHelper<Callback<T> > { 323 explicit IgnoreResultHelper(const Callback<T>& functor) : functor_(functor) {} 324 325 const Callback<T>& functor_; 326}; 327 328// An alternate implementation is to avoid the destructive copy, and instead 329// specialize ParamTraits<> for OwnedWrapper<> to change the StorageType to 330// a class that is essentially a scoped_ptr<>. 331// 332// The current implementation has the benefit though of leaving ParamTraits<> 333// fully in callback_internal.h as well as avoiding type conversions during 334// storage. 335template <typename T> 336class OwnedWrapper { 337 public: 338 explicit OwnedWrapper(T* o) : ptr_(o) {} 339 ~OwnedWrapper() { delete ptr_; } 340 T* get() const { return ptr_; } 341 OwnedWrapper(const OwnedWrapper& other) { 342 ptr_ = other.ptr_; 343 other.ptr_ = NULL; 344 } 345 346 private: 347 mutable T* ptr_; 348}; 349 350// PassedWrapper is a copyable adapter for a scoper that ignores const. 351// 352// It is needed to get around the fact that Bind() takes a const reference to 353// all its arguments. Because Bind() takes a const reference to avoid 354// unnecessary copies, it is incompatible with movable-but-not-copyable 355// types; doing a destructive "move" of the type into Bind() would violate 356// the const correctness. 357// 358// This conundrum cannot be solved without either C++11 rvalue references or 359// a O(2^n) blowup of Bind() templates to handle each combination of regular 360// types and movable-but-not-copyable types. Thus we introduce a wrapper type 361// that is copyable to transmit the correct type information down into 362// BindState<>. Ignoring const in this type makes sense because it is only 363// created when we are explicitly trying to do a destructive move. 364// 365// Two notes: 366// 1) PassedWrapper supports any type that has a "Pass()" function. 367// This is intentional. The whitelisting of which specific types we 368// support is maintained by CallbackParamTraits<>. 369// 2) is_valid_ is distinct from NULL because it is valid to bind a "NULL" 370// scoper to a Callback and allow the Callback to execute once. 371template <typename T> 372class PassedWrapper { 373 public: 374 explicit PassedWrapper(T scoper) : is_valid_(true), scoper_(scoper.Pass()) {} 375 PassedWrapper(const PassedWrapper& other) 376 : is_valid_(other.is_valid_), scoper_(other.scoper_.Pass()) { 377 } 378 T Pass() const { 379 CHECK(is_valid_); 380 is_valid_ = false; 381 return scoper_.Pass(); 382 } 383 384 private: 385 mutable bool is_valid_; 386 mutable T scoper_; 387}; 388 389// Unwrap the stored parameters for the wrappers above. 390template <typename T> 391struct UnwrapTraits { 392 typedef const T& ForwardType; 393 static ForwardType Unwrap(const T& o) { return o; } 394}; 395 396template <typename T> 397struct UnwrapTraits<UnretainedWrapper<T> > { 398 typedef T* ForwardType; 399 static ForwardType Unwrap(UnretainedWrapper<T> unretained) { 400 return unretained.get(); 401 } 402}; 403 404template <typename T> 405struct UnwrapTraits<ConstRefWrapper<T> > { 406 typedef const T& ForwardType; 407 static ForwardType Unwrap(ConstRefWrapper<T> const_ref) { 408 return const_ref.get(); 409 } 410}; 411 412template <typename T> 413struct UnwrapTraits<scoped_refptr<T> > { 414 typedef T* ForwardType; 415 static ForwardType Unwrap(const scoped_refptr<T>& o) { return o.get(); } 416}; 417 418template <typename T> 419struct UnwrapTraits<WeakPtr<T> > { 420 typedef const WeakPtr<T>& ForwardType; 421 static ForwardType Unwrap(const WeakPtr<T>& o) { return o; } 422}; 423 424template <typename T> 425struct UnwrapTraits<OwnedWrapper<T> > { 426 typedef T* ForwardType; 427 static ForwardType Unwrap(const OwnedWrapper<T>& o) { 428 return o.get(); 429 } 430}; 431 432template <typename T> 433struct UnwrapTraits<PassedWrapper<T> > { 434 typedef T ForwardType; 435 static T Unwrap(PassedWrapper<T>& o) { 436 return o.Pass(); 437 } 438}; 439 440// Utility for handling different refcounting semantics in the Bind() 441// function. 442template <bool is_method, typename T> 443struct MaybeRefcount; 444 445template <typename T> 446struct MaybeRefcount<false, T> { 447 static void AddRef(const T&) {} 448 static void Release(const T&) {} 449}; 450 451template <typename T, size_t n> 452struct MaybeRefcount<false, T[n]> { 453 static void AddRef(const T*) {} 454 static void Release(const T*) {} 455}; 456 457template <typename T> 458struct MaybeRefcount<true, T> { 459 static void AddRef(const T&) {} 460 static void Release(const T&) {} 461}; 462 463template <typename T> 464struct MaybeRefcount<true, T*> { 465 static void AddRef(T* o) { o->AddRef(); } 466 static void Release(T* o) { o->Release(); } 467}; 468 469// No need to additionally AddRef() and Release() since we are storing a 470// scoped_refptr<> inside the storage object already. 471template <typename T> 472struct MaybeRefcount<true, scoped_refptr<T> > { 473 static void AddRef(const scoped_refptr<T>& o) {} 474 static void Release(const scoped_refptr<T>& o) {} 475}; 476 477template <typename T> 478struct MaybeRefcount<true, const T*> { 479 static void AddRef(const T* o) { o->AddRef(); } 480 static void Release(const T* o) { o->Release(); } 481}; 482 483// IsWeakMethod is a helper that determine if we are binding a WeakPtr<> to a 484// method. It is used internally by Bind() to select the correct 485// InvokeHelper that will no-op itself in the event the WeakPtr<> for 486// the target object is invalidated. 487// 488// P1 should be the type of the object that will be received of the method. 489template <bool IsMethod, typename P1> 490struct IsWeakMethod : public false_type {}; 491 492template <typename T> 493struct IsWeakMethod<true, WeakPtr<T> > : public true_type {}; 494 495template <typename T> 496struct IsWeakMethod<true, ConstRefWrapper<WeakPtr<T> > > : public true_type {}; 497 498} // namespace internal 499 500template <typename T> 501static inline internal::UnretainedWrapper<T> Unretained(T* o) { 502 return internal::UnretainedWrapper<T>(o); 503} 504 505template <typename T> 506static inline internal::ConstRefWrapper<T> ConstRef(const T& o) { 507 return internal::ConstRefWrapper<T>(o); 508} 509 510template <typename T> 511static inline internal::OwnedWrapper<T> Owned(T* o) { 512 return internal::OwnedWrapper<T>(o); 513} 514 515// We offer 2 syntaxes for calling Passed(). The first takes a temporary and 516// is best suited for use with the return value of a function. The second 517// takes a pointer to the scoper and is just syntactic sugar to avoid having 518// to write Passed(scoper.Pass()). 519template <typename T> 520static inline internal::PassedWrapper<T> Passed(T scoper) { 521 return internal::PassedWrapper<T>(scoper.Pass()); 522} 523template <typename T> 524static inline internal::PassedWrapper<T> Passed(T* scoper) { 525 return internal::PassedWrapper<T>(scoper->Pass()); 526} 527 528template <typename T> 529static inline internal::IgnoreResultHelper<T> IgnoreResult(T data) { 530 return internal::IgnoreResultHelper<T>(data); 531} 532 533template <typename T> 534static inline internal::IgnoreResultHelper<Callback<T> > 535IgnoreResult(const Callback<T>& data) { 536 return internal::IgnoreResultHelper<Callback<T> >(data); 537} 538 539BASE_EXPORT void DoNothing(); 540 541template<typename T> 542void DeletePointer(T* obj) { 543 delete obj; 544} 545 546// ScopedClosureRunner is akin to scoped_ptr for Closures. It ensures that the 547// Closure is executed and deleted no matter how the current scope exits. 548class BASE_EXPORT ScopedClosureRunner { 549 public: 550 explicit ScopedClosureRunner(const Closure& closure); 551 ~ScopedClosureRunner(); 552 553 Closure Release(); 554 555 private: 556 Closure closure_; 557 558 DISALLOW_IMPLICIT_CONSTRUCTORS(ScopedClosureRunner); 559}; 560 561} // namespace base 562 563#endif // BASE_BIND_HELPERS_H_ 564