Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(1268)

Side by Side Diff: base/uber_callback.h

Issue 6109007: Unified callback system. (Closed) Base URL: svn://svn.chromium.org/chrome/trunk/src/base
Patch Set: more bits of cleanup Created 9 years, 10 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
OLDNEW
(Empty)
1 // This file was GENERATED by command:
2 // pump.py uber_callback.h.pump
3 // DO NOT EDIT BY HAND!!!
4
5
6 // Copyright (c) 2011 The Chromium Authors. All rights reserved.
7 // Use of this source code is governed by a BSD-style license that can be
8 // found in the LICENSE file.
9
10 #ifndef BASE_UBER_CALLBACK_H_
11 #define BASE_UBER_CALLBACK_H_
12 #pragma once
13
14 #include "base/uber_callback_helpers.h"
15
16 // New, super-duper, unified Callback system. This will eventually replace
17 // NewRunnableMethod, NewRunnableFunction, CreateFunctor, and CreateCallback
18 // systems currently in the Chromium code base.
19 //
20 // WHAT IS THIS:
21 //
22 // The templated Callback class is a generalized funciton object. Together
23 // with the Prebind() function in prebind.h, they provide a type-safe method
24 // for performing currying of arguments, and createing a "closure."
25 //
26 // In programing languages, a closure is a first-class function where all its
27 // parameters have been bound (usually via currying). Closures are well
28 // suited for representing, and passing around a unit of delayed execution.
29 // They are used in Chromium code to schedule tasks on different MessageLoops.
30 //
31 // EXAMPLE USAGE:
32 //
33 // /* Binding a class method. */
34 // 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.
35 // int Foo() { return 3; }
36 // };
37 // scoped_refptr<Ref> ref = new Ref();
38 // Callback<int(void)> ref_cb = Prebind(&Ref::Foo, ref.get());
39 // LOG(INFO) << ref_cb.Run(); // Prints out 3.
40 //
41 // /* Binding a class method in a non-refcounted class. */
42 // class NoRef {
willchan no longer on Chromium 2011/02/07 23:50:02 public:
awong 2011/02/08 18:52:26 Done.
43 // int Foo() { return 4; }
44 // };
45 // NoRef no_ref;
46 // 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, sin
awong 2011/02/08 18:52:26 Done.
47 // LOG(INFO) << ref_cb.Run(); // Prints out 4.
48 //
49 // /* Binding a normal function. */
50 // int Return5() { return 5; }
51 // Callback<int(int)> func_cb = Prebind(&Return5);
52 // LOG(INFO) << func_cb.Run(5); // Prints 5.
53 //
54 // /* Binding a reference. */
55 // int Identity(int n) { return n; }
56 // int value = 1;
57 // Callback<int(void)> bound_copy_cb = Prebind(&Identity, value);
58 // 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
awong 2011/02/08 18:52:26 Scary note added.
59 // LOG(INFO) << bound_copy_cb.Run(); // Prints 1.
60 // LOG(INFO) << bound_ref_cb.Run(); // Prints 1.
61 // value = 2;
62 // LOG(INFO) << bound_copy_cb.Run(); // Prints 1.
63 // LOG(INFO) << bound_ref_cb.Run(); // Prints 2.
64 //
65 //
willchan no longer on Chromium 2011/02/07 23:50:02 Include an example for Closure. I suspect that wil
awong 2011/02/08 18:52:26 Good call. I added a couple.
66 // WHERE IS THIS DESIGN FROM:
67 //
68 // The design Callback and Prebind is heavily influenced by C++'s
69 // tr1::function/tr1::bind, and by the "Google Callback" system used inside
70 // Google.
71 //
72 //
73 // HOW THE IMPLEMENTATION WORKS:
74 //
75 // There are three main components to the system:
76 // 1) The Callback classes.
77 // 2) The Prebind() functions.
78 // 3) The arguments wrappers (eg., Unretained() and ConstRef()).
79 //
80 // The Callback classes represent a generic function pointer. Internally,
81 // it stores a refcounted piece of state that represents the target function
82 // and all its bound parameters. Each Callback specialization has a templated
83 // constructor that takes an InvokerStorageHolder<> object. In the context of
84 // the constructor, the static type of this InvokerStorageHolder<> object
85 // uniquely identifies the function it is representing, all its bound
86 // parameters, and a DoInvoke that is capable of invoking the target.
87 //
88 // Callback's constructor is takes the InvokerStorageHolder<> that has the
89 // full static type and erases the target function type, and the bound
90 // parameters. It does this by storing a pointer to the specific DoInvoke
91 // function, and upcasting the state of InvokerStorageHolder<> to a
92 // InvokerStorageBase. This is safe as long as this InvokerStorageBase pointer
93 // is only used with the stored DoInvoke pointer.
94 //
95 // To create InvokerStorageHolder<> objects, we use the Prebind() functions.
96 // These functions, along with a set of internal templates, are reponsible for
97 //
98 // - Unwrapping the function signature into return type, and parameters
99 // - Determining the number of parameters that are bound
100 // - Creating the storage for the bound parameters
101 // - Performing compile-time asserts to avoid error-prone behavior
102 // - Returning an InvokerStorageHolder<> with an DoInvoke that has an arity
103 // matching the number of unbound parameters, and knows the correct
104 // refcounting semantics for the target object if we are binding a class
105 // method.
106 //
107 // The Prebind functions do the above using type-inference, and template
108 // specializations.
109 //
110 // By default Prebind() will store copies of all bound parameters, and attempt
111 // to refcount a target object if the function being bound is a class method.
112 //
113 // To change this behavior, we introduce a set of argument wrappers
114 // (eg. Unretained(), and ConstRef()). These are simple container templates
115 // that are passed by value, and wrap a pointer to argument.
116 //
117 // ConstRef() allows Prebind()'s storage to preserve copy-semantics even if we
118 // wish to pass the invoked object a reference to the bound parameter.
119 //
120 // Unretained() allows us to tag an object for different refcounting semantics.
121 //
122 // These types are passed to the Unwrap() functions, and the MaybeRefcount()
123 // functions respectively to modify the behavior of Prebind(). The Unwrap()
124 // and MaybeRefcount() functions change behavior by doing partial
125 // specialization based on whether or not a parameter is a wrapper type.
126 //
127 // ConstRef() is similar to tr1::cref. Unretained() is specific to Chromium.
128 //
129 //
130 // WHY NOT TR1 FUNCTION/BIND?
131 //
132 // Direct use of tr1::function and tr1::bind was considered, but ultimately
133 // rejected because of the number of copy constructors invocations involved
134 // in the binding of arguments during construction, and the forwarding of
135 // arguments during invocation. These copies will no longer be an issue in
136 // C++0x because C++0x will support rvalue reference allowing for the compiler
137 // to avoid these copies. However, waiting for C++0x is not an option.
138 //
139 // Measured with valgrind on gcc version 4.4.3 (Ubuntu 4.4.3-4ubuntu5), the
140 // tr1::bind call itself will invoke a non-trivial copy constructor three times
141 // for each bound parameter. Also, each when passing a tr1::function, each
142 // bound argument will be copied again.
143 //
144 // In addition to the copies taken at binding and invocation, copying a
145 // tr1::function causes a copy to be made of all the bound parameters and
146 // state.
147 //
148 // Furthermore, in Chromium, it is desirable for the Callback to take a
149 // reference on a target object when representing a class method call. This
150 // is not supported by tr1.
151 //
152 // Lastly, tr1::function and tr1::bind has a more general and flexible API.
153 // This includes things like argument reordering by use of
154 // tr1::bind::placeholder, support for non-const reference parameters, and some
155 // limited amount of subtyping of the tr1::function object (eg.,
156 // tr1::function<int(int)> is convertable to tr1::function<void(int)>).
157 //
158 // These are not features that are required in Chromium. Some of them, such as
159 // allowing for reference parameters, and subtyping of functions, may actually
160 // because a source of errors. Removing support for these features actually
161 // allows for a simpler implementation, and a terser Currying API.
162 //
163 //
164 // WHY NOT GOOGLE CALLBACKS?
165 //
166 // The Google callback system also does not support refcounting. Furthermore,
167 // its implementation has a number of strange edge cases with respect to type
168 // convesrion of its arguments. In particular, the argument's constness must
169 // at times match exactly the function signature, or the type-inference might
170 // break. Given the above, writing a custom solution was easier.
171 //
172 //
173 // MISSING FUNCTIONALITY
174 // - Invoking the return of Prebind. Prebind(&foo).Run() does not work;
175 // - Binding arrays to functions that take a non-const pointer.
176 // Example:
177 // void Foo(const char* ptr);
178 // void Bar(char* ptr);
179 // Prebind(&Foo, "test");
180 // Prebind(&Bar, "tesT"); // This fails because ptr is not const.
181
182 namespace base {
183
184 // First, we forward declare the Callback class template. This informs the
185 // compiler that the template only has 1 type parameter which is the function
186 // signature that the Callback is representing.
187 //
188 // After this, create template specializations for 0-6 parameters. Note that
189 // even though the template typelist grows, the specialization still
190 // only has one type: the function signature.
191 //
192 // Also, note that the templated constructor should *not* be explicit. This is
193 // to allow for a natural assignment syntax from the result of Prebind(), which
194 // is not the same type as Callback(). See the description of Prebind for
195 // details.
196 template <typename Sig>
197 class Callback;
198
199 template <typename R>
200 class Callback<R(void)> {
201 public:
202 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
awong 2011/02/08 18:52:26 Yeah...I initially left it out too. The my unitte
203
204 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.
205
206 template <typename T>
207 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 mem
willchan no longer on Chromium 2011/02/07 23:25:15 I just noticed this constructor is implicit. Can y
awong 2011/02/08 18:52:26 No...unfortunately not without increasing the numb
awong 2011/02/08 18:52:26 This is to avoid an Addref/Unref pair. I'll add
208 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
209 invoker_storage_.swap(invoker_holder.invoker_storage_);
210 }
211
212 R Run(void) {
213 return polymorphic_invoke_(invoker_storage_.get());
214 }
215
216 private:
217 scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
218 PolymorphicInvoke polymorphic_invoke_;
219 };
220
221 template <typename R, typename A1>
222 class Callback<R(A1)> {
223 public:
224 Callback() : polymorphic_invoke_(NULL) { }
225
226 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&);
227
228 template <typename T>
229 Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
230 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
231 invoker_storage_.swap(invoker_holder.invoker_storage_);
232 }
233
234 R Run(const A1& a1) {
235 return polymorphic_invoke_(invoker_storage_.get(), a1);
236 }
237
238 private:
239 scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
240 PolymorphicInvoke polymorphic_invoke_;
241 };
242
243 template <typename R, typename A1, typename A2>
244 class Callback<R(A1, A2)> {
245 public:
246 Callback() : polymorphic_invoke_(NULL) { }
247
248 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&,
249 const A2&);
250
251 template <typename T>
252 Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
253 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
254 invoker_storage_.swap(invoker_holder.invoker_storage_);
255 }
256
257 R Run(const A1& a1, const A2& a2) {
258 return polymorphic_invoke_(invoker_storage_.get(), a1, a2);
259 }
260
261 private:
262 scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
263 PolymorphicInvoke polymorphic_invoke_;
264 };
265
266 template <typename R, typename A1, typename A2, typename A3>
267 class Callback<R(A1, A2, A3)> {
268 public:
269 Callback() : polymorphic_invoke_(NULL) { }
270
271 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&,
272 const A2&, const A3&);
273
274 template <typename T>
275 Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
276 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
277 invoker_storage_.swap(invoker_holder.invoker_storage_);
278 }
279
280 R Run(const A1& a1, const A2& a2, const A3& a3) {
281 return polymorphic_invoke_(invoker_storage_.get(), a1, a2, a3);
282 }
283
284 private:
285 scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
286 PolymorphicInvoke polymorphic_invoke_;
287 };
288
289 template <typename R, typename A1, typename A2, typename A3, typename A4>
290 class Callback<R(A1, A2, A3, A4)> {
291 public:
292 Callback() : polymorphic_invoke_(NULL) { }
293
294 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&,
295 const A2&, const A3&, const A4&);
296
297 template <typename T>
298 Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
299 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
300 invoker_storage_.swap(invoker_holder.invoker_storage_);
301 }
302
303 R Run(const A1& a1, const A2& a2, const A3& a3, const A4& a4) {
304 return polymorphic_invoke_(invoker_storage_.get(), a1, a2, a3, a4);
305 }
306
307 private:
308 scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
309 PolymorphicInvoke polymorphic_invoke_;
310 };
311
312 template <typename R, typename A1, typename A2, typename A3, typename A4,
313 typename A5>
314 class Callback<R(A1, A2, A3, A4, A5)> {
315 public:
316 Callback() : polymorphic_invoke_(NULL) { }
317
318 typedef R(*PolymorphicInvoke)(internal::InvokerStorageBase*, const A1&,
319 const A2&, const A3&, const A4&, const A5&);
320
321 template <typename T>
322 Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
323 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
324 invoker_storage_.swap(invoker_holder.invoker_storage_);
325 }
326
327 R Run(const A1& a1, const A2& a2, const A3& a3, const A4& a4, const A5& a5) {
328 return polymorphic_invoke_(invoker_storage_.get(), a1, a2, a3, a4, a5);
329 }
330
331 private:
332 scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
333 PolymorphicInvoke polymorphic_invoke_;
334 };
335
336 template <typename R, typename A1, typename A2, typename A3, typename A4,
337 typename A5, typename A6>
338 class Callback<R(A1, A2, A3, A4, A5, A6)> {
339 public:
340 Callback() : polymorphic_invoke_(NULL) { }
341
342 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
awong 2011/02/08 18:52:26 Fixed...but I wonder if we're trading pump-file re
343 const A2&, const A3&, const A4&, const A5&, const A6&);
344
345 template <typename T>
346 Callback(const internal::InvokerStorageHolder<T>& invoker_holder)
347 : polymorphic_invoke_(&T::FunctionTraits::DoInvoke) {
348 invoker_storage_.swap(invoker_holder.invoker_storage_);
349 }
350
351 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 format
awong 2011/02/08 18:52:26 Done.
352 const A6& a6) {
353 return polymorphic_invoke_(invoker_storage_.get(), a1, a2, a3, a4, a5, a6);
354 }
355
356 private:
357 scoped_refptr<internal::InvokerStorageBase> invoker_storage_;
358 PolymorphicInvoke polymorphic_invoke_;
359 };
360
361
362 // Syntactic sugar to make Callbacks<void(void)> easier to declare since it
363 // will be used in a lot of APIs with delayed execution.
364 typedef Callback<void(void)> Closure;
365
366 } // namespace base
367
368 #endif // BASE_UBER_CALLBACK_H
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698