Android 并发模型

// ActivityThread.main() —— 应用进程的 Java 入口
public static void main(String[] args) {
    // 为当前线程（即主线程）创建一个 Looper 实例
    // prepareMainLooper 内部会调用 prepare()，并把自己标记为"主Looper"，不可退出
    Looper.prepareMainLooper();
 
    // 创建 ActivityThread 实例，它并不是一个 Thread，而是应用的"管家"对象
    ActivityThread thread = new ActivityThread();
 
    // attach(false) 向 AMS 注册自己，告诉系统"我准备好了，可以接收组件调度了"
    thread.attach(false);
 
    // 获取主线程的 Handler（即内部类 H），后续所有组件生命周期回调都通过它分发
    if (sMainThreadHandler == null) {
        sMainThreadHandler = thread.getHandler();
    }
 
    // 进入无限循环，开始从 MessageQueue 中逐条取出消息并分发处理
    // 这一行代码之后的任何语句在正常情况下都不会被执行
    Looper.loop();
 
    // 如果走到这里，说明 loop() 退出了，抛出异常表示主线程意外终止
    throw new RuntimeException("Main thread loop unexpectedly exited");
}

// ViewRootImpl.checkThread() —— UI 线程检查
void checkThread() {
    // mThread 是在 ViewRootImpl 构造时记录的创建线程（即主线程）
    if (mThread != Thread.currentThread()) {
        // 如果当前调用线程不是主线程，直接抛出异常
        throw new CalledFromWrongThreadException(
            "Only the original thread that created a view hierarchy can touch its views.");
    }
}

// 最基础的工作线程创建方式
val workerThread = Thread {
    // 这里运行在新线程中，可以执行耗时操作
    val result = performNetworkRequest()  // 假设这是一个网络请求
 
    // ❌ 错误：不能在工作线程直接操作 UI
    // textView.text = result
 
    // ✅ 正确：通过 Handler 或 runOnUiThread 切回主线程
    runOnUiThread {
        // 这个 lambda 会被 post 到主线程的 MessageQueue 中
        textView.text = result  // 安全地更新 UI
    }
}
// 设置为守护线程（可选），避免阻止 JVM 退出
workerThread.isDaemon = true
// 启动线程
workerThread.start()

// 创建一个固定大小为 4 的线程池
val executor: ExecutorService = Executors.newFixedThreadPool(4)
 
// 提交任务到线程池（不关心返回值）
executor.execute {
    // 运行在线程池中的某个工作线程上
    val data = loadDataFromDatabase()  // 耗时的数据库操作
    // 处理完成后切回主线程更新 UI
    mainHandler.post {
        recyclerView.adapter = DataAdapter(data)
    }
}
 
// 提交任务并获取 Future（可以拿到返回值或取消任务）
val future: Future<String> = executor.submit(Callable {
    // 工作线程中执行，返回一个 String 结果
    fetchUserName()
})
// 注意：future.get() 会阻塞当前线程直到结果返回，不要在主线程调用！

// 在 ViewModel 中使用协程执行异步任务
class UserViewModel : ViewModel() {
 
    // viewModelScope 是 ViewModel 自带的协程作用域
    // 当 ViewModel 被清除时，scope 会自动取消所有协程，避免泄漏
    fun loadUser() {
        viewModelScope.launch {
            // launch 默认运行在 Dispatchers.Main（主线程）
            // 但 withContext 会把代码块切换到 IO 线程执行
            val user = withContext(Dispatchers.IO) {
                // 这里运行在 IO 线程池中（适合 I/O 密集型任务）
                repository.fetchUser()  // 网络请求或数据库查询
            }
            // withContext 执行完毕后，自动切回 Main 线程
            // 直接更新 LiveData，观察者会在主线程收到通知
            _userLiveData.value = user
        }
    }
}

// 线程不安全的计数器示例
class UnsafeCounter {
    // 普通 Int 变量，多线程下读写不安全
    var count = 0
 
    // 自增操作看似一行代码，实际上包含三个步骤：
    // 1. 从内存读取 count 的当前值到寄存器（READ）
    // 2. 在寄存器中将值加 1（MODIFY）
    // 3. 将新值写回内存（WRITE）
    // 如果两个线程同时执行步骤 1，都读到了 count = 5，
    // 那么两个线程都会写回 6，实际上只增加了 1 而不是 2
    fun increment() {
        count++  // ❌ 非原子操作，存在竞态条件（Race Condition）
    }
}
 
// 验证线程不安全
fun main() {
    val counter = UnsafeCounter()
    // 创建 1000 个协程，每个协程调用 increment() 1000 次
    // 预期最终结果应该是 1,000,000
    runBlocking {
        repeat(1000) {
            launch(Dispatchers.Default) {
                repeat(1000) {
                    counter.increment()
                }
            }
        }
    }
    // 实际打印的结果几乎不可能是 1,000,000
    // 而是一个小于 1,000,000 的随机数，如 987,653
    println("Count = ${counter.count}")
}

// ❌ 线程不安全的单例 —— Double-Check Locking 的错误实现
class DatabaseHelper private constructor(context: Context) {
 
    companion object {
        // 没有 @Volatile 注解！
        // 在 JVM 中，对象创建分为三步：1.分配内存 2.初始化 3.引用赋值
        // 由于指令重排序（Instruction Reordering），可能先执行 3 再执行 2
        // 导致另一个线程看到 instance 不为 null，但对象还未初始化完成
        private var instance: DatabaseHelper? = null
 
        fun getInstance(context: Context): DatabaseHelper {
            // 第一次检查（无锁，快速路径）
            if (instance == null) {
                // 加锁
                synchronized(this) {
                    // 第二次检查
                    if (instance == null) {
                        instance = DatabaseHelper(context.applicationContext)
                    }
                }
            }
            // 可能返回一个"半初始化"的对象！
            return instance!!
        }
    }
}
 
// ✅ 正确的 Kotlin 写法 —— 利用 Kotlin 的 lazy 委托
class DatabaseHelper private constructor(context: Context) {
 
    companion object {
        // lazy 默认使用 LazyThreadSafetyMode.SYNCHRONIZED
        // 内部使用了 Double-Check Locking + volatile，保证线程安全且只初始化一次
        @Volatile
        private var instance: DatabaseHelper? = null
 
        fun getInstance(context: Context): DatabaseHelper {
            // 使用 Kotlin 的 also 让代码更简洁
            return instance ?: synchronized(this) {
                instance ?: DatabaseHelper(context.applicationContext).also {
                    instance = it
                }
            }
        }
    }
}

// 线程安全的计数器 —— 使用 AtomicInteger
class SafeCounter {
    // AtomicInteger 内部使用 CAS 操作保证原子性
    // CAS 是 CPU 级别的指令：比较内存中的值是否等于预期值，如果是则更新
    private val count = AtomicInteger(0)
 
    fun increment() {
        // incrementAndGet() 是原子操作，即使多线程并发调用也不会丢失计数
        count.incrementAndGet()
    }
 
    // 读取也是原子的
    fun get(): Int = count.get()
}

// 使用 synchronized 保护共享列表
class SafeList {
    // 被保护的共享资源
    private val list = mutableListOf<String>()
 
