/**
  * Low-level class holding the list of messages to be dispatched by a
  * {@link Looper}.  Messages are not added directly to a MessageQueue,
  * but rather through {@link Handler} objects associated with the Looper.
  *
  * <p>You can retrieve the MessageQueue for the current thread with
  * {@link Looper#myQueue() Looper.myQueue()}.
  */

boolean enqueueMessage(Message msg, long when) {
    if (msg.target == null) {
        throw new IllegalArgumentException("Message must have a target.");
    }
    if (msg.isInUse()) {
        throw new IllegalStateException(msg + " This message is already in use.");
    }

    synchronized (this) {
        if (mQuitting) {
            IllegalStateException e = new IllegalStateException(
                    msg.target + " sending message to a Handler on a dead thread");
            Log.w(TAG, e.getMessage(), e);
            msg.recycle();
            return false;
        }

        msg.markInUse();
        msg.when = when;
        Message p = mMessages;
        boolean needWake;
        if (p == null || when == 0 || when < p.when) {
            // New head, wake up the event queue if blocked.
            msg.next = p;
            mMessages = msg;
            needWake = mBlocked;
        } else {
            // Inserted within the middle of the queue.  Usually we don't have to wake
            // up the event queue unless there is a barrier at the head of the queue
            // and the message is the earliest asynchronous message in the queue.
            needWake = mBlocked && p.target == null && msg.isAsynchronous();
            Message prev;
            for (;;) {
                prev = p;
                p = p.next;
                if (p == null || when < p.when) {
                    break;
                }
                if (needWake && p.isAsynchronous()) {
                    needWake = false;
                }
            }
            msg.next = p; // invariant: p == prev.next
            prev.next = msg;
        }

        // We can assume mPtr != 0 because mQuitting is false.
        if (needWake) {
            nativeWake(mPtr);
        }
    }
    return true;
}

if (msg.target == null) {
    throw new IllegalArgumentException("Message must have a target.");
}

// 使用默认回调初始化 Handler 时移除消息
void removeMessages(Handler h, int what, Object object) {
    if (h == null) {
        return;
    }

    synchronized (this) {
        Message p = mMessages;

        // Remove all messages at front.
        while (p != null && p.target == h && p.what == what
                && (object == null || p.obj == object)) {
            Message n = p.next;
            mMessages = n;
            p.recycleUnchecked();
            p = n;
        }

        // Remove all messages after front.
        while (p != null) {
            Message n = p.next;
            if (n != null) {
                if (n.target == h && n.what == what
                    && (object == null || n.obj == object)) {
                    Message nn = n.next;
                    n.recycleUnchecked();
                    p.next = nn;
                    continue;
                }
            }
            p = n;
        }
    }
}

// 使用自定义回调初始化 Handler 时移除消息
void removeMessages(Handler h, Runnable r, Object object) {
    if (h == null || r == null) {
        return;
    }

    synchronized (this) {
        Message p = mMessages;

        // Remove all messages at front.
        while (p != null && p.target == h && p.callback == r
                && (object == null || p.obj == object)) {
            Message n = p.next;
            mMessages = n;
            p.recycleUnchecked();
            p = n;
        }

        // Remove all messages after front.
        while (p != null) {
            Message n = p.next;
            if (n != null) {
                if (n.target == h && n.callback == r
                    && (object == null || n.obj == object)) {
                    Message nn = n.next;
                    n.recycleUnchecked();
                    p.next = nn;
                    continue;
                }
            }
            p = n;
        }
    }
}

/**
  * Removes a synchronization barrier.
  *
  * @param token The synchronization barrier token that was returned by
  * {@link #postSyncBarrier}.
  *
  * @throws IllegalStateException if the barrier was not found.
  *
  * @hide
  */
@TestApi
public void removeSyncBarrier(int token) {
    // Remove a sync barrier token from the queue.
    // If the queue is no longer stalled by a barrier then wake it.
    synchronized (this) {
        Message prev = null;
        Message p = mMessages;
        while (p != null && (p.target != null || p.arg1 != token)) {
            prev = p;
            p = p.next;
        }
        if (p == null) {
            throw new IllegalStateException("The specified message queue synchronization "
                    + " barrier token has not been posted or has already been removed.");
        }
        final boolean needWake;
        if (prev != null) {
            prev.next = p.next;
            needWake = false;
        } else {
            mMessages = p.next;
            needWake = mMessages == null || mMessages.target != null;
        }
        p.recycleUnchecked();

        // If the loop is quitting then it is already awake.
        // We can assume mPtr != 0 when mQuitting is false.
        if (needWake && !mQuitting) {
            nativeWake(mPtr);
        }
    }
}

/**
  * Callback interface for discovering when a thread is going to block
  * waiting for more messages.
  */
public static interface IdleHandler {
    /**
      * Called when the message queue has run out of messages and will now
      * wait for more.  Return true to keep your idle handler active, false
      * to have it removed.  This may be called if there are still messages
      * pending in the queue, but they are all scheduled to be dispatched
      * after the current time.
      */
    boolean queueIdle();
}

/**
  * Add a new {@link IdleHandler} to this message queue.  This may be
  * removed automatically for you by returning false from
  * {@link IdleHandler#queueIdle IdleHandler.queueIdle()} when it is
  * invoked, or explicitly removing it with {@link #removeIdleHandler}.
  *
  * <p>This method is safe to call from any thread.
  *
  * @param handler The IdleHandler to be added.
  */
public void addIdleHandler(@NonNull IdleHandler handler) {
    if (handler == null) {
        throw new NullPointerException("Can't add a null IdleHandler");
    }
    synchronized (this) {
        mIdleHandlers.add(handler);
    }
}

