From 8709ba863eeef0166a1ed2139aa066498eb42ba5 Mon Sep 17 00:00:00 2001
From: Adam Powell <adamp@google.com>
Date: Wed, 21 Feb 2018 10:18:25 -0800
Subject: [PATCH] Add factory methods for async Handlers

Message.setAsynchronous is already public and this makes working
with posted messages that do not interact with UIs quite a bit nicer.

Added as factory methods for better integration with support shims
as well as generally encouraging the use of the handler callback
instead of subclassing for working with custom messages.

Bug: 73124158

Change-Id: I1210e7dc524fdf771e7af19297d5a822fdbd502c
---
 api/current.txt                   |  2 ++
 core/java/android/os/Handler.java | 39 ++++++++++++++++++++++++++++++-
 2 files changed, 40 insertions(+), 1 deletion(-)

diff --git a/api/current.txt b/api/current.txt
index 69d9a9e4c73ca..48465408a255f 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -33178,6 +33178,8 @@ package android.os {
     ctor public Handler(android.os.Handler.Callback);
     ctor public Handler(android.os.Looper);
     ctor public Handler(android.os.Looper, android.os.Handler.Callback);
+    method public static android.os.Handler createAsync(android.os.Looper);
+    method public static android.os.Handler createAsync(android.os.Looper, android.os.Handler.Callback);
     method public void dispatchMessage(android.os.Message);
     method public final void dump(android.util.Printer, java.lang.String);
     method public final android.os.Looper getLooper();
diff --git a/core/java/android/os/Handler.java b/core/java/android/os/Handler.java
index 0417ded829e8c..f5bca04ae1044 100644
--- a/core/java/android/os/Handler.java
+++ b/core/java/android/os/Handler.java
@@ -220,7 +220,7 @@ public class Handler {
      *
      * Asynchronous messages represent interrupts or events that do not require global ordering
      * with respect to synchronous messages.  Asynchronous messages are not subject to
-     * the synchronization barriers introduced by {@link MessageQueue#enqueueSyncBarrier(long)}.
+     * the synchronization barriers introduced by conditions such as display vsync.
      *
      * @param looper The looper, must not be null.
      * @param callback The callback interface in which to handle messages, or null.
@@ -236,6 +236,43 @@ public class Handler {
         mAsynchronous = async;
     }
 
+    /**
+     * Create a new Handler whose posted messages and runnables are not subject to
+     * synchronization barriers such as display vsync.
+     *
+     * <p>Messages sent to an async handler are guaranteed to be ordered with respect to one another,
+     * but not necessarily with respect to messages from other Handlers.</p>
+     *
+     * @see #createAsync(Looper, Callback) to create an async Handler with custom message handling.
+     *
+     * @param looper the Looper that the new Handler should be bound to
+     * @return a new async Handler instance
+     */
+    @NonNull
+    public static Handler createAsync(@NonNull Looper looper) {
+        if (looper == null) throw new NullPointerException("looper must not be null");
+        return new Handler(looper, null, true);
+    }
+
+    /**
+     * Create a new Handler whose posted messages and runnables are not subject to
+     * synchronization barriers such as display vsync.
+     *
+     * <p>Messages sent to an async handler are guaranteed to be ordered with respect to one another,
+     * but not necessarily with respect to messages from other Handlers.</p>
+     *
+     * @see #createAsync(Looper) to create an async Handler without custom message handling.
+     *
+     * @param looper the Looper that the new Handler should be bound to
+     * @return a new async Handler instance
+     */
+    @NonNull
+    public static Handler createAsync(@NonNull Looper looper, @NonNull Callback callback) {
+        if (looper == null) throw new NullPointerException("looper must not be null");
+        if (callback == null) throw new NullPointerException("callback must not be null");
+        return new Handler(looper, callback, true);
+    }
+
     /** @hide */
     @NonNull
     public static Handler getMain() {