Package icyllis.modernui.core

# Class MessageQueue

java.lang.Object
icyllis.modernui.core.MessageQueue

public final class MessageQueue extends Object
Low-level class holding the list of messages to be dispatched by a `Looper`. Messages are not added directly to a MessageQueue, but rather through `Handler` objects associated with the Looper.

You can retrieve the MessageQueue for the current thread with `Looper.myQueue()`.

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static interface`
  `MessageQueue.IdleHandler`
  Callback interface for discovering when a thread is going to block waiting for more messages.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addIdleHandler(MessageQueue.IdleHandler handler)`
  Add a new `MessageQueue.IdleHandler` to this message queue.
  `boolean`
  `isIdle()`
  Returns true if the looper has no pending messages which are due to be processed.
  `boolean`
  `isPolling()`
  Returns whether this looper's thread is currently polling for more work to do.
  `int`
  `postSyncBarrier()`
  Posts a synchronization barrier to the Looper's message queue.
  `void`
  `removeIdleHandler(MessageQueue.IdleHandler handler)`
  Remove an `MessageQueue.IdleHandler` from the queue that was previously added with `addIdleHandler(icyllis.modernui.core.MessageQueue.IdleHandler)`.
  `void`
  `removeSyncBarrier(int token)`
  Removes a synchronization barrier.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Method Details

  - ### isIdle

    public boolean isIdle()
    Returns true if the looper has no pending messages which are due to be processed.

    This method is safe to call from any thread.

    Returns:
      True if the looper is idle.

  - ### addIdleHandler

    public void addIdleHandler(@NonNull MessageQueue.IdleHandler handler)
    Add a new `MessageQueue.IdleHandler` to this message queue. This may be removed automatically for you by returning false from `IdleHandler.queueIdle()` when it is invoked, or explicitly removing it with `removeIdleHandler(icyllis.modernui.core.MessageQueue.IdleHandler)`.

    This method is safe to call from any thread.

    Parameters:
      `handler` - The IdleHandler to be added.

  - ### removeIdleHandler

    public void removeIdleHandler(@NonNull MessageQueue.IdleHandler handler)
    Remove an `MessageQueue.IdleHandler` from the queue that was previously added with `addIdleHandler(icyllis.modernui.core.MessageQueue.IdleHandler)`. If the given object is not currently in the idle list, nothing is done.

    This method is safe to call from any thread.

    Parameters:
      `handler` - The IdleHandler to be removed.

  - ### isPolling

    public boolean isPolling()
    Returns whether this looper's thread is currently polling for more work to do. This is a good signal that the loop is still alive rather than being stuck handling a callback. Note that this method is intrinsically racy, since the state of the loop can change before you get the result back.

    This method is safe to call from any thread.

    Returns:
      True if the looper is currently polling for events.

  - ### postSyncBarrier

    public int postSyncBarrier()
    Posts a synchronization barrier to the Looper's message queue.

    Message processing occurs as usual until the message queue encounters the synchronization barrier that has been posted. When the barrier is encountered, later synchronous messages in the queue are stalled (prevented from being executed) until the barrier is released by calling `removeSyncBarrier(int)` and specifying the token that identifies the synchronization barrier.

    This method is used to immediately postpone execution of all subsequently posted synchronous messages until a condition is met that releases the barrier. Asynchronous messages (see `Message.isAsynchronous()`) are exempt from the barrier and continue to be processed as usual.

    This call must be always matched by a call to `removeSyncBarrier(int)` with the same token to ensure that the message queue resumes normal operation. Otherwise, the application will probably hang!

    Returns:
      A token that uniquely identifies the barrier. This token must be passed to `removeSyncBarrier(int)` to release the barrier.

  - ### removeSyncBarrier

    public void removeSyncBarrier(int token)
    Removes a synchronization barrier.
    Parameters:
      `token` - The synchronization barrier token that was returned by `postSyncBarrier()`.
    Throws:
      `IllegalStateException` - if the barrier was not found.