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.

[willchan no longer on Chromium, 2011/01/19 16:57:43]

I'm not trying to wordsmith the comments here, just want to note this down for
the future.

Perhaps we should do tr1 justice and note that it's because of lack of rvalue
references, which will be fixed in C++0x. We can't wait for that though, and
it's just an implementation detail.

[awong, 2011/01/20 20:27:35]

Ooh...good point.  Will add a note about it.

+//
+// 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 {
+
+// InvokerBase 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 InvokerBase : public RefCountedThreadSafe<InvokerBase> {

[willchan no longer on Chromium, 2011/01/19 16:57:43]

Just noting that this is RefCountedThreadSafe. Every time we pass this results
in a few atomic operations. Do we want to encourage passing Callbacks to
functions by const reference instead of copy by value? That'd help minimize the
atomics. Did we discuss this in the meeting? If so, I forget and am sorry to
recover old ground. Note that if we wanted to pass via const reference, then
Run() would have to be a const member function, which is fine by me, but maybe
others find it weird.

This invoker stuff definitely should not be contaminating the base namespace.
Remember to stuff it in base::internal later.

[awong, 2011/01/20 20:27:35]

I think we started talking about it, but never actually came to a conclusion. 
I'll add a TODO to consider on the next pass.  Would like to punt though until
basic functionality is going.  The code is complex enough as it is. :(

+ protected:
+  virtual ~InvokerBase() {}

[willchan no longer on Chromium, 2011/01/19 16:57:43]

Why is this virtual?

[awong, 2011/01/20 20:27:35]

The scope_refptr's static type is scoped_refptr<InvokerBase>...which I think
means it will call InvokerBase's destructor.  However, the pointer is referring
to a child, so we need this to be virtual to ensure that the most-derived
class's destructor is called.

Am I wrong about this?

[willchan no longer on Chromium, 2011/01/21 02:30:12]

Yes, I'm wrong. I wrote that comment early on when I was still grokking how this
all worked.

+};
+
+// 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.
+template <typename Sig>
+class Callback;
+
+template <typename R>
+class Callback<R(void)> {
+ public:
+  typedef R(*PolymorphicInvoke)(InvokerBase*);
+
+  Callback(InvokerBase* invoker, PolymorphicInvoke* polymorphic_invoke)
+      : invoker_(invoker),
+        polymorphic_invoke_(polymorphic_invoke) {
+  }
+
+  R Run(void) {
+    return polymorphic_invoke_(invoker_.get());
+  }
+
+ private:
+  scoped_refptr<InvokerBase> invoker_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+template <typename R, typename A0>
+class Callback<R(A0)> {
+ public:
+  typedef R(*PolymorphicInvoke)(InvokerBase*, const A0&);
+
+  Callback(InvokerBase* invoker, PolymorphicInvoke* polymorphic_invoke)
+      : invoker_(invoker),
+        polymorphic_invoke_(polymorphic_invoke) {
+  }
+
+  R Run(const A0& a0) {
+    return polymorphic_invoke_(invoker_.get(), a0);
+  }
+
+ private:
+  scoped_refptr<InvokerBase> invoker_;
+  PolymorphicInvoke polymorphic_invoke_;
+};
+
+template <typename R, typename A0, typename A1>
+class Callback<R(A0, A1)> {
+ public:
+  typedef R(*PolymorphicInvoke)(void*, const A0&, const A1&);
+
+  Callback(InvokerBase* invoker, PolymorphicInvoke* polymorphic_invoke)
+      : invoker_(invoker),
+        polymorphic_invoke_(polymorphic_invoke) {
+  }
+
+  R Run(const A0& a0, const A1& a1) {
+    return polymorphic_invoke_(invoker_.get(), a0, a1);
+  }
+
+ private:
+  scoped_refptr<InvokerBase> invoker_;
+  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.
+typename Callback<void(void)> Closure;
+
+}  // namespace base
+
 #endif  // BASE_CALLBACK_H