    // 使用 synchronized 确保同一时刻只有一个线程能进入代码块
    fun add(item: String) {
        synchronized(list) {
            // 获取到 list 对象的内置锁（Monitor Lock）后才能执行
            list.add(item)
        }
        // 离开 synchronized 块时自动释放锁
    }
 
    fun getAll(): List<String> {
        synchronized(list) {
            // 返回一个防御性拷贝（Defensive Copy）
            // 避免外部拿到引用后在不同线程修改
            return list.toList()
        }
    }
}

// 使用 @WorkerThread 标注，告诉调用者：这个方法必须在工作线程调用
@WorkerThread
fun fetchDataFromNetwork(): String {
    // 网络请求，可能耗时数秒
    return api.getData()
}
 
// 使用 @MainThread 标注，告诉调用者：这个方法必须在主线程调用
@MainThread
fun updateUI(data: String) {
    textView.text = data
}

// Looper.java
// 使用 ThreadLocal 存储当前线程的 Looper 实例
// 所有线程共享同一个 sThreadLocal 对象，但各自 get() 返回不同的 Looper
static final ThreadLocal<Looper> sThreadLocal = new ThreadLocal<Looper>();

┌─────────────────────────────────────────────────────────────────┐
│                   静态变量 Looper.sThreadLocal                    │
│                  （全局唯一的 ThreadLocal 实例）                    │
└──────────────────────────┬──────────────────────────────────────┘
                           │
            ┌──────────────┼──────────────────┐
            ▼              ▼                  ▼
   ┌─────────────┐  ┌──────────────┐  ┌──────────────┐
   │  主线程 Main │  │ WorkerThread │  │ HandlerThread│
   │ ┌─────────┐ │  │ ┌──────────┐ │  │ ┌──────────┐ │
   │ │ThreadLo-│ │  │ │ThreadLo- │ │  │ │ThreadLo- │ │
   │ │calMap   │ │  │ │calMap    │ │  │ │calMap    │ │
   │ │         │ │  │ │          │ │  │ │          │ │
   │ │key:sTL  │ │  │ │key: sTL  │ │  │ │key: sTL  │ │
   │ │val:Loop-│ │  │ │val: Loop-│ │  │ │val: Loop-│ │
   │ │  er#main│ │  │ │  er#work │ │  │ │  er#ht   │ │
   │ └─────────┘ │  │ └──────────┘ │  │ └──────────┘ │
   └─────────────┘  └──────────────┘  └──────────────┘

// Looper.java — prepare 方法（简化版源码）
public static void prepare() {
    // 委托给带参数的私有方法，参数表示"是否允许退出"
    // 普通线程的 Looper 允许退出（quitAllowed = true）
    prepare(true);
}
 
private static void prepare(boolean quitAllowed) {
    // 【关键守卫】检查当前线程是否已经有 Looper
    // 如果 sThreadLocal.get() 不为 null，说明已经调用过 prepare
    if (sThreadLocal.get() != null) {
        // 直接抛出异常！一个线程只能 prepare 一次
        throw new RuntimeException("Only one Looper may be created per thread");
    }
    // 创建新的 Looper 实例，并存入当前线程的 ThreadLocal 中
    // 这一行同时完成了 Looper 的创建和与线程的绑定
    sThreadLocal.set(new Looper(quitAllowed));
}

// Looper.java — 构造函数
private Looper(boolean quitAllowed) {
    // 在构造 Looper 的同时，创建与之绑定的 MessageQueue
    // 这保证了 Looper 和 MessageQueue 是一对一的关系
    mQueue = new MessageQueue(quitAllowed);
    // 记录当前所在线程的引用，用于后续的线程归属校验
    mThread = Thread.currentThread();
}

// ActivityThread.java — main 方法（极简化）
public static void main(String[] args) {
    // 第一步：为主线程创建 Looper（quitAllowed = false）
    Looper.prepareMainLooper();
 
    // ... 创建 ActivityThread 实例，注册到 AMS 等 ...
 
    // 最后一步：启动消息循环（注意：这行之后的代码正常情况下不会执行）
    Looper.loop();
 
    // 如果执行到这里，说明 loop() 退出了，抛出异常
    throw new RuntimeException("Main thread loop unexpectedly exited");
}

// Looper.java — 主线程专用的 prepare
public static void prepareMainLooper() {
    // 调用 prepare，但 quitAllowed = false（不允许退出）
    prepare(false);
    // 使用 synchronized 保护 sMainLooper 的赋值（防止并发问题）
    synchronized (Looper.class) {
        // sMainLooper 是一个静态变量，记录主线程的 Looper
        // 同样只允许赋值一次
        if (sMainLooper != null) {
            throw new IllegalStateException("The main Looper has already been prepared.");
        }
        // 从当前线程的 ThreadLocal 中取出刚创建的 Looper
        sMainLooper = myLooper();
    }
}

// Looper.java — loop 方法（简化版源码，保留核心逻辑）
public static void loop() {
    // 获取当前线程绑定的 Looper（即 prepare 时存入 ThreadLocal 的那个）
    final Looper me = myLooper();
    // 如果当前线程没有 prepare 过，直接抛异常
    if (me == null) {
        throw new RuntimeException("No Looper; Looper.prepare() wasn't called on this thread.");
    }
 
    // 拿到 Looper 关联的 MessageQueue
    final MessageQueue queue = me.mQueue;
 
    // 核心：无限循环 —— 这就是 Android 消息驱动的"心跳"
    for (;;) {
        // 从 MessageQueue 中取下一条消息
        // 【关键】如果队列为空或最近的消息还没到时间，next() 会阻塞（不消耗 CPU）
        Message msg = queue.next();
 
        // 如果 next() 返回 null，说明 MessageQueue 正在退出
        // 这是 loop() 退出的 **唯一正常途径**
        if (msg == null) {
            return;
        }
 
        // msg.target 就是发送这条消息的 Handler
        // 调用 Handler 的 dispatchMessage，完成消息的分发与处理
        // 注意：这里是在 Looper 所在的线程中执行的（对主线程来说就是主线程）
        msg.target.dispatchMessage(msg);
 
        // 消息处理完毕，回收 Message 对象到复用池
        // 避免频繁创建 Message 带来的 GC 压力
        msg.recycleUnchecked();
    }
}

// Looper.java — 退出方法
 
// 方式一：立即退出（不安全）
public void quit() {
    // 直接调用 MessageQueue 的 quit，参数 safe = false
    mQueue.quit(false);
}
 
// 方式二：安全退出（推荐）
public void quitSafely() {
    // 调用 MessageQueue 的 quit，参数 safe = true
    mQueue.quit(true);
}

// MessageQueue.java — quit 方法（简化版）
void quit(boolean safe) {
    // 检查是否允许退出（主线程的 Looper 创建时 quitAllowed = false）
    if (!mQuitAllowed) {
        // 主线程调用 quit 会直接抛异常
        throw new IllegalStateException("Main thread not allowed to quit.");
    }
 
    synchronized (this) {
        // 防止重复调用
        if (mQuitting) {
            return;
        }
        // 标记为正在退出
        mQuitting = true;
 
        if (safe) {
            // 安全退出：只移除「尚未到执行时间」的延迟消息
            // 已经到时间的消息（when <= now）会被保留并正常处理完
            removeAllFutureMessagesLocked();
        } else {
            // 立即退出：移除队列中的「所有」消息，不管是否到时间
            removeAllMessagesLocked();
        }
 
        // 唤醒可能正在 next() 中阻塞的线程
        // 唤醒后 next() 检测到 mQuitting = true，会返回 null
        nativeWake(mPtr);
    }
}

