Unified callback system.

base/uber_callback.h

Index: base/uber_callback.h
diff --git a/base/uber_callback.h b/base/uber_callback.h
new file mode 100644
index 0000000000000000000000000000000000000000..5a721a013af78f5f443b5df3f79d40d587d1c926
--- /dev/null
+++ b/base/uber_callback.h
@@ -0,0 +1,368 @@
+// This file was GENERATED by command:
+//     pump.py uber_callback.h.pump
+// DO NOT EDIT BY HAND!!!
+
+
+// Copyright (c) 2011 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef BASE_UBER_CALLBACK_H_
+#define BASE_UBER_CALLBACK_H_
+#pragma once
+
+#include "base/uber_callback_helpers.h"
+
+// New, super-duper, unified Callback system.  This will eventually replace
+// NewRunnableMethod, NewRunnableFunction, CreateFunctor, and CreateCallback
+// systems currently in the Chromium code base.
+//
+// WHAT IS THIS:
+//
+// The templated Callback class is a generalized funciton object. Together
+// with the Prebind() function in prebind.h, they provide a type-safe method
+// for performing currying of arguments, and createing a "closure."
+//
+// In programing languages, a closure is a first-class function where all its
+// parameters have been bound (usually via currying).  Closures are well
+// suited for representing, and passing around a unit of delayed execution.
+// They are used in Chromium code to schedule tasks on different MessageLoops.
+//
+// EXAMPLE USAGE:
+//
+// /* Binding a class method. */
+// class Ref : public RefCountedThreadSafe<Ref> {

[willchan no longer on Chromium, 2011/02/07 23:50:02]

Add a public: section.

[awong, 2011/02/08 18:52:26]

Done.

+//   int Foo() { return 3; }
+// };
+// scoped_refptr<Ref> ref = new Ref();
+// Callback<int(void)> ref_cb = Prebind(&Ref::Foo, ref.get());
+// LOG(INFO) << ref_cb.Run();  // Prints out 3.
+//
+// /* Binding a class method in a non-refcounted class. */
+// class NoRef {

[willchan no longer on Chromium, 2011/02/07 23:50:02]

public:

[awong, 2011/02/08 18:52:26]

Done.

+//   int Foo() { return 4; }
+// };
+// NoRef no_ref;
+// Callback<int(void)> no_ref_cb = Prebind(&NoRef::Foo, Unretained(&no_ref));

[willchan no longer on Chromium, 2011/02/07 23:50:02]

Please prepend the base:: namespace as needed, since this should be an example
of how most people use it, and most users won't be in the base namespace.

[awong, 2011/02/08 18:52:26]

Done.

+// LOG(INFO) << ref_cb.Run();  // Prints out 4.
+//
+// /* Binding a normal function. */
+// int Return5() { return 5; }
+// Callback<int(int)> func_cb = Prebind(&Return5);
+// LOG(INFO) << func_cb.Run(5);  // Prints 5.
+//
+// /* Binding a reference. */
+// int Identity(int n) { return n; }
+// int value = 1;
+// Callback<int(void)> bound_copy_cb = Prebind(&Identity, value);
+// Callback<int(void)> bound_ref_cb = Prebind(&Identity, ConstRef(value));

[willchan no longer on Chromium, 2011/02/07 23:50:02]

I wonder if it's appropriate here to post a scary note about using ConstRef with
a Closure posted to the MessageLoop.

[awong, 2011/02/08 18:52:26]

Scary note added.

+// LOG(INFO) << bound_copy_cb.Run();  // Prints 1.
+// LOG(INFO) << bound_ref_cb.Run();  // Prints 1.
+// value = 2;
+// LOG(INFO) << bound_copy_cb.Run();  // Prints 1.
+// LOG(INFO) << bound_ref_cb.Run();  // Prints 2.
+//
+//

[willchan no longer on Chromium, 2011/02/07 23:50:02]

Include an example for Closure. I suspect that will be the most common one after
all.

[awong, 2011/02/08 18:52:26]

Good call.  I added a couple.

