callback.h revision 72a454cd3513ac24fbdd0e0cb9ad70b86a99b801
1// This file was GENERATED by command: 2// pump.py callback.h.pump 3// DO NOT EDIT BY HAND!!! 4 5 6// Copyright (c) 2011 The Chromium Authors. All rights reserved. 7// Use of this source code is governed by a BSD-style license that can be 8// found in the LICENSE file. 9 10#ifndef BASE_CALLBACK_H_ 11#define BASE_CALLBACK_H_ 12#pragma once 13 14#include "base/callback_helpers.h" 15#include "base/callback_old.h" 16 17// New, super-duper, unified Callback system. This will eventually replace 18// NewRunnableMethod, NewRunnableFunction, CreateFunctor, and CreateCallback 19// systems currently in the Chromium code base. 20// 21// WHAT IS THIS: 22// 23// The templated Callback class is a generalized function object. Together 24// with the Bind() function in bind.h, they provide a type-safe method for 25// performing currying of arguments, and creating a "closure." 26// 27// In programing languages, a closure is a first-class function where all its 28// parameters have been bound (usually via currying). Closures are well 29// suited for representing, and passing around a unit of delayed execution. 30// They are used in Chromium code to schedule tasks on different MessageLoops. 31// 32// 33// MEMORY MANAGEMENT AND PASSING 34// 35// The Callback objects themselves should be passed by const-reference, and 36// stored by copy. They internally store their state via a refcounted class 37// and thus do not need to be deleted. 38// 39// The reason to pass via a const-reference is to avoid unnecessary 40// AddRef/Release pairs to the internal state. 41// 42// 43// EXAMPLE USAGE: 44// 45// /* Binding a normal function. */ 46// int Return5() { return 5; } 47// base::Callback<int(int)> func_cb = base::Bind(&Return5); 48// LOG(INFO) << func_cb.Run(5); // Prints 5. 49// 50// void PrintHi() { LOG(INFO) << "hi."; } 51// base::Closure void_func_cb = base::Bind(&PrintHi); 52// LOG(INFO) << void_func_cb.Run(); // Prints: hi. 53// 54// /* Binding a class method. */ 55// class Ref : public RefCountedThreadSafe<Ref> { 56// public: 57// int Foo() { return 3; } 58// void PrintBye() { LOG(INFO) << "bye."; } 59// }; 60// scoped_refptr<Ref> ref = new Ref(); 61// base::Callback<int(void)> ref_cb = base::Bind(&Ref::Foo, ref.get()); 62// LOG(INFO) << ref_cb.Run(); // Prints out 3. 63// 64// base::Closure void_ref_cb = base::Bind(&Ref::PrintBye, ref.get()); 65// void_ref_cb.Run(); // Prints: bye. 66// 67// /* Binding a class method in a non-refcounted class. 68// * 69// * WARNING: You must be sure the referee outlives the callback! 70// * This is particularly important if you post a closure to a 71// * MessageLoop because then it becomes hard to know what the 72// * lifetime of the referee needs to be. 73// */ 74// class NoRef { 75// public: 76// int Foo() { return 4; } 77// void PrintWhy() { LOG(INFO) << "why???"; } 78// }; 79// NoRef no_ref; 80// base::Callback<int(void)> base::no_ref_cb = 81// base::Bind(&NoRef::Foo, base::Unretained(&no_ref)); 82// LOG(INFO) << ref_cb.Run(); // Prints out 4. 83// 84// base::Closure void_no_ref_cb = 85// base::Bind(&NoRef::PrintWhy, base::Unretained(no_ref)); 86// void_no_ref_cb.Run(); // Prints: why??? 87// 88// /* Binding a reference. */ 89// int Identity(int n) { return n; } 90// int value = 1; 91// base::Callback<int(void)> bound_copy_cb = base::Bind(&Identity, value); 92// base::Callback<int(void)> bound_ref_cb = 93// base::Bind(&Identity, base::ConstRef(value)); 94// LOG(INFO) << bound_copy_cb.Run(); // Prints 1. 95// LOG(INFO) << bound_ref_cb.Run(); // Prints 1. 96// value = 2; 97// LOG(INFO) << bound_copy_cb.Run(); // Prints 1. 98// LOG(INFO) << bound_ref_cb.Run(); // Prints 2. 99// 100// 101// WHERE IS THIS DESIGN FROM: 102// 103// The design Callback and Bind is heavily influenced by C++'s 104// tr1::function/tr1::bind, and by the "Google Callback" system used inside 105// Google. 106// 107// 108// HOW THE IMPLEMENTATION WORKS: 109// 110// There are three main components to the system: 111// 1) The Callback classes. 112// 2) The Bind() functions. 113// 3) The arguments wrappers (eg., Unretained() and ConstRef()). 114// 115// The Callback classes represent a generic function pointer. Internally, 116// it stores a refcounted piece of state that represents the target function 117// and all its bound parameters. Each Callback specialization has a templated 118// constructor that takes an InvokerStorageHolder<> object. In the context of 119// the constructor, the static type of this InvokerStorageHolder<> object 120// uniquely identifies the function it is representing, all its bound 121// parameters, and a DoInvoke() that is capable of invoking the target. 122// 123// Callback's constructor is takes the InvokerStorageHolder<> that has the 124// full static type and erases the target function type, and the bound 125// parameters. It does this by storing a pointer to the specific DoInvoke() 126// function, and upcasting the state of InvokerStorageHolder<> to a 127// InvokerStorageBase. This is safe as long as this InvokerStorageBase pointer 128// is only used with the stored DoInvoke() pointer. 129// 130// To create InvokerStorageHolder<> objects, we use the Bind() functions. 131// These functions, along with a set of internal templates, are reponsible for 132// 133// - Unwrapping the function signature into return type, and parameters 134// - Determining the number of parameters that are bound 135// - Creating the storage for the bound parameters 136// - Performing compile-time asserts to avoid error-prone behavior 137// - Returning an InvokerStorageHolder<> with an DoInvoke() that has an arity 138// matching the number of unbound parameters, and knows the correct 139// refcounting semantics for the target object if we are binding a class 140// method. 141// 142// The Bind functions do the above using type-inference, and template 143// specializations. 144// 145// By default Bind() will store copies of all bound parameters, and attempt 146// to refcount a target object if the function being bound is a class method. 147// 148// To change this behavior, we introduce a set of argument wrappers 149// (eg. Unretained(), and ConstRef()). These are simple container templates 150// that are passed by value, and wrap a pointer to argument. See the 151// file-level comment in base/bind_helpers.h for more info. 152// 153// These types are passed to the Unwrap() functions, and the MaybeRefcount() 154// functions respectively to modify the behavior of Bind(). The Unwrap() 155// and MaybeRefcount() functions change behavior by doing partial 156// specialization based on whether or not a parameter is a wrapper type. 157// 158// ConstRef() is similar to tr1::cref. Unretained() is specific to Chromium. 159// 160// 161// WHY NOT TR1 FUNCTION/BIND? 162// 163// Direct use of tr1::function and tr1::bind was considered, but ultimately 164// rejected because of the number of copy constructors invocations involved 165// in the binding of arguments during construction, and the forwarding of 166// arguments during invocation. These copies will no longer be an issue in 167// C++0x because C++0x will support rvalue reference allowing for the compiler 168// to avoid these copies. However, waiting for C++0x is not an option. 169// 170// Measured with valgrind on gcc version 4.4.3 (Ubuntu 4.4.3-4ubuntu5), the 171// tr1::bind call itself will invoke a non-trivial copy constructor three times 172// for each bound parameter. Also, each when passing a tr1::function, each 173// bound argument will be copied again. 174// 175// In addition to the copies taken at binding and invocation, copying a 176// tr1::function causes a copy to be made of all the bound parameters and 177// state. 178// 179// Furthermore, in Chromium, it is desirable for the Callback to take a 180// reference on a target object when representing a class method call. This 181// is not supported by tr1. 182// 183// Lastly, tr1::function and tr1::bind has a more general and flexible API. 184// This includes things like argument reordering by use of 185// tr1::bind::placeholder, support for non-const reference parameters, and some 186// limited amount of subtyping of the tr1::function object (eg., 187// tr1::function<int(int)> is convertible to tr1::function<void(int)>). 188// 189// These are not features that are required in Chromium. Some of them, such as 190// allowing for reference parameters, and subtyping of functions, may actually 191// because a source of errors. Removing support for these features actually 192// allows for a simpler implementation, and a terser Currying API. 193// 194// 195// WHY NOT GOOGLE CALLBACKS? 196// 197// The Google callback system also does not support refcounting. Furthermore, 198// its implementation has a number of strange edge cases with respect to type 199// conversion of its arguments. In particular, the argument's constness must 200// at times match exactly the function signature, or the type-inference might 201// break. Given the above, writing a custom solution was easier. 202// 203// 204// MISSING FUNCTIONALITY 205// - Invoking the return of Bind. Bind(&foo).Run() does not work; 206// - Binding arrays to functions that take a non-const pointer. 207// Example: 208// void Foo(const char* ptr); 209// void Bar(char* ptr); 210// Bind(&Foo, "test"); 211// Bind(&Bar, "test"); // This fails because ptr is not const. 212 213namespace base { 214 215// First, we forward declare the Callback class template. This informs the 216// compiler that the template only has 1 type parameter which is the function 217// signature that the Callback is representing. 218// 219// After this, create template specializations for 0-6 parameters. Note that 220// even though the template typelist grows, the specialization still 221// only has one type: the function signature. 222template <typename Sig> 223class Callback; 224 225template <typename R> 226class Callback<R(void)> { 227 public: 228 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*); 229 230 Callback() : polymorphic_invoke_(NULL) { } 231 232 // We pass InvokerStorageHolder by const ref to avoid incurring an 233 // unnecessary AddRef/Unref pair even though we will modify the object. 234 // We cannot use a normal reference because the compiler will warn 235 // since this is often used on a return value, which is a temporary. 236 // 237 // Note that this constructor CANNOT be explicit, and that Bind() CANNOT 238 // return the exact Callback<> type. See base/bind.h for details. 239 template <typename T> 240 Callback(const internal::InvokerStorageHolder<T>& invoker_holder) 241 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) { 242 invoker_storage_.swap(invoker_holder.invoker_storage_); 243 } 244 245 R Run(void) const { 246 return polymorphic_invoke_(invoker_storage_.get()); 247 } 248 249 private: 250 scoped_refptr<internal::InvokerStorageBase> invoker_storage_; 251 PolymorphicInvoke polymorphic_invoke_; 252}; 253 254template <typename R, typename A1> 255class Callback<R(A1)> { 256 public: 257 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&); 258 259 Callback() : polymorphic_invoke_(NULL) { } 260 261 // We pass InvokerStorageHolder by const ref to avoid incurring an 262 // unnecessary AddRef/Unref pair even though we will modify the object. 263 // We cannot use a normal reference because the compiler will warn 264 // since this is often used on a return value, which is a temporary. 265 // 266 // Note that this constructor CANNOT be explicit, and that Bind() CANNOT 267 // return the exact Callback<> type. See base/bind.h for details. 268 template <typename T> 269 Callback(const internal::InvokerStorageHolder<T>& invoker_holder) 270 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) { 271 invoker_storage_.swap(invoker_holder.invoker_storage_); 272 } 273 274 R Run(const A1& a1) const { 275 return polymorphic_invoke_(invoker_storage_.get(), a1); 276 } 277 278 private: 279 scoped_refptr<internal::InvokerStorageBase> invoker_storage_; 280 PolymorphicInvoke polymorphic_invoke_; 281}; 282 283template <typename R, typename A1, typename A2> 284class Callback<R(A1, A2)> { 285 public: 286 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&, 287 const A2&); 288 289 Callback() : polymorphic_invoke_(NULL) { } 290 291 // We pass InvokerStorageHolder by const ref to avoid incurring an 292 // unnecessary AddRef/Unref pair even though we will modify the object. 293 // We cannot use a normal reference because the compiler will warn 294 // since this is often used on a return value, which is a temporary. 295 // 296 // Note that this constructor CANNOT be explicit, and that Bind() CANNOT 297 // return the exact Callback<> type. See base/bind.h for details. 298 template <typename T> 299 Callback(const internal::InvokerStorageHolder<T>& invoker_holder) 300 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) { 301 invoker_storage_.swap(invoker_holder.invoker_storage_); 302 } 303 304 R Run(const A1& a1, 305 const A2& a2) const { 306 return polymorphic_invoke_(invoker_storage_.get(), a1, 307 a2); 308 } 309 310 private: 311 scoped_refptr<internal::InvokerStorageBase> invoker_storage_; 312 PolymorphicInvoke polymorphic_invoke_; 313}; 314 315template <typename R, typename A1, typename A2, typename A3> 316class Callback<R(A1, A2, A3)> { 317 public: 318 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&, 319 const A2&, 320 const A3&); 321 322 Callback() : polymorphic_invoke_(NULL) { } 323 324 // We pass InvokerStorageHolder by const ref to avoid incurring an 325 // unnecessary AddRef/Unref pair even though we will modify the object. 326 // We cannot use a normal reference because the compiler will warn 327 // since this is often used on a return value, which is a temporary. 328 // 329 // Note that this constructor CANNOT be explicit, and that Bind() CANNOT 330 // return the exact Callback<> type. See base/bind.h for details. 331 template <typename T> 332 Callback(const internal::InvokerStorageHolder<T>& invoker_holder) 333 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) { 334 invoker_storage_.swap(invoker_holder.invoker_storage_); 335 } 336 337 R Run(const A1& a1, 338 const A2& a2, 339 const A3& a3) const { 340 return polymorphic_invoke_(invoker_storage_.get(), a1, 341 a2, 342 a3); 343 } 344 345 private: 346 scoped_refptr<internal::InvokerStorageBase> invoker_storage_; 347 PolymorphicInvoke polymorphic_invoke_; 348}; 349 350template <typename R, typename A1, typename A2, typename A3, typename A4> 351class Callback<R(A1, A2, A3, A4)> { 352 public: 353 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&, 354 const A2&, 355 const A3&, 356 const A4&); 357 358 Callback() : polymorphic_invoke_(NULL) { } 359 360 // We pass InvokerStorageHolder by const ref to avoid incurring an 361 // unnecessary AddRef/Unref pair even though we will modify the object. 362 // We cannot use a normal reference because the compiler will warn 363 // since this is often used on a return value, which is a temporary. 364 // 365 // Note that this constructor CANNOT be explicit, and that Bind() CANNOT 366 // return the exact Callback<> type. See base/bind.h for details. 367 template <typename T> 368 Callback(const internal::InvokerStorageHolder<T>& invoker_holder) 369 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) { 370 invoker_storage_.swap(invoker_holder.invoker_storage_); 371 } 372 373 R Run(const A1& a1, 374 const A2& a2, 375 const A3& a3, 376 const A4& a4) const { 377 return polymorphic_invoke_(invoker_storage_.get(), a1, 378 a2, 379 a3, 380 a4); 381 } 382 383 private: 384 scoped_refptr<internal::InvokerStorageBase> invoker_storage_; 385 PolymorphicInvoke polymorphic_invoke_; 386}; 387 388template <typename R, typename A1, typename A2, typename A3, typename A4, 389 typename A5> 390class Callback<R(A1, A2, A3, A4, A5)> { 391 public: 392 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&, 393 const A2&, 394 const A3&, 395 const A4&, 396 const A5&); 397 398 Callback() : polymorphic_invoke_(NULL) { } 399 400 // We pass InvokerStorageHolder by const ref to avoid incurring an 401 // unnecessary AddRef/Unref pair even though we will modify the object. 402 // We cannot use a normal reference because the compiler will warn 403 // since this is often used on a return value, which is a temporary. 404 // 405 // Note that this constructor CANNOT be explicit, and that Bind() CANNOT 406 // return the exact Callback<> type. See base/bind.h for details. 407 template <typename T> 408 Callback(const internal::InvokerStorageHolder<T>& invoker_holder) 409 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) { 410 invoker_storage_.swap(invoker_holder.invoker_storage_); 411 } 412 413 R Run(const A1& a1, 414 const A2& a2, 415 const A3& a3, 416 const A4& a4, 417 const A5& a5) const { 418 return polymorphic_invoke_(invoker_storage_.get(), a1, 419 a2, 420 a3, 421 a4, 422 a5); 423 } 424 425 private: 426 scoped_refptr<internal::InvokerStorageBase> invoker_storage_; 427 PolymorphicInvoke polymorphic_invoke_; 428}; 429 430template <typename R, typename A1, typename A2, typename A3, typename A4, 431 typename A5, typename A6> 432class Callback<R(A1, A2, A3, A4, A5, A6)> { 433 public: 434 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&, 435 const A2&, 436 const A3&, 437 const A4&, 438 const A5&, 439 const A6&); 440 441 Callback() : polymorphic_invoke_(NULL) { } 442 443 // We pass InvokerStorageHolder by const ref to avoid incurring an 444 // unnecessary AddRef/Unref pair even though we will modify the object. 445 // We cannot use a normal reference because the compiler will warn 446 // since this is often used on a return value, which is a temporary. 447 // 448 // Note that this constructor CANNOT be explicit, and that Bind() CANNOT 449 // return the exact Callback<> type. See base/bind.h for details. 450 template <typename T> 451 Callback(const internal::InvokerStorageHolder<T>& invoker_holder) 452 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) { 453 invoker_storage_.swap(invoker_holder.invoker_storage_); 454 } 455 456 R Run(const A1& a1, 457 const A2& a2, 458 const A3& a3, 459 const A4& a4, 460 const A5& a5, 461 const A6& a6) const { 462 return polymorphic_invoke_(invoker_storage_.get(), a1, 463 a2, 464 a3, 465 a4, 466 a5, 467 a6); 468 } 469 470 private: 471 scoped_refptr<internal::InvokerStorageBase> invoker_storage_; 472 PolymorphicInvoke polymorphic_invoke_; 473}; 474 475 476// Syntactic sugar to make Callbacks<void(void)> easier to declare since it 477// will be used in a lot of APIs with delayed execution. 478typedef Callback<void(void)> Closure; 479 480} // namespace base 481 482#endif // BASE_CALLBACK_H 483