Unified callback system.

base/callback.h

-// Copyright (c) 2010 The Chromium Authors. All rights reserved.
+// 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_CALLBACK_H_
 #define BASE_CALLBACK_H_
 #pragma once
 
 #include "base/tuple.h"
+#include "base/ref_counted.h"
 #include "base/raw_scoped_refptr_mismatch_checker.h"
 
 // Callback --------------------------------------------------------------------
 //
 // A Callback is like a Task but with unbound parameters. It is basically an
 // object-oriented function pointer.
 //
 // Callbacks are designed to work with Tuples.  A set of helper functions and
 // classes is provided to hide the Tuple details from the consumer.  Client
 // code will generally work with the CallbackRunner base class, which merely
@@ skipping 224 matching lines @@
   virtual ~CallbackWithReturnValueImpl() {}
 };
 
 template <class T, typename ReturnValue>
 typename CallbackWithReturnValue<ReturnValue>::Type*
 NewCallbackWithReturnValue(T* object, ReturnValue (T::*method)()) {
   return new CallbackWithReturnValueImpl<T, ReturnValue (T::*)(), ReturnValue>(
       object, method);
 }
 
+// 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, they provide a type-safe method for
+// creating a "closure."  In programing languages, a closure is a first-class
+// function where all its parameters have been bound.  Closures are well suited
+// for passing around a unit of delayed execution. They are used in Chromium
+// code to schedule tasks on different MessageLoops.
+//
+// EXAMPLE USAGE:
+//
+// TODO(ajwong): Add some good examples.
+//
+//
+// 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.
+//
+//
+// 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 when binding
+// arguments.  These copies will no longer be an issue in C++0x; C++0x will
+// support rvalue reference which will solve the 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.
+namespace base {
+
+// InvokerStorageBase is used to provide an opaque handle that the Callback
+// class can use to represent a function object with bound arguments.  It
+// behaves as an existential type that is used by a corresponding
+// PolymorphicInvoke function to perform the function execution.  This allows
+// us to shield the Callback class from the types of the bound arguments via
+// "type erasure."
+//
+// TODO(ajwong): Explain the PolymorphicInvoke setup is more understandable
+// terms.
+class InvokerStorageBase : public RefCountedThreadSafe<InvokerStorageBase> {
+ protected:
+  friend class RefCountedThreadSafe<InvokerStorageBase>;
+  virtual ~InvokerStorageBase() {}
+};
+
+template <typename T>
+struct InvokerStorageHolder {
+  explicit InvokerStorageHolder(T* invoker_storage)
+      : invoker_storage_(invoker_storage) {
+  }
+  scoped_refptr<InvokerStorageBase> invoker_storage_;
+};
+
+// First, forward declare the Callback class template. This informs the
+// compiler that ther template only have 1 type parameter, the function

[darin (slow to review), 2011/02/01 00:35:56]

need to proof read comments.  there's a variety of typos.

[awong, 2011/02/01 01:21:38]

Yep...will revisit all comments on the next version.

+// signature that the Callback is abstracting.
+//
+// After this, create template specializations for 0-5 parameters. Note that
+// even though the template typelist grows, that the specialization still
+// only has one type: the function signature.
+//
+// Also, note that the templated constructor should *not* be explicit. This is
+// to allow the natural assignment syntax from the result of Prebind().
+template <typename Sig>
+class Callback;
+
+template <typename R>
+class Callback<R(void)> {
+ public:
+  typedef R(*PolymorphicInvoke)(InvokerStorageBase*);
+
+  template <typename T>
+  Callback(const InvokerStorageHolder<T>& invoker_holder)
+      : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
+    invoker_storage_.swap(
+        const_cast<InvokerStorageHolder<T>&>(invoker_holder).invoker_storage_);
+  }
+
+  R Run(void) {
+    return polymorphic_invoke_(invoker_storage_.get());
+  }
+
+ private:
+  scoped_refptr<InvokerStorageBase> invoker_storage_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+template <typename R, typename A1>
+class Callback<R(A1)> {
+ public:
+  typedef R(*PolymorphicInvoke)(InvokerStorageBase*, A1);
+
+  template <typename T>
+  Callback(const InvokerStorageHolder<T>& invoker_holder)
+      : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
+    invoker_storage_.swap(
+        const_cast<InvokerStorageHolder<T>&>(invoker_holder).invoker_storage_);
+  }
+
+  R Run(A1 a1) {
+    return polymorphic_invoke_(invoker_storage_.get(), a1);
+  }
+
+ private:
+  scoped_refptr<InvokerStorageBase> invoker_storage_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+template <typename R, typename A1, typename A2>
+class Callback<R(A1, A2)> {
+ public:
+  typedef R(*PolymorphicInvoke)(void*, const A1&, const A2&);
+
+  template <typename T>
+  Callback(const InvokerStorageHolder<T>& invoker_holder)
+      : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
+    invoker_storage_.swap(
+        const_cast<InvokerStorageHolder<T>&>(invoker_holder).invoker_storage_);
+  }
+
+  R Run(const A1& a1, const A2& a2) {
+    return polymorphic_invoke_(invoker_storage_.get(), a1, a2);
+  }
+
+ private:
+  scoped_refptr<InvokerStorageBase> invoker_storage_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+
+// Syntactic sugar to make Callbacks<void(void)> easier to read since it will
+// be used in a lot of APIs with delayed execution.
+typedef Callback<void(void)> Closure;
+
+}  // namespace base
+
 #endif  // BASE_CALLBACK_H