Make Message.setAsynchronous() public.

There are many cases in real world applications where it is desirable
to continue processing messages on the Looper even when most other
messages have been suspended by a synchronization barrier pending
completion of the next drawing frame on vsync.

Internally the framework is able to mark certain messages as being
independent of these higher level synchronization invariants by
flagging them as asynchronous.

This change exposes the existing function and improves on the
documentation so that it is clearer what is meant by asynchronous.

Bug: 18283959
Change-Id: I775e4c95938123a364b21a9f2c39019bf37e1afd

3 files changed, 27 insertions, 21 deletions

diff --git a/api/current.txt b/api/current.txt
index 1a882ac5a6e2..746d31a1ecd1 100644
--- a/api/current.txt
+++ b/api/current.txt
@@ -21854,6 +21854,7 @@ package android.os {
     method public android.os.Bundle getData();
     method public android.os.Handler getTarget();
     method public long getWhen();
+    method public boolean isAsynchronous();
     method public static android.os.Message obtain();
     method public static android.os.Message obtain(android.os.Message);
     method public static android.os.Message obtain(android.os.Handler);
@@ -21865,6 +21866,7 @@ package android.os {
     method public android.os.Bundle peekData();
     method public void recycle();
     method public void sendToTarget();
+    method public void setAsynchronous(boolean);
     method public void setData(android.os.Bundle);
     method public void setTarget(android.os.Handler);
     method public void writeToParcel(android.os.Parcel, int);
diff --git a/core/java/android/os/Handler.java b/core/java/android/os/Handler.java
index 52db0609854e..878b7a0e8e10 100644
--- a/core/java/android/os/Handler.java
+++ b/core/java/android/os/Handler.java
@@ -156,7 +156,7 @@ public class Handler {
      * one that is strictly asynchronous.
      *
      * Asynchronous messages represent interrupts or events that do not require global ordering
-     * with represent to synchronous messages.  Asynchronous messages are not subject to
+     * with respect to synchronous messages.  Asynchronous messages are not subject to
      * the synchronization barriers introduced by {@link MessageQueue#enqueueSyncBarrier(long)}.
      *
      * @param async If true, the handler calls {@link Message#setAsynchronous(boolean)} for
@@ -176,7 +176,7 @@ public class Handler {
      * one that is strictly asynchronous.
      *
      * Asynchronous messages represent interrupts or events that do not require global ordering
-     * with represent to synchronous messages.  Asynchronous messages are not subject to
+     * with respect to synchronous messages.  Asynchronous messages are not subject to
      * the synchronization barriers introduced by {@link MessageQueue#enqueueSyncBarrier(long)}.
      *
      * @param callback The callback interface in which to handle messages, or null.
@@ -214,7 +214,7 @@ public class Handler {
      * one that is strictly asynchronous.
      *
      * Asynchronous messages represent interrupts or events that do not require global ordering
-     * with represent to synchronous messages.  Asynchronous messages are not subject to
+     * with respect to synchronous messages.  Asynchronous messages are not subject to
      * the synchronization barriers introduced by {@link MessageQueue#enqueueSyncBarrier(long)}.
      *
      * @param looper The looper, must not be null.
diff --git a/core/java/android/os/Message.java b/core/java/android/os/Message.java
index 6a0bddc5ee1b..8c758470c83a 100644
--- a/core/java/android/os/Message.java
+++ b/core/java/android/os/Message.java
@@ -417,38 +417,42 @@ public final class Message implements Parcelable {
     }
 
     /**
-     * Returns true if the message is asynchronous.
-     *
-     * Asynchronous messages represent interrupts or events that do not require global ordering
-     * with represent to synchronous messages.  Asynchronous messages are not subject to
-     * the synchronization barriers introduced by {@link MessageQueue#enqueueSyncBarrier(long)}.
+     * Returns true if the message is asynchronous, meaning that it is not
+     * subject to {@link Looper} synchronization barriers.
      *
      * @return True if the message is asynchronous.
      *
      * @see #setAsynchronous(boolean)
-     * @see MessageQueue#enqueueSyncBarrier(long)
-     * @see MessageQueue#removeSyncBarrier(int)
-     *
-     * @hide
      */
     public boolean isAsynchronous() {
         return (flags & FLAG_ASYNCHRONOUS) != 0;
     }
 
     /**
-     * Sets whether the message is asynchronous.
-     *
-     * Asynchronous messages represent interrupts or events that do not require global ordering
-     * with represent to synchronous messages.  Asynchronous messages are not subject to
-     * the synchronization barriers introduced by {@link MessageQueue#enqueueSyncBarrier(long)}.
+     * Sets whether the message is asynchronous, meaning that it is not
+     * subject to {@link Looper} synchronization barriers.
+     * <p>
+     * Certain operations, such as view invalidation, may introduce synchronization
+     * barriers into the {@link Looper}'s message queue to prevent subsequent messages
+     * from being delivered until some condition is met.  In the case of view invalidation,
+     * messages which are posted after a call to {@link android.view.View#invalidate}
+     * are suspended by means of a synchronization barrier until the next frame is
+     * ready to be drawn.  The synchronization barrier ensures that the invalidation
+     * request is completely handled before resuming.
+     * </p><p>
+     * Asynchronous messages are exempt from synchronization barriers.  They typically
+     * represent interrupts, input events, and other signals that must be handled independently
+     * even while other work has been suspended.
+     * </p><p>
+     * Note that asynchronous messages may be delivered out of order with respect to
+     * synchronous messages although they are always delivered in order among themselves.
+     * If the relative order of these messages matters then they probably should not be
+     * asynchronous in the first place.  Use with caution.
+     * </p>
      *
      * @param async True if the message is asynchronous.
      *
      * @see #isAsynchronous()
-     * @see MessageQueue#enqueueSyncBarrier(long)
-     * @see MessageQueue#removeSyncBarrier(int)
-     *
-     * @hide
      */
     public void setAsynchronous(boolean async) {
         if (async) {