val thread = Thread {
    val handler = Handler(Looper.myLooper()!!)
    handler.post { Log.d("Test", "Hello from worker") }
}
thread.start()

// Message.java 中的链表指针字段
// 每个 Message 对象都持有一个指向"下一条消息"的引用
// 这就是单链表的"指针"——不需要额外的 Node 包装类
/*package*/ Message next;

// MessageQueue.java
// mMessages 指向链表头部，即"时间最早应被处理的那条消息"
// 如果为 null，说明队列为空
Message mMessages;

mMessages (队列头指针)
    │
    ▼
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Message A │    │ Message B │    │ Message C │    │ Message D │
│ when=100  │───▶│ when=150  │───▶│ when=200  │───▶│ when=350  │───▶ null
│ what=1    │    │ what=2    │    │ what=3    │    │ what=1    │
│ target=H1 │    │ target=H2 │    │ target=H1 │    │ target=H3 │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
   (头节点)                                         (尾节点)
   最早处理                                         最晚处理

// MessageQueue.java — enqueueMessage 入队核心逻辑
boolean enqueueMessage(Message msg, long when) {
    // 【校验1】msg.target 不能为 null（除了同步屏障消息，后面章节会讲）
    if (msg.target == null) {
        throw new IllegalArgumentException("Message must have a target.");
    }
 
    // 使用 synchronized 锁住 this（即当前 MessageQueue 实例）
    // 保证多线程并发入队时的线程安全
    synchronized (this) {
        // 【校验2】如果队列正在退出（quit 被调用），则回收消息并返回 false
        if (mQuitting) {
            msg.recycle();          // 将消息回收到复用池
            return false;           // 入队失败
        }
 
        // 将传入的时间戳记录到 msg.when 字段
        msg.when = when;
 
        // p 指向当前的链表头节点
        Message p = mMessages;
 
        // needWake 标记：本次入队后是否需要唤醒正在休眠的线程
        boolean needWake;
 
        // 【情况1】链表为空（p == null）
        // 【情况2】新消息的 when 为 0（即立即执行，最高优先级）
        // 【情况3】新消息的 when 小于头节点的 when（比当前最早的消息还早）
        // 以上三种情况，新消息都应该成为新的头节点
        if (p == null || when == 0 || when < p.when) {
            msg.next = p;           // 新消息的 next 指向原来的头节点
            mMessages = msg;        // 更新头指针为新消息
            needWake = mBlocked;    // 如果线程正在休眠（mBlocked=true），则需要唤醒
        } else {
            // 【情况4】新消息需要插入到链表中间或尾部
            // needWake 通常为 false，除非头节点是同步屏障且新消息是最早的异步消息
            needWake = mBlocked && p.target == null && msg.isAsynchronous();
 
            // prev 用于记录"插入位置的前一个节点"
            Message prev;
            // 遍历链表，找到第一个 when 大于新消息 when 的节点
            for (;;) {
                prev = p;           // 记录当前节点为 prev
                p = p.next;         // p 移动到下一个节点
                // 如果到达链表尾部（p == null），或找到了一个 when 更大的节点
                if (p == null || when < p.when) {
                    break;          // 跳出循环，插入位置确定
                }
                // 如果遍历过程中发现异步消息相关条件，重置 needWake
                if (needWake && p.isAsynchronous()) {
                    needWake = false;
                }
            }
            // 执行链表插入操作：
            msg.next = p;           // 新消息的 next 指向"插入位置的后一个节点"
            prev.next = msg;        // 前一个节点的 next 指向新消息
        }
 
        // 如果 needWake 为 true，调用 native 方法唤醒线程
        if (needWake) {
            nativeWake(mPtr);       // mPtr 是 native 层 MessageQueue 的指针
        }
    }
    return true;                    // 入队成功
}

// MessageQueue.java — next() 取出消息的核心逻辑
Message next() {
    // mPtr 是 native 层 NativeMessageQueue 的指针
    // 如果为 0，说明 MessageQueue 已被销毁，直接返回 null
    final long ptr = mPtr;
    if (ptr == 0) {
        return null;
    }
 
    // pendingIdleHandlerCount：待执行的 IdleHandler 数量
    // 首次进入循环时设为 -1，表示"尚未统计"
    int pendingIdleHandlerCount = -1;
 
    // nextPollTimeoutMillis：下一次 nativePollOnce 的超时时长
    // 0 表示立即返回（不休眠）
    // -1 表示无限期休眠（直到被唤醒）
    // 正数表示休眠指定毫秒数
    int nextPollTimeoutMillis = 0;
 
    // 进入无限循环——每次循环尝试取出一条消息
    for (;;) {
        // 【关键调用】nativePollOnce：线程在此处休眠
        // 休眠时长由 nextPollTimeoutMillis 决定
        // 这是一个 native 方法，底层通过 epoll_wait 实现
        nativePollOnce(ptr, nextPollTimeoutMillis);
 
        // 加锁，准备操作链表
        synchronized (this) {
            // 获取当前时间（开机以来的毫秒数，不含深度睡眠）
            final long now = SystemClock.uptimeMillis();
 
            Message prevMsg = null;  // 用于同步屏障逻辑（追踪前一个节点）
            Message msg = mMessages; // msg 指向链表头节点
 
            // 【同步屏障检测】如果头节点的 target 为 null，说明是同步屏障
            // 需要跳过所有同步消息，找到第一条异步消息（后续章节详述）
            if (msg != null && msg.target == null) {
                do {
                    prevMsg = msg;
                    msg = msg.next;
                } while (msg != null && !msg.isAsynchronous());
            }
 
            if (msg != null) {
                if (now < msg.when) {
                    // 【情况A】消息尚未到期
                    // 计算需要休眠的时长（最多不超过 Integer.MAX_VALUE）
                    nextPollTimeoutMillis = (int) Math.min(
                        msg.when - now, Integer.MAX_VALUE);
                } else {
                    // 【情况B】消息已到期，可以取出
                    mBlocked = false;   // 标记线程不再处于休眠状态
 
                    // 将 msg 从链表中摘除
                    if (prevMsg != null) {
                        // 存在同步屏障时，prevMsg 不为 null
                        prevMsg.next = msg.next;
                    } else {
                        // 正常情况：直接更新头指针
                        mMessages = msg.next;
                    }
                    msg.next = null;    // 断开 msg 的 next 引用
 
                    // 标记消息为"使用中"，防止重复回收
                    msg.markInUse();
 
                    // 返回这条消息给 Looper.loop() 进行分发
                    return msg;
                }
            } else {
                // 【情况C】队列中没有消息（或没有异步消息可处理）
                // 设置为 -1，表示无限期休眠
                nextPollTimeoutMillis = -1;
            }
 
            // 如果正在退出（quit 被调用），执行清理并返回 null
            if (mQuitting) {
                dispose();           // 释放 native 资源
                return null;         // Looper.loop() 收到 null 会退出循环
            }
 
            // === IdleHandler 处理逻辑（后续章节详述）===
            // 如果没有消息需要处理（即将休眠），执行 IdleHandler 回调
            if (pendingIdleHandlerCount < 0
                    && (mMessages == null || now < mMessages.when)) {
                pendingIdleHandlerCount = mIdleHandlers.size();
            }
            if (pendingIdleHandlerCount <= 0) {
                // 没有 IdleHandler 需要执行
                mBlocked = true;     // 标记线程即将休眠
                continue;            // 回到循环头部，执行 nativePollOnce 休眠
            }
            // ... IdleHandler 执行逻辑省略 ...
        }
        // ... IdleHandler 执行逻辑省略 ...
 
        // IdleHandler 执行完毕后，重置计数，并将 nextPollTimeoutMillis 设为 0
        // 因为 IdleHandler 执行期间可能有新消息入队，需要立即检查
        pendingIdleHandlerCount = 0;
        nextPollTimeoutMillis = 0;
    }
}

