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

diff --git a/api/current.txt b/api/current.txt
index 69d9a9e..4846540 100644 (file)
--- 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 0417ded..f5bca04 100644 (file)
--- 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() {