Describe preference for Executor over Handler in Android API guidelines
Elaborate on the history of using Executor vs. Handler as a means to direct a callback to a specific execution context in the Android API guidelines.
Include common exception requests and their typical outcomes.
PiperOrigin-RevId: 602712654
Change-Id: I1178863c9d4ab07e0ec30de5294ff13215120d5a
diff --git a/api-guidelines/methods.md b/api-guidelines/methods.md
index 4bdfe4b..0a0b8be 100644
--- a/api-guidelines/methods.md
+++ b/api-guidelines/methods.md
@@ -1407,6 +1407,43 @@
public void clearFooCallback()
```
+#### Why not `Handler` instead of `Executor`?
+
+Android's `Handler` was used as a standard for redirecting callback execution to
+a specific `Looper` thread in the past. This standard was changed to prefer
+`Executor` as most app developers manage their own thread pools, making the
+main or UI thread the only `Looper` thread available to the app. Use `Executor`
+to give developers the control they need to reuse their existing/preferred
+execution contexts.
+
+Modern concurrency libraries like kotlinx.coroutines or RxJava provide their own
+scheduling mechanisms that perform their own dispatch when needed, which makes
+it important to provide the ability to use a direct executor (e.g.
+`Runnable::run`) to avoid latency from double thread hops. (e.g. one hop to post
+to a `Looper` thread via a `Handler` followed by another hop from the app's
+concurrency framework.)
+
+Exceptions to this guideline are rare. Common appeals for an exception include:
+
+**I have to use a `Looper` because I need a `Looper` to `epoll` for the event.**
+This exception request is granted as the benefits of `Executor` described above
+cannot be realized in this situation.
+
+**I do not want app code to block my thread publishing the event.** This
+exception request is typically **not** granted for code that runs in an app
+process. Apps that get this wrong are only hurting themselves, not impacting
+overall system health. Apps that get it right or use a common concurrency
+framework should not pay additional latency penalties.
+
+**`Handler` is locally consistent with other similar APIs in the same class.**
+This exception request is granted **situationally.** Preference is for
+`Executor`-based overloads to be added, migrating `Handler` implementations to
+use the new `Executor` implementation. (`myHandler::post` is a valid
+`Executor`!) Depending on the size of the class, number of existing `Handler`
+methods, and likelihood that developers would need to use existing `Handler`
+based methods alongside the new method, an exception may be granted to add a
+new `Handler`-based method.
+
### Symmetry in Registration <a name="callbacks-symmetry"></a>
If there is a way to add or register something, there should also be a way to
