Unified callback system.

base/uber_callback.h.pump

Index: base/uber_callback.h.pump
diff --git a/base/uber_callback.h.pump b/base/uber_callback.h.pump
new file mode 100644
index 0000000000000000000000000000000000000000..8212b57e3f810bad800417d59f7dd463ed330ef8
--- /dev/null
+++ b/base/uber_callback.h.pump
@@ -0,0 +1,142 @@
+// 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/ref_counted.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, 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_;
+};
+
+template <typename T>
+InvokerStorageHolder<T> MakeInvokerStorageHolder(T* o) {
+  return InvokerStorageHolder<T>(o);
+}
+
+// First, forward declare the Callback class template. This informs the
+// compiler that ther template only have 1 type parameter, the function
+// 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;
+
+$var MAX_ARITY = 6
+
+$range ARITY 0..MAX_ARITY
+$for ARITY [[
+$range ARG 1..ARITY
+
+$if ARITY == 0 [[
+template <typename R>
+class Callback<R(void)> {
+]] $else [[
+template <typename R, $for ARG , [[typename A$(ARG)]]>
+class Callback<R($for ARG , [[A$(ARG)]])> {
+]]
+
+ public:
+  typedef R(*PolymorphicInvoke)(InvokerStorageBase*[[]]
+$if ARITY != 0 [[, ]] $for ARG , [[A$(ARG)]]);
+
+  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_);
+  }
+
+
+$if ARITY == 0 [[
+  R Run(void) {
+]] $else [[
+  R Run($for ARG , [[A$(ARG) a$(ARG)]]) {
+]]
+
+    return polymorphic_invoke_(invoker_storage_.get()[[]]
+$if ARITY != 0 [[, ]] $for ARG , [[a$(ARG)]]);
+  }
+
+ private:
+  scoped_refptr<InvokerStorageBase> invoker_storage_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+
+]]  $$ for ARITY
+
+// 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_UBER_CALLBACK_H