// ---- Handler.java 发送链路核心源码 ----
 
// 【入口1】发送一个 Message，delay 默认为 0
public final boolean sendMessage(@NonNull Message msg) {
    // 直接委托给 sendMessageDelayed，延迟时间为 0（立即执行）
    return sendMessageDelayed(msg, 0);
}
 
// 【入口2】发送一个 Runnable，内部包装成 Message
public final boolean post(@NonNull Runnable r) {
    // getPostMessage(r) 把 Runnable 包装为 Message（赋值给 msg.callback）
    // 然后同样走 sendMessageDelayed，延迟时间为 0
    return sendMessageDelayed(getPostMessage(r), 0);
}
 
// 【汇聚点1】带延迟的发送，将相对延迟转为绝对时间
public final boolean sendMessageDelayed(@NonNull Message msg, long delayMillis) {
    // 如果传入负数延迟，修正为 0（不允许"回到过去"）
    if (delayMillis < 0) {
        delayMillis = 0;
    }
    // 用当前系统启动时间 + 延迟，算出消息应被处理的绝对时刻
    // uptimeMillis 不受系统时钟修改和休眠影响，保证时序准确
    return sendMessageAtTime(msg, SystemClock.uptimeMillis() + delayMillis);
}
 
// 【汇聚点2】指定绝对时间发送，真正准备入队
public boolean sendMessageAtTime(@NonNull Message msg, long uptimeMillis) {
    // 获取当前 Handler 绑定的 MessageQueue
    MessageQueue queue = mQueue;
    // 如果 queue 为 null，说明 Looper 未初始化或已退出
    if (queue == null) {
        RuntimeException e = new RuntimeException(
                this + " sendMessageAtTime() called with no mQueue");
        Log.w("Looper", e.getMessage(), e);
        // 返回 false 表示发送失败
        return false;
    }
    // 调用私有方法 enqueueMessage，执行真正的入队操作
    return enqueueMessage(queue, msg, uptimeMillis);
}
 
// 【终点】私有入队方法 —— 所有发送路径的最终汇聚
private boolean enqueueMessage(@NonNull MessageQueue queue, @NonNull Message msg,
        long uptimeMillis) {
    // ★ 关键：将 msg.target 设为当前 Handler 自身
    // 这样 Looper 在取出消息后，就知道该交给哪个 Handler 来处理
    msg.target = this;
 
    // 获取当前 Handler 的 uid（用于跨进程消息场景的身份标识）
    msg.workSourceUid = ThreadLocalWorkSource.getUid();
 
    // 如果当前 Handler 被设置为异步模式（构造时传入 async = true）
    // 则将消息标记为异步消息（不受同步屏障阻挡）
    if (mAsynchronous) {
        msg.setAsynchronous(true);
    }
 
    // 最终委托给 MessageQueue 的 enqueueMessage() 完成入队
    // MessageQueue 会根据 uptimeMillis 将消息插入到链表的正确位置
    return queue.enqueueMessage(msg, uptimeMillis);
}
 
// 【辅助】将 Runnable 包装为 Message 的私有工具方法
private static Message getPostMessage(Runnable r) {
    // 从 Message 复用池中获取一个空闲 Message（避免频繁 new）
    Message m = Message.obtain();
    // 将 Runnable 赋值给 Message 的 callback 字段
    // 后续 dispatchMessage 时会优先检查此字段
    m.callback = r;
    // 返回包装好的 Message
    return m;
}

// ---- Handler.java 分发链路核心源码 ----
 
// Looper.loop() 中取出消息后调用此方法
// 这个方法在 Looper 所在线程上执行（通常是主线程）
public void dispatchMessage(@NonNull Message msg) {
 
    // 【第一优先级】检查 Message 自身是否携带了 Runnable 回调
    // 当开发者使用 handler.post(Runnable) 时，Runnable 被存在 msg.callback
    if (msg.callback != null) {
        // 直接执行 Runnable.run()，不再走后续流程
        handleCallback(msg);
    } else {
        // 【第二优先级】检查 Handler 构造时是否传入了 Callback 接口
        // mCallback 是 Handler.Callback 类型，可在构造器中注入
        if (mCallback != null) {
            // 调用 Callback.handleMessage()
            // 如果返回 true —— 消息已被拦截处理，流程终止
            // 如果返回 false —— 消息穿透，继续走第三优先级
            if (mCallback.handleMessage(msg)) {
                return; // 被拦截，直接返回
            }
        }
        // 【第三优先级】调用 Handler 子类重写的 handleMessage()
        // Handler 基类中此方法为空实现，需要子类提供逻辑
        handleMessage(msg);
    }
}
 
// 第一优先级的实际执行方法：直接运行 Runnable
private static void handleCallback(Message message) {
    // 在当前线程（Looper 线程）执行 Runnable 的 run() 方法
    // 注意：这里是 run() 不是 start()，不会创建新线程
    message.callback.run();
}
 
// 第三优先级：空方法，等待子类重写
// 开发者通过 switch(msg.what) 区分消息类型并处理
public void handleMessage(@NonNull Message msg) {
    // 默认空实现
}
 
// Callback 接口定义 —— 第二优先级的抽象
public interface Callback {
    // 返回 true 表示消息已处理（拦截）
    // 返回 false 表示消息未处理（穿透到 handleMessage）
    boolean handleMessage(@NonNull Message msg);
}

// ---- 现代 Handler 推荐使用方式 (Kotlin) ----
 
// 【方式1】使用 Callback 接口（推荐：避免继承、避免内存泄漏）
// 显式传入 Looper.getMainLooper()，确保消息在主线程处理
val handler = Handler(Looper.getMainLooper()) { msg ->
    // Kotlin lambda 实现 Callback 接口
    // msg 就是从队列中取出的 Message
    when (msg.what) {
        // 根据 what 值分发不同消息类型
        MSG_UPDATE_UI -> {
            // 从 msg.obj 中取出数据（需要类型转换）
            val data = msg.obj as? String
            // 更新 UI（此时已经在主线程，安全操作 View）
            textView.text = data
            true // 返回 true 表示消息已处理，不再穿透
        }
        MSG_LOAD_COMPLETE -> {
            // 处理加载完成逻辑
            progressBar.visibility = View.GONE
            true // 已处理
        }
        else -> false // 未知消息类型，返回 false 表示未处理
    }
}
 