/**
  * Remove an {@link IdleHandler} from the queue that was previously added
  * with {@link #addIdleHandler}.  If the given object is not currently
  * in the idle list, nothing is done.
  *
  * <p>This method is safe to call from any thread.
  *
  * @param handler The IdleHandler to be removed.
  */
public void removeIdleHandler(@NonNull IdleHandler handler) {
    synchronized (this) {
        mIdleHandlers.remove(handler);
    }
}

@UnsupportedAppUsage
Message next() {
    // Return here if the message loop has already quit and been disposed.
    // This can happen if the application tries to restart a looper after quit
    // which is not supported.


    // mPtr 是通过调用 nativeInit() 获取的返回值
    // 可以认为这个是 Native 层 MessageQueue 初始化后的指针地址
    final long ptr = mPtr;
    if (ptr == 0) {
        return null;
    }

    int pendingIdleHandlerCount = -1; // -1 only during first iteration
    int nextPollTimeoutMillis = 0;
    for (;;) {
        if (nextPollTimeoutMillis != 0) {
            Binder.flushPendingCommands();
        }

        nativePollOnce(ptr, nextPollTimeoutMillis);

        synchronized (this) {
            // Try to retrieve the next message.  Return if found.
            final long now = SystemClock.uptimeMillis();
            Message prevMsg = null;
            Message msg = mMessages;


            // 重点是 msg.target == null，如果满足说明这个 msg 是一个障栅消息
            // 那么就要阻塞这条消息之后的所有同步消息，而放行异步消息
            if (msg != null && msg.target == null) {
                // Stalled by a barrier.  Find the next asynchronous message in the queue.


                // 循环结束后有两种情况：
                // 1. 整个消息队列中都没有异步消息，则终止条件为：msg == null
                // 2. 找到了异步消息，则终止条件为：msg.isAsynchronous() == true
                do {
                    prevMsg = msg;
                    msg = msg.next;
                } while (msg != null && !msg.isAsynchronous());
            }
            if (msg != null) {
                // msg != null 有两种可能：
                // 1. 消息队列没阻塞，msg 是一条同步消息
                // 2. 消息队列被障栅消息阻塞了，但是找到了异步消息


                if (now < msg.when) {
                    // 说明还没到需要分发消息的时候，
                    // 则计算到需要分发消息中间的间隔，
                    // 在间隔时间后再唤醒消息队里进行分发


                    // Next message is not ready.  Set a timeout to wake up when it is ready.
                    nextPollTimeoutMillis = (int) Math.min(msg.when - now, Integer.MAX_VALUE);
                } else {
                    // 说明到了需要分发消息的时候


                    // Got a message.


                    // 开始分发消息了，不是阻塞状态
                    mBlocked = false;


                    // 由于将这条消息分发出去了，相当于要从链表里去掉这个消息
                    // 需要判断当前消息是不是第一个消息
                    // prevMsg 表示该 msg 的前一个消息
                    if (prevMsg != null) {
                        prevMsg.next = msg.next;
                    } else {
                        mMessages = msg.next;
                    }


                    // 由于该消息即将被分发出去，因此该消息的下一条就没用了
                    // 置为空，去掉无用引用，防止内存溢出
                    msg.next = null;
                    if (DEBUG) Log.v(TAG, "Returning message: " + msg);


                    // 把该 msg 标识为“使用中”
                    msg.markInUse();


                    // 返回这条 msg 作为需要处理的消息
                    return msg;
                }
            } else {
                // 说明 msg == null，此时有两种可能：
                // 1. 已经没有消息需要分发
                // 2. 当前队列被障栅消息阻塞了，却又没有异步消息（不论是否有同步消息）


                // No more messages.
                nextPollTimeoutMillis = -1;
            }

            // Process the quit message now that all pending messages have been handled.
            if (mQuitting) {
                // 如果当前消息队列是正在退出的状态
                // 则调用 dispose() 销毁 Native 层的消息队列
                dispose();
                return null;
            }


            // ======================
            // 以下为 IdleHandler 部分
            // ======================


            // If first time idle, then get the number of idlers to run.
            // Idle handles only run if the queue is empty or if the first message
            // in the queue (possibly a barrier) is due to be handled in the future.
            if (pendingIdleHandlerCount < 0
                    && (mMessages == null || now < mMessages.when)) {
                pendingIdleHandlerCount = mIdleHandlers.size();
            }
            if (pendingIdleHandlerCount <= 0) {
                // No idle handlers to run.  Loop and wait some more.
                mBlocked = true;
                continue;
            }

            if (mPendingIdleHandlers == null) {
                mPendingIdleHandlers = new IdleHandler[Math.max(pendingIdleHandlerCount, 4)];
            }
            mPendingIdleHandlers = mIdleHandlers.toArray(mPendingIdleHandlers);
        }

        // Run the idle handlers.
        // We only ever reach this code block during the first iteration.
        for (int i = 0; i < pendingIdleHandlerCount; i++) {
            final IdleHandler idler = mPendingIdleHandlers[i];
            mPendingIdleHandlers[i] = null; // release the reference to the handler

            boolean keep = false;
            try {
                keep = idler.queueIdle();
            } catch (Throwable t) {
                Log.wtf(TAG, "IdleHandler threw exception", t);
            }

            if (!keep) {
                synchronized (this) {
                    mIdleHandlers.remove(idler);
                }
            }
        }

        // Reset the idle handler count to 0 so we do not run them again.
        pendingIdleHandlerCount = 0;

        // While calling an idle handler, a new message could have been delivered
        // so go back and look again for a pending message without waiting.
        nextPollTimeoutMillis = 0;
    }
}