+// WHERE IS THIS DESIGN FROM:
+//
+// The design Callback and Prebind is heavily influenced by C++'s
+// tr1::function/tr1::bind, and by the "Google Callback" system used inside
+// Google.
+//
+//
+// HOW THE IMPLEMENTATION WORKS:
+//
+// There are three main components to the system:
+//   1) The Callback classes.
+//   2) The Prebind() functions.
+//   3) The arguments wrappers (eg., Unretained() and ConstRef()).
+//
+// The Callback classes represent a generic function pointer. Internally,
+// it stores a refcounted piece of state that represents the target function
+// and all its bound parameters.  Each Callback specialization has a templated
+// constructor that takes an InvokerStorageHolder<> object.  In the context of
+// the constructor, the static type of this InvokerStorageHolder<> object
+// uniquely identifies the function it is representing, all its bound
+// parameters, and a DoInvoke that is capable of invoking the target.
+//
+// Callback's constructor is takes the InvokerStorageHolder<> that has the
+// full static type and erases the target function type, and the bound
+// parameters.  It does this by storing a pointer to the specific DoInvoke
+// function, and upcasting the state of InvokerStorageHolder<> to a
+// InvokerStorageBase. This is safe as long as this InvokerStorageBase pointer
+// is only used with the stored DoInvoke pointer.
+//
+// To create InvokerStorageHolder<> objects, we use the Prebind() functions.
+// These functions, along with a set of internal templates, are reponsible for
+//
+//  - Unwrapping the function signature into return type, and parameters
+//  - Determining the number of parameters that are bound
+//  - Creating the storage for the bound parameters
+//  - Performing compile-time asserts to avoid error-prone behavior
+//  - Returning an InvokerStorageHolder<> with an DoInvoke that has an arity
+//    matching the number of unbound parameters, and knows the correct
+//    refcounting semantics for the target object if we are binding a class
+//    method.
+//
+// The Prebind functions do the above using type-inference, and template
+// specializations.
+//
+// By default Prebind() will store copies of all bound parameters, and attempt
+// to refcount a target object if the function being bound is a class method.
+//
+// To change this behavior, we introduce a set of argument wrappers
+// (eg. Unretained(), and ConstRef()).  These are simple container templates
+// that are passed by value, and wrap a pointer to argument.
+//
+// ConstRef() allows Prebind()'s storage to preserve copy-semantics even if we
+// wish to pass the invoked object a reference to the bound parameter.
+//
+// Unretained() allows us to tag an object for different refcounting semantics.
+//
+// These types are passed to the Unwrap() functions, and the MaybeRefcount()
+// functions respectively to modify the behavior of Prebind().  The Unwrap()
+// and MaybeRefcount() functions change behavior by doing partial
+// specialization based on whether or not a parameter is a wrapper type.
+//
+// ConstRef() is similar to tr1::cref.  Unretained() is specific to Chromium.
+//
+//
+// WHY NOT TR1 FUNCTION/BIND?
+//
+// Direct use of tr1::function and tr1::bind was considered, but ultimately
+// rejected because of the number of copy constructors invocations involved
+// in the binding of arguments during construction, and the forwarding of
+// arguments during invocation.  These copies will no longer be an issue in
+// C++0x because C++0x will support rvalue reference allowing for the compiler
+// to avoid these copies.  However, waiting for C++0x is not an option.
+//
+// Measured with valgrind on gcc version 4.4.3 (Ubuntu 4.4.3-4ubuntu5), the
+// tr1::bind call itself will invoke a non-trivial copy constructor three times
+// for each bound parameter.  Also, each when passing a tr1::function, each
+// bound argument will be copied again.
+//
+// In addition to the copies taken at binding and invocation, copying a
+// tr1::function causes a copy to be made of all the bound parameters and
+// state.
+//
+// Furthermore, in Chromium, it is desirable for the Callback to take a
+// reference on a target object when representing a class method call.  This
+// is not supported by tr1.
+//
+// Lastly, tr1::function and tr1::bind has a more general and flexible API.
+// This includes things like argument reordering by use of
+// tr1::bind::placeholder, support for non-const reference parameters, and some
+// limited amount of subtyping of the tr1::function object (eg.,
+// tr1::function<int(int)> is convertable to tr1::function<void(int)>).
+//
+// These are not features that are required in Chromium. Some of them, such as
+// allowing for reference parameters, and subtyping of functions, may actually
+// because a source of errors. Removing support for these features actually
+// allows for a simpler implementation, and a terser Currying API.
+//
+//
+// WHY NOT GOOGLE CALLBACKS?
+//
+// The Google callback system also does not support refcounting.  Furthermore,
+// its implementation has a number of strange edge cases with respect to type
+// convesrion of its arguments.  In particular, the argument's constness must
+// at times match exactly the function signature, or the type-inference might
+// break.  Given the above, writing a custom solution was easier.
+//
+//
+// MISSING FUNCTIONALITY
+//  - Invoking the return of Prebind.  Prebind(&foo).Run() does not work;
+//  - Binding arrays to functions that take a non-const pointer.
+//    Example:
+//      void Foo(const char* ptr);
+//      void Bar(char* ptr);
+//      Prebind(&Foo, "test");
+//      Prebind(&Bar, "tesT");  // This fails because ptr is not const.
+
+namespace base {
+
+// First, we forward declare the Callback class template. This informs the
+// compiler that the template only has 1 type parameter which is the function
+// signature that the Callback is representing.
+//
+// After this, create template specializations for 0-6 parameters. Note that
+// even though the template typelist grows, the specialization still
+// only has one type: the function signature.
+//
+// Also, note that the templated constructor should *not* be explicit. This is
+// to allow for a natural assignment syntax from the result of Prebind(), which
+// is not the same type as Callback().  See the description of Prebind for
+// details.
+template <typename Sig>
+class Callback;
+
+template <typename R>
+class Callback<R(void)> {
+ public:
+  Callback() : polymorphic_invoke_(NULL) { }

[willchan no longer on Chromium, 2011/02/06 10:26:50]

When is this ever used? Can this be private?

[willchan no longer on Chromium, 2011/02/07 23:25:15]

Oops, I see now that this is the equivalent of std::tr1::function; This is fine.

[awong, 2011/02/08 18:52:26]

Yeah...I initially left it out too.  The my unittests told me to do otherwise. 
Yay for unittests!

+
+  typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*);

[willchan no longer on Chromium, 2011/02/06 10:26:50]

Move the typedef before the constructor.

[awong, 2011/02/08 18:52:26]

Done.

+
+  template <typename T>
+  Callback(const internal::InvokerStorageHolder<T>& invoker_holder)

[willchan no longer on Chromium, 2011/02/07 20:51:48]

Why is this const if we're calling swap on its member variable?

[willchan no longer on Chromium, 2011/02/07 23:25:15]

I just noticed this constructor is implicit. Can you change Prebind() to return
the appropriate Callback type rather than returning the
internal::InvokerStorageHolder()?

[awong, 2011/02/08 18:52:26]

No...unfortunately not without increasing the number of templates by 
sum(1..arity - 1).  There's a comment in prebind explaining this.

[awong, 2011/02/08 18:52:26]

This is to avoid an Addref/Unref pair.   I'll add a comment.

+      : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
+    invoker_storage_.swap(invoker_holder.invoker_storage_);
+  }
+
+  R Run(void) {
+    return polymorphic_invoke_(invoker_storage_.get());
+  }
+
+ private:
+  scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+template <typename R, typename A1>
+class Callback<R(A1)> {
+ public:
+  Callback() : polymorphic_invoke_(NULL) { }
+
+  typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&);
+
+  template <typename T>
+  Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
+      : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
+    invoker_storage_.swap(invoker_holder.invoker_storage_);
+  }
+
+  R Run(const A1& a1) {
+    return polymorphic_invoke_(invoker_storage_.get(), a1);
+  }
+
+ private:
+  scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+template <typename R, typename A1, typename A2>
+class Callback<R(A1, A2)> {
+ public:
+  Callback() : polymorphic_invoke_(NULL) { }
+
+  typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&,
+      const A2&);
+
+  template <typename T>
+  Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
+      : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
+    invoker_storage_.swap(invoker_holder.invoker_storage_);
+  }
+
+  R Run(const A1& a1, const A2& a2) {
+    return polymorphic_invoke_(invoker_storage_.get(), a1, a2);
+  }
+
+ private:
+  scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+template <typename R, typename A1, typename A2, typename A3>
+class Callback<R(A1, A2, A3)> {
+ public:
+  Callback() : polymorphic_invoke_(NULL) { }
+
+  typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&,
+      const A2&, const A3&);
+
+  template <typename T>
+  Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
+      : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
+    invoker_storage_.swap(invoker_holder.invoker_storage_);
+  }
+
+  R Run(const A1& a1, const A2& a2, const A3& a3) {
+    return polymorphic_invoke_(invoker_storage_.get(), a1, a2, a3);
+  }
+
+ private:
+  scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+template <typename R, typename A1, typename A2, typename A3, typename A4>
+class Callback<R(A1, A2, A3, A4)> {
+ public:
+  Callback() : polymorphic_invoke_(NULL) { }
+
+  typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&,
+      const A2&, const A3&, const A4&);
+
+  template <typename T>
+  Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
+      : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
+    invoker_storage_.swap(invoker_holder.invoker_storage_);
+  }
+
+  R Run(const A1& a1, const A2& a2, const A3& a3, const A4& a4) {
+    return polymorphic_invoke_(invoker_storage_.get(), a1, a2, a3, a4);
+  }
+
+ private:
+  scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+template <typename R, typename A1, typename A2, typename A3, typename A4,
+    typename A5>
+class Callback<R(A1, A2, A3, A4, A5)> {
+ public:
+  Callback() : polymorphic_invoke_(NULL) { }
+
+  typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&,
+      const A2&, const A3&, const A4&, const A5&);
+
+  template <typename T>
+  Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
+      : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
+    invoker_storage_.swap(invoker_holder.invoker_storage_);
+  }
+
+  R Run(const A1& a1, const A2& a2, const A3& a3, const A4& a4, const A5& a5) {
+    return polymorphic_invoke_(invoker_storage_.get(), a1, a2, a3, a4, a5);
+  }
+
+ private:
+  scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+template <typename R, typename A1, typename A2, typename A3, typename A4,
+    typename A5, typename A6>
+class Callback<R(A1, A2, A3, A4, A5, A6)> {
+ public:
+  Callback() : polymorphic_invoke_(NULL) { }
+
+  typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&,

[willchan no longer on Chromium, 2011/02/06 10:26:50]

Nit: you should probably change the pump to emit a line for each of these
arguments, so you don't have the strange formatting issues here.

[awong, 2011/02/08 18:52:26]

Fixed...but I wonder if we're trading pump-file readability (which is already
pretty bad) for generated-code readability.

+      const A2&, const A3&, const A4&, const A5&, const A6&);
+
+  template <typename T>
+  Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
+      : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
+    invoker_storage_.swap(invoker_holder.invoker_storage_);
+  }
+
+  R Run(const A1& a1, const A2& a2, const A3& a3, const A4& a4, const A5& a5,

[willchan no longer on Chromium, 2011/02/06 10:26:50]

Ditto on the line per argument to avoid the formatting indentation issue.

[awong, 2011/02/08 18:52:26]

Done.

+      const A6& a6) {
+    return polymorphic_invoke_(invoker_storage_.get(), a1, a2, a3, a4, a5, a6);
+  }
+
+ private:
+  scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+
+// Syntactic sugar to make Callbacks<void(void)> easier to declare since it
+// will be used in a lot of APIs with delayed execution.
+typedef Callback<void(void)> Closure;
+
+}  // namespace base
+
+#endif  // BASE_UBER_CALLBACK_H