// 在工作线程中发送消息到主线程
thread {
    // 模拟耗时操作（网络请求、数据库查询等）
    val result = performHeavyWork()
 
    // 通过 Handler 将结果发送到主线程
    // obtain() 从复用池获取 Message，避免频繁创建对象
    val msg = Message.obtain().apply {
        what = MSG_UPDATE_UI   // 设置消息类型标识
        obj = result           // 设置载荷数据
    }
    // sendMessage 将消息投递到主线程的 MessageQueue
    handler.sendMessage(msg)
}
 
 
// 【方式2】使用 post(Runnable)（适合简单场景）
// 无需定义 what 常量，直接在 Runnable 中编写 UI 更新逻辑
val handler2 = Handler(Looper.getMainLooper())
 
thread {
    val result = performHeavyWork()
    // post 将 Runnable 包装为 Message 投递到主线程
    handler2.post {
        // 这个 lambda 会在主线程执行
        textView.text = result
    }
}
 
 
// 【方式3】子类重写（传统方式，注意内存泄漏风险）
// 使用 companion object 中的常量定义消息类型
companion object {
    const val MSG_UPDATE_UI = 1       // UI 更新消息
    const val MSG_LOAD_COMPLETE = 2   // 加载完成消息
}
 
// ★ 注意：如果必须使用子类方式，务必使用静态内部类 + WeakReference
// 详见下方"内存泄漏"章节

                    ┌─────────────────────────────────────────────┐
                    │            GC 引用链（泄漏路径）              │
                    ├─────────────────────────────────────────────┤
                    │                                             │
                    │  主线程 (GC Root)                            │
                    │      │                                      │
                    │      ▼                                      │
                    │  Looper (主线程 Looper，永不销毁)              │
                    │      │ 持有                                  │
                    │      ▼                                      │
                    │  MessageQueue (消息队列)                     │
                    │      │ 链表持有                               │
                    │      ▼                                      │
                    │  Message (延迟消息，still enqueued)           │
                    │      │ msg.target                            │
                    │      ▼                                      │
                    │  Handler (非静态内部类)                       │
                    │      │ 隐式持有外部类引用 (this$0)             │
                    │      ▼                                      │
                    │  Activity (已 onDestroy，但无法被 GC！)       │
                    │      │ 持有                                  │
                    │      ▼                                      │
                    │  View 树、Bitmap、Adapter 等大量资源           │
                    │                                             │
                    └─────────────────────────────────────────────┘

// ---- 反面示例：Handler 内存泄漏 ----
 
class LeakyActivity : AppCompatActivity() {
 
    // ★ 问题1：匿名内部类/lambda 隐式持有 LeakyActivity.this 引用
    // 在 Kotlin 中 object : Handler() 等价于 Java 的匿名内部类
    private val leakyHandler = object : Handler(Looper.getMainLooper()) {
        override fun handleMessage(msg: Message) {
            // 直接引用外部 Activity 的 View
            // 即使 Activity 已 onDestroy，这段代码仍可能执行
            textView.text = "Updated: ${msg.obj}"
        }
    }
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_leaky)
 
        // ★ 问题2：发送一条 10 分钟后才执行的延迟消息
        // 在这 10 分钟内，引用链一直存在：
        // MessageQueue → Message → leakyHandler → LeakyActivity
        val msg = Message.obtain().apply {
            what = 1
            obj = "some data"
        }
        leakyHandler.sendMessageDelayed(msg, 10 * 60 * 1000L)  // 10 分钟
 
        // ★ 问题3：周期性消息——泄漏永远不会结束
        // handleMessage 中再次 sendMessageDelayed，形成无限循环
        // leakyHandler.sendEmptyMessageDelayed(REFRESH_MSG, 5000)
    }
 
    // 用户按返回键，Activity 执行 onDestroy
    // 但由于引用链存在，Activity 的内存无法被回收
    // 如果反复进出这个 Activity，每次都泄漏一个实例
    // 内存占用持续增长，最终 OOM
}

// ---- 标准修复：静态内部类 + WeakReference + onDestroy 清理 ----
 
class SafeActivity : AppCompatActivity() {
 
    // ★ 修复1：使用伴生对象内的静态内部类
    // Kotlin 中 companion object 内的 class 或顶层 class 不持有外部类引用
    // 等价于 Java 中的 static inner class
    private class SafeHandler(
        activity: SafeActivity  // 构造时传入 Activity
    ) : Handler(Looper.getMainLooper()) {
 
        // ★ 修复2：使用 WeakReference 弱引用持有 Activity
        // 当 GC 发生时，如果 Activity 只被 WeakReference 引用
        // GC 可以正常回收 Activity，weakRef.get() 将返回 null
        private val weakActivity = WeakReference(activity)
 
        override fun handleMessage(msg: Message) {
            // ★ 修复3：每次处理消息前，先检查 Activity 是否还存活
            // 如果已被 GC 回收，get() 返回 null，直接跳过处理
            val activity = weakActivity.get() ?: return
 
            // 此时 activity 非 null，可以安全操作 UI
            when (msg.what) {
                MSG_UPDATE -> {
                    // 安全访问 Activity 的 View
                    activity.findViewById<TextView>(R.id.textView)?.text =
                        msg.obj as? String ?: ""
                }
            }
        }
    }
 
    // Handler 实例——SafeHandler 是静态类，不隐式持有 SafeActivity
    private val handler = SafeHandler(this)
 
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_safe)
 
        // 正常发送延迟消息
        handler.sendMessageDelayed(
            Message.obtain().apply {
                what = MSG_UPDATE
                obj = "Hello Safe Handler"
            },
            10 * 60 * 1000L  // 即使延迟 10 分钟也不会泄漏
        )
    }
 
    override fun onDestroy() {
        super.onDestroy()
 
        // ★ 修复4（关键保险）：移除该 Handler 发送的所有待处理消息和回调
        // 参数 null 表示移除所有——无论 what 值、无论 Runnable 还是 Message
        // 这直接将 Message 从 MessageQueue 链表中摘除
        // 引用链在此处彻底断开
        handler.removeCallbacksAndMessages(null)
    }
 
    companion object {
        const val MSG_UPDATE = 1  // 消息类型常量
    }
}

val handler = Handler(Looper.getMainLooper(), Handler.Callback { msg ->
    textView.text = "Callback"     // mCallback 处理
    false                          // 返回 false，消息穿透
})
 
handler.post {
    textView.text = "Runnable"     // msg.callback
}

// Message.java 核心静态字段（简化）
public final class Message implements Parcelable {
 
    // --- 复用池相关 ---
 
    // 池锁：所有对池的操作都需要在 synchronized(sPoolSync) 中执行
    private static final Object sPoolSync = new Object();
 
    // 池头指针：指向当前可用链表的第一个 Message
    // 如果为 null，说明池为空，需要 new
    private static Message sPool;
 
