Allow base::DoNothing() to handle any argument list.
This changes the form of DoNothing() from a simple no-arg function to a class
that produces callbacks via templated operator(). This allows callers to
replace base::Bind(&base::DoNothing) with base::DoNothing() for a small
boilerplate reduction; more importantly, it allows using DoNothing() to replace
existing no-op functions/lambdas that took more than zero args, and thus had to
be manually declared. This removes dozens of such functions and around 600 LOC
total.
In a few places, DoNothing() can't be used directly, and this change also adds
explicit callback-generating Once<>() and Repeatedly<>() members that will
produce a callback with a specific signature.
BUG=811554
TEST=none
Cq-Include-Trybots: master.tryserver.blink:linux_trusty_blink_rel;master.tryserver.chromium.android:android_optional_gpu_tests_rel;master.tryserver.chromium.linux:linux_mojo;master.tryserver.chromium.linux:linux_optional_gpu_tests_rel;master.tryserver.chromium.linux:linux_vr;master.tryserver.chromium.mac:ios-simulator-cronet;master.tryserver.chromium.mac:ios-simulator-full-configs;master.tryserver.chromium.mac:mac_optional_gpu_tests_rel;master.tryserver.chromium.win:win_optional_gpu_tests_rel
Change-Id: I37f87b35c6c079a6a8c03ff18ec3a54e1237f126
Reviewed-on: https://chromium-review.googlesource.com/903416
Commit-Queue: Peter Kasting <[email protected]>
Reviewed-by: Jochen Eisinger <[email protected]>
Reviewed-by: Gabriel Charette <[email protected]>
Cr-Commit-Position: refs/heads/master@{#538953}diff --git a/docs/callback.md b/docs/callback.md
index 3c0d7ad..309f51167 100644
--- a/docs/callback.md
+++ b/docs/callback.md
@@ -164,6 +164,47 @@
}
```
+### Creating a Callback That Does Nothing
+
+Sometimes you need a callback that does nothing when run (e.g. test code that
+doesn't care to be notified about certain types of events). It may be tempting
+to pass a default-constructed callback of the right type:
+
+```cpp
+using MyCallback = base::OnceCallback<void(bool arg)>;
+void MyFunction(MyCallback callback) {
+ std::move(callback).Run(true); // Uh oh...
+}
+...
+MyFunction(MyCallback()); // ...this will crash when Run()!
+```
+
+Default-constructed callbacks are null, and thus cannot be Run(). Instead, use
+`base::DoNothing()`:
+
+```cpp
+...
+MyFunction(base::DoNothing()); // Can be Run(), will no-op
+```
+
+`base::DoNothing()` can be passed for any OnceCallback or RepeatingCallback that
+returns void.
+
+Implementation-wise, `base::DoNothing()` is actually a functor which produces a
+callback from `operator()`. This makes it unusable when trying to bind other
+arguments to it. Normally, the only reason to bind arguments to DoNothing() is
+to manage object lifetimes, and in these cases, you should strive to use idioms
+like DeleteSoon(), ReleaseSoon(), or RefCountedDeleteOnSequence instead. If you
+truly need to bind an argument to DoNothing(), or if you need to explicitly
+create a callback object (because implicit conversion through operator()() won't
+compile), you can instantiate directly:
+
+```cpp
+// Binds |foo_ptr| to a no-op OnceCallback takes a scoped_refptr<Foo>.
+// ANTIPATTERN WARNING: This should likely be changed to ReleaseSoon()!
+base::Bind(base::DoNothing::Once<scoped_refptr<Foo>>(), foo_ptr);
+```
+
### Passing Unbound Input Parameters
Unbound parameters are specified at the time a callback is `Run()`. They are
