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