    // 当前池中缓存的 Message 数量
    private static int sPoolSize = 0;
 
    // 池容量上限，防止内存浪费（硬编码为 50）
    private static final int MAX_POOL_SIZE = 50;
 
    // 链表 next 指针：在池中时指向下一个可用 Message
    // 在 MessageQueue 中时用于消息链表的连接
    // 这个字段被"复用"了两种用途，非常精妙
    /*package*/ Message next;
 
    // 标记位：标识当前 Message 是否正在被使用
    // FLAG_IN_USE = 1 << 0
    /*package*/ int flags;
}

sPool（池头指针）
  │
  ▼
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ Message  │───▶│ Message  │───▶│ Message  │───▶│ Message  │───▶ null
│ (空闲)   │next│ (空闲)   │next│ (空闲)   │next│ (空闲)   │next
└──────────┘    └──────────┘    └──────────┘    └──────────┘
          sPoolSize = 4（当前池中有 4 个可复用对象）

// Message.obtain() —— 从复用池获取 Message
public static Message obtain() {
    // 对复用池加锁，保证多线程安全
    synchronized (sPoolSync) {
        // 如果池不为空（sPool 指向链表头节点）
        if (sPool != null) {
            // 取出链表头节点作为返回值
            Message m = sPool;
            // 将池头指针后移到下一个节点
            sPool = m.next;
            // 断开取出节点的 next 引用，避免持有整条链
            m.next = null;
            // 清除 FLAG_IN_USE 标记（此时即将被外部使用，flags 重置）
            m.flags = 0;
            // 池大小减一
            sPoolSize--;
            // 返回复用的 Message 对象
            return m;
        }
    }
    // 池为空时，兜底策略：创建新的 Message 对象
    return new Message();
}

// 带 Handler 的 obtain —— 同时绑定 target
public static Message obtain(Handler h) {
    // 先从池中取出空消息
    Message m = obtain();
    // 绑定目标 Handler，后续 Looper 分发时会交给它
    m.target = h;
    // 返回已绑定 target 的 Message
    return m;
}
 
// 带 Handler + what 的 obtain
public static Message obtain(Handler h, int what) {
    // 从池中取出空消息
    Message m = obtain();
    // 绑定目标 Handler
    m.target = h;
    // 设置消息类型标识
    m.what = what;
    return m;
}
 
// 带 Handler + Runnable 的 obtain
public static Message obtain(Handler h, Runnable callback) {
    // 从池中取出空消息
    Message m = obtain();
    // 绑定目标 Handler
    m.target = h;
    // 绑定回调任务，分发时优先执行 callback.run()
    m.callback = callback;
    return m;
}

// Message.recycle() —— 外部调用的回收入口
public void recycle() {
    // 检查是否正在被使用（是否已入队或正在分发）
    if (isInUse()) {
        // 如果消息还在使用中，抛出异常，防止重复回收导致数据错乱
        throw new IllegalStateException(
            "This message cannot be recycled because it is still in use.");
    }
    // 通过检查后，执行实际回收逻辑
    recycleUnchecked();
}
 
// Message.recycleUnchecked() —— 实际回收逻辑（框架内部也直接调用此方法）
void recycleUnchecked() {
    // 清空所有载荷字段，防止下次复用时残留旧数据
    flags = FLAG_IN_USE;   // 标记为"在池中"（防止被再次 recycle）
    what = 0;              // 重置消息类型
    arg1 = 0;              // 重置整型参数 1
    arg2 = 0;              // 重置整型参数 2
    obj = null;            // 释放对象引用，避免内存泄漏！
    replyTo = null;        // 释放跨进程回复的 Messenger 引用
    sendingUid = UID_NONE; // 重置发送方 UID
    workSourceUid = UID_NONE; // 重置工作源 UID
    when = 0;              // 重置定时时间戳
    target = null;         // 释放目标 Handler 引用！
    callback = null;       // 释放 Runnable 引用
    data = null;           // 释放 Bundle 引用
 
    // 加锁，将清空后的 Message 放回池头部
    synchronized (sPoolSync) {
        // 只有池未满时才放入，防止无限膨胀浪费内存
        if (sPoolSize < MAX_POOL_SIZE) {
            // 当前 Message 的 next 指向原来的池头
            next = sPool;
            // 池头指针更新为当前 Message（LIFO 入栈）
            sPool = this;
            // 池大小加一
            sPoolSize++;
        }
        // 如果池已满（sPoolSize >= 50），该 Message 不入池
        // 直接被 GC 回收，这是容量控制的安全阀
    }
}

// 定义消息类型常量（推荐使用 companion object 或顶层常量）
companion object {
    const val MSG_LOAD_DATA = 1      // 加载数据
    const val MSG_UPDATE_UI = 2      // 更新 UI
    const val MSG_SHOW_ERROR = 3     // 显示错误
}
 
// 在 handleMessage 中根据 what 分发
override fun handleMessage(msg: Message) {
    // 根据 msg.what 判断消息类型
    when (msg.what) {
        // 消息类型 1：执行数据加载逻辑
        MSG_LOAD_DATA -> loadDataFromNetwork()
        // 消息类型 2：使用 arg1 携带的进度值更新 UI
        MSG_UPDATE_UI -> updateProgress(msg.arg1)
        // 消息类型 3：使用 obj 携带的错误信息展示 Toast
        MSG_SHOW_ERROR -> showError(msg.obj as String)
    }
}

// 发送方：传递下载进度（当前值和总值）
val msg = Message.obtain(handler, MSG_DOWNLOAD_PROGRESS) // 从池获取并绑定 handler
msg.arg1 = currentBytes   // arg1 携带已下载字节数
msg.arg2 = totalBytes      // arg2 携带总字节数
handler.sendMessage(msg)   // 发送消息
 
// 接收方：读取进度
override fun handleMessage(msg: Message) {
    when (msg.what) {
        MSG_DOWNLOAD_PROGRESS -> {
            // 从 arg1、arg2 读取进度数据
            val current = msg.arg1  // 已下载
            val total = msg.arg2    // 总大小
            // 计算百分比并更新进度条
            progressBar.progress = (current * 100 / total)
        }
    }
}

// 发送方：传递一个数据对象
val user = User(name = "Alice", age = 30)  // 创建数据对象
val msg = Message.obtain(handler, MSG_USER_LOADED) // 从池获取
msg.obj = user    // 将 User 对象引用赋给 obj 字段
handler.sendMessage(msg) // 发送
 
// 接收方：取出对象并使用
override fun handleMessage(msg: Message) {
    when (msg.what) {
        MSG_USER_LOADED -> {
            // 从 obj 取出并强转为具体类型
            val user = msg.obj as User
            // 更新 UI 显示用户信息
            textName.text = user.name
        }
    }
}

// 发送方：通过 Bundle 传递多个键值对
val msg = Message.obtain(handler, MSG_COMPLEX_DATA) // 从池获取
val bundle = Bundle()                  // 创建 Bundle 容器
bundle.putString("title", "Hello")     // 放入字符串
bundle.putInt("count", 42)             // 放入整型
bundle.putParcelable("item", item)     // 放入 Parcelable 对象
msg.data = bundle                      // 将 Bundle 设置到 Message
handler.sendMessage(msg)               // 发送
 
// 接收方：从 Bundle 中按 key 提取数据
override fun handleMessage(msg: Message) {
    when (msg.what) {
        MSG_COMPLEX_DATA -> {
            // 从 msg.data 中按键取值
            val title = msg.data.getString("title")  // 取字符串
            val count = msg.data.getInt("count")      // 取整型
            // 使用数据更新 UI
        }
    }
}

// Message.java 中的 target 字段
public final class Message implements Parcelable {
    // 目标 Handler：决定这条消息最终由谁来处理
    // 当 Looper 从 MessageQueue 取出消息后，
    // 会调用 msg.target.dispatchMessage(msg) 将消息交给这个 Handler
    /*package*/ Handler target;
}

// Handler.java —— 消息入队的内部实现
private boolean enqueueMessage(
        MessageQueue queue,  // 目标消息队列
        Message msg,         // 待发送的消息
        long uptimeMillis    // 预定执行时间
) {
    // ★★★ 核心：将当前 Handler 实例绑定为消息的 target ★★★
    // 这一行建立了 Message → Handler 的关联
    msg.target = this;
 
    // 将 workSourceUid 传递给消息（用于电量统计等系统功能）
    msg.workSourceUid = ThreadLocalWorkSource.getUid();
 
    // 如果当前 Handler 设置了异步标志，则将消息也标记为异步
    // 异步消息不受同步屏障（SyncBarrier）阻拦
    if (mAsynchronous) {
        msg.setAsynchronous(true);
    }
 
    // 调用 MessageQueue 的入队方法，按时间戳插入链表
    return queue.enqueueMessage(msg, uptimeMillis);
}

// Looper.loop() 核心分发逻辑（简化）
public static void loop() {
    // 获取当前线程的 Looper
    final Looper me = myLooper();
    // 获取 Looper 关联的 MessageQueue
    final MessageQueue queue = me.mQueue;
 
    // 进入死循环，不断取消息并分发
    for (;;) {
        // 从消息队列取出下一条消息（可能阻塞）
        Message msg = queue.next();
        // 如果返回 null，说明 Looper 正在退出
        if (msg == null) {
            return;
        }
 
        // ★★★ 利用 target 字段将消息路由到目标 Handler ★★★
        // Looper 完全不关心消息内容，只负责"投递"
        msg.target.dispatchMessage(msg);
 
        // 分发完毕，回收 Message 到复用池
        msg.recycleUnchecked();
    }
}

GC Root (主线程栈 / MessageQueue 的静态引用)
   │
   ▼
MessageQueue  ─── 持有 ──→  Message (mMessages 链表)
                                │
                                │  msg.target
                                ▼
                            Handler (非静态内部类)
                                │
                                │  隐式持有外部类引用 (this$0)
                                ▼
                            Activity (已执行 onDestroy，本应被回收)

class MyActivity : AppCompatActivity() {
 
    // ★ 使用静态内部类 + 弱引用，切断 Handler → Activity 的强引用链
    private class SafeHandler(
        activity: MyActivity  // 构造时传入 Activity
    ) : Handler(Looper.getMainLooper()) {
 
        // 将 Activity 包装为弱引用，不阻止 GC 回收
        private val activityRef = WeakReference(activity)
 
        override fun handleMessage(msg: Message) {
            // 尝试获取 Activity，如果已被回收则返回 null
            val activity = activityRef.get() ?: return
            // Activity 仍然存活，安全执行 UI 操作
            when (msg.what) {
                MSG_UPDATE -> activity.updateUI()
            }
        }
    }
 
    // 持有 Handler 引用
    private val handler = SafeHandler(this)
 
    override fun onDestroy() {
        super.onDestroy()
        // ★ 移除所有未处理的消息和回调，彻底切断引用链
        // 传入 null token 表示移除该 Handler 的所有消息
        handler.removeCallbacksAndMessages(null)
    }
}

// Message.java 中的 callback 字段
public final class Message implements Parcelable {
    // Runnable 回调：如果不为 null，分发时直接执行它
    // 而不再走 Handler.handleMessage() 流程
    /*package*/ Runnable callback;
}

// Handler.post() 的实现 —— Runnable 被包装成 Message
public final boolean post(Runnable r) {
    // 调用 sendMessageDelayed，延迟 0 表示立即执行
    return sendMessageDelayed(getPostMessage(r), 0);
}
 
// 将 Runnable 包装成 Message 的关键方法
private static Message getPostMessage(Runnable r) {
    // 从复用池获取一个空 Message
    Message m = Message.obtain();
    // ★ 将 Runnable 赋值给 callback 字段 ★
    m.callback = r;
    // 返回携带了 Runnable 的 Message
    return m;
}

// Handler.dispatchMessage() —— 消息分发的三级优先级
public void dispatchMessage(Message msg) {
 
    // ★★ 第一优先级：Message 自带的 callback（即 post 的 Runnable）★★
    if (msg.callback != null) {
        // 如果消息自带 Runnable，直接执行它
        // 不再继续向下判断
        handleCallback(msg);
        return; // 注意这里直接 return 了
    }
 
    // ★★ 第二优先级：Handler 构造时传入的全局 Callback ★★
    if (mCallback != null) {
        // 调用全局 Callback 的 handleMessage
        // 如果它返回 true，表示消息已被消费，不再继续
        if (mCallback.handleMessage(msg)) {
            return;
        }
        // 返回 false 则"穿透"到第三优先级
    }
 
    // ★★ 第三优先级：Handler 子类重写的 handleMessage ★★
    handleMessage(msg);
}
 
// 执行 Message.callback（Runnable）的方法
private static void handleCallback(Message message) {
    // 直接调用 Runnable 的 run() 方法
    // 注意：是 run() 不是 start()，所以是在当前线程执行
    message.callback.run();
}

// 使用 Handler.Callback 代替继承
// 好处：减少类的数量，避免内部类引用问题
val handler = Handler(Looper.getMainLooper(), Handler.Callback { msg ->
    // 这里是第二优先级的回调
    when (msg.what) {
        MSG_REFRESH -> {
            // 处理刷新消息
            refreshData()
            true  // 返回 true：消息已消费，不再传递到 handleMessage
        }
        else -> false // 返回 false：当前 Callback 不处理，传递到 handleMessage
    }
})

MessageQueue → Message → callback (Lambda/匿名类)
                                    │
                                    │ 捕获外部 this
                                    ▼
                                Activity

// Message.java 中的异步标记相关
public final class Message implements Parcelable {
 
    // 标记位常量：异步消息标志
    // 值为 1 << 1 = 2
    /*package*/ static final int FLAG_ASYNCHRONOUS = 1 << 1;
 
    // 设置消息为异步
    public void setAsynchronous(boolean async) {
        if (async) {
            // 将 FLAG_ASYNCHRONOUS 位置 1
            flags |= FLAG_ASYNCHRONOUS;
        } else {
            // 将 FLAG_ASYNCHRONOUS 位清 0
            flags &= ~FLAG_ASYNCHRONOUS;
        }
    }
 
    // 查询当前消息是否为异步消息
    public boolean isAsynchronous() {
        // 检查 FLAG_ASYNCHRONOUS 位是否为 1
        return (flags & FLAG_ASYNCHRONOUS) != 0;
    }
}

// Handler 构造函数（含 async 参数）
public Handler(Looper looper, Callback callback, boolean async) {
    mLooper = looper;
    mQueue = looper.mQueue;
    mCallback = callback;
    // ★ 记录异步标志，后续所有消息都会继承此标志
    mAsynchronous = async;
}
 
// enqueueMessage 中自动标记
private boolean enqueueMessage(MessageQueue queue, Message msg, long uptimeMillis) {
    msg.target = this;
    // 如果 Handler 是异步的，则将消息也标记为异步
    if (mAsynchronous) {
        msg.setAsynchronous(true);
    }
    return queue.enqueueMessage(msg, uptimeMillis);
}

MessageQueue（无屏障时的时间序列）：
 
  队首                                               队尾
  ┌────────────┬────────────┬────────────┬────────────────────┐
  │ BizMsg #1  │ BizMsg #2  │ BizMsg #3  │ ★ Choreographer    │
  │ when=100   │ when=105   │ when=110   │   绘制回调          │
  │ 5ms 耗时   │ 3ms 耗时   │ 8ms 耗时   │   when=112          │
  └────────────┴────────────┴────────────┴────────────────────┘
               ──── time ──→
 
绘制消息实际执行时刻 = 100 + 5 + 3 + 8 = 116
绘制耗时假设 = 6ms → 完成时刻 = 122
下一个 VSync ≈ 112 + 16.6 = 128.6
122 < 128.6 → 本帧险过 ✅
 
但如果 BizMsg #3 耗时 12ms →
绘制完成 = 100 + 5 + 3 + 12 + 6 = 126
也许刚好能过 ... 再多一点就掉帧了 ❌

MessageQueue（有屏障时的实际行为）：
 
  队首                                                       队尾
  ┌──────────┬────────────┬────────────┬────────────┬──────────────────┐
  │ ⚡BARRIER │ BizMsg #1  │ BizMsg #2  │ BizMsg #3  │ ★ Choreographer  │
  │ target=  │ (同步,阻拦) │ (同步,阻拦) │ (同步,阻拦) │  (异步,穿透!)    │
  │ null     │            │            │            │                  │
  └──────────┴────────────┴────────────┴────────────┴──────────────────┘
 
next() 跳过所有同步消息 → 直接取出 Choreographer 绘制回调 → 立即执行 ★

// MessageQueue.postSyncBarrier() —— 插入同步屏障
// 返回值是屏障的 token，后续用于移除屏障
public int postSyncBarrier() {
    // 使用当前时间作为屏障的时间戳
    return postSyncBarrier(SystemClock.uptimeMillis());
}
 
private int postSyncBarrier(long when) {
    synchronized (this) {
        // 生成屏障的唯一 token（自增整数）
        // 每次调用 token 不同，用于精确移除对应屏障
        final int token = mNextBarrierToken++;
 
        // ★ 从复用池获取一个 Message 作为屏障
        // 注意：没有设置 target！target 保持为 null
        // 这就是屏障消息的唯一特征
        final Message msg = Message.obtain();
        msg.markInUse();      // 标记为使用中
        msg.when = when;      // 设置时间戳
        msg.arg1 = token;     // 将 token 存入 arg1 字段，用于后续匹配移除
 
        // ★ 将屏障消息按时间戳插入链表的正确位置 ★
        // 与普通 enqueueMessage 类似，但不需要设置 target
        Message prev = null;
        Message p = mMessages; // 链表头指针
 
        // 找到第一个 when > 屏障时间戳的消息，插入其前面
        if (when != 0) {
            while (p != null && p.when <= when) {
                prev = p;   // 记录前驱节点
                p = p.next; // 向后遍历
            }
        }
 
        // 将屏障消息插入链表
        if (prev != null) {
            // 插入到 prev 和 p 之间
            msg.next = p;
            prev.next = msg;
        } else {
            // 插入到链表头部
            msg.next = p;
            mMessages = msg;
        }
 
        // 返回 token，调用方需要保存它以便后续移除屏障
        return token;
    }
}

// MessageQueue.next() —— 核心取消息逻辑（含屏障处理，简化版）
Message next() {
    // native 层 epoll 的文件描述符指针
    final long ptr = mPtr;
    if (ptr == 0) {
        // MessageQueue 已销毁
        return null;
    }
 
    // 下次 epoll_wait 的超时时间，-1 表示无限等待
    int nextPollTimeoutMillis = 0;
 
    for (;;) {
        // 调用 native 层 epoll_wait，阻塞指定时间
        // 0 = 立即返回，-1 = 无限阻塞，>0 = 阻塞指定毫秒
        nativePollOnce(ptr, nextPollTimeoutMillis);
 
        synchronized (this) {
            final long now = SystemClock.uptimeMillis();
            Message prevMsg = null;
            Message msg = mMessages; // 从链表头开始
 
            // ★★★ 关键：检测同步屏障 ★★★
            if (msg != null && msg.target == null) {
                // 遇到了屏障消息！
                // 进入屏障模式：从屏障之后开始遍历，跳过所有同步消息
                // 只寻找下一条异步消息（isAsynchronous() == true）
                do {
                    prevMsg = msg;
                    msg = msg.next;
                    // 持续遍历，直到找到异步消息或链表末尾
                } while (msg != null && !msg.isAsynchronous());
 
                // 此时 msg 要么是第一条异步消息，要么是 null（没找到）
            }
 
            if (msg != null) {
                if (now < msg.when) {
                    // 消息还未到期，计算需要等待的时间
                    nextPollTimeoutMillis =
                        (int) Math.min(msg.when - now, Integer.MAX_VALUE);
                } else {
                    // 消息已到期，可以取出
                    mBlocked = false;
 
                    // 从链表中摘除该消息
                    if (prevMsg != null) {
                        // 消息在链表中间（屏障模式下的异步消息）
                        // 将前驱的 next 指向当前消息的 next
                        prevMsg.next = msg.next;
                    } else {
                        // 消息在链表头部（无屏障的普通模式）
                        mMessages = msg.next;
                    }
                    // 断开取出消息的 next 引用
                    msg.next = null;
                    // 标记为使用中
                    msg.markInUse();
                    // 返回该消息给 Looper
                    return msg;
                }
            } else {
                // 没有找到可用消息（或只有同步消息被屏障阻拦）
                // 设置无限等待，直到有新消息入队唤醒
                nextPollTimeoutMillis = -1;
            }
 
            // ... IdleHandler 处理逻辑（下一节详解）...
        }
    }
}

// MessageQueue.removeSyncBarrier() —— 移除同步屏障
public void removeSyncBarrier(int token) {
    synchronized (this) {
        Message prev = null;
        Message p = mMessages;
 
        // 在链表中查找 target == null 且 arg1 == token 的屏障消息
        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 (needWake && !mQuitting) {
            // 调用 native 层的 wake，向 eventfd 写入数据
            // 唤醒 epoll_wait 中阻塞的 next()
            nativeWake(mPtr);
        }
    }
}