Android常用C++模式

// 经典懒汉式 Singleton —— 非线程安全版本
class Singleton {
public:
    // 全局唯一访问点，返回单例指针
    static Singleton* getInstance() {
        // 首次调用时才创建实例（Lazy）
        if (sInstance == nullptr) {        // 检查是否已创建
            sInstance = new Singleton();   // 首次进入时分配堆内存并构造
        }
        return sInstance;                  // 返回唯一实例
    }
 
private:
    Singleton() {}                         // 构造函数私有化，禁止外部直接构造
    Singleton(const Singleton&) = delete;  // 禁止拷贝构造
    Singleton& operator=(const Singleton&) = delete; // 禁止赋值运算符
 
    static Singleton* sInstance;           // 静态成员：持有唯一实例的指针
};
 
// 静态成员需在 .cpp 中定义并初始化为 nullptr
Singleton* Singleton::sInstance = nullptr;

// 文件路径: system/core/include/utils/Singleton.h
// Android 的 Singleton 模板实现
 
#ifndef ANDROID_UTILS_SINGLETON_H
#define ANDROID_UTILS_SINGLETON_H
 
#include <stdint.h>          // 标准整型定义
#include <sys/types.h>       // 系统基础类型
#include <utils/Mutex.h>     // Android 自封装的互斥锁
 
namespace android {
 
// ---------------------------------------------------------------------------
// Singleton<T> 模板基类
// 使用 CRTP 模式：子类将自身作为模板参数传入
// 例如: class FooManager : public Singleton<FooManager> { ... };
// ---------------------------------------------------------------------------
template <typename TYPE>
class ANDROID_API Singleton
{
public:
    // 全局唯一访问点
    // 返回 TYPE 的引用（不是指针），更安全
    static TYPE& getInstance() {
        Mutex::Autolock _l(sLock);        // RAII 式加锁：构造时 lock()，析构时 unlock()
        TYPE* instance = sInstance;       // 读取当前静态实例指针
        if (instance == 0) {              // 如果实例尚未创建（首次调用）
            instance = new TYPE();        // 在堆上创建 TYPE 的实例
            sInstance = instance;         // 将实例指针保存到静态成员
        }
        return *instance;                // 解引用并返回实例的引用
    }
 
    // 判断单例是否已经被创建
    static bool hasInstance() {
        Mutex::Autolock _l(sLock);        // 同样需要加锁保护读取
        return sInstance != 0;            // 返回实例是否存在
    }
 
protected:
    ~Singleton() { }                      // 析构函数为 protected，防止外部 delete
    Singleton() { }                       // 构造函数为 protected，防止外部直接构造
 
private:
    // 禁止拷贝和赋值
    Singleton(const Singleton&);             // 拷贝构造声明但不实现 = 禁用
    Singleton& operator = (const Singleton&); // 赋值运算符声明但不实现 = 禁用
 
    static Mutex sLock;                   // 静态互斥锁：保护 sInstance 的并发访问
    static TYPE* sInstance;               // 静态实例指针：指向唯一的 TYPE 对象
};
 
// ---------------------------------------------------------------------------
 
// 宏：用于在 .cpp 文件中定义静态成员
// 因为 C++ 模板的静态成员必须在类外显式定义（One Definition Rule）
#define ANDROID_SINGLETON_STATIC_INSTANCE(TYPE)              \
    template<> ::android::Mutex                              \
        (::android::Singleton< TYPE >::sLock)(::android::Mutex::PRIVATE); \
    template<> TYPE* ::android::Singleton< TYPE >::sInstance(0); \
    template class ::android::Singleton< TYPE >;
 
// ---------------------------------------------------------------------------
}  // namespace android
 
#endif // ANDROID_UTILS_SINGLETON_H

// CRTP 的典型用法
// ProcessState 继承 Singleton，并把自己（ProcessState）作为模板参数 TYPE 传入
class ProcessState : public Singleton<ProcessState> {
    // 此时基类 Singleton<ProcessState> 中的 TYPE 就是 ProcessState
    // getInstance() 返回的就是 ProcessState& 类型
    friend class Singleton<ProcessState>;  // 允许基类访问 private 构造函数
private:
    ProcessState();  // 构造函数私有化
};

// Mutex::Autolock 简化实现原理
class Mutex::Autolock {
public:
    // 构造时自动加锁
    inline Autolock(Mutex& mutex) : mLock(mutex) {
        mLock.lock();    // 获取互斥锁
    }
    // 析构时自动解锁（离开作用域时触发）
    inline ~Autolock() {
        mLock.unlock();  // 释放互斥锁
    }
private:
    Mutex& mLock;        // 持有锁的引用
};

// 宏展开示例：假设 TYPE = ProcessState
// 原始宏
ANDROID_SINGLETON_STATIC_INSTANCE(ProcessState)
 
// 展开后等价于:
template<> ::android::Mutex
    (::android::Singleton<ProcessState>::sLock)(::android::Mutex::PRIVATE);
    // ↑ 显式特化 sLock，初始化为 PRIVATE 类型的 Mutex（进程内互斥）
 
template<> ProcessState*
    ::android::Singleton<ProcessState>::sInstance(0);
    // ↑ 显式特化 sInstance，初始化为 nullptr (0)
 
template class ::android::Singleton<ProcessState>;
    // ↑ 显式实例化整个 Singleton<ProcessState> 模板类
    //   确保编译器为该特化生成所有成员函数的代码

// ==================== DisplayManager.h ====================
#ifndef DISPLAY_MANAGER_H
#define DISPLAY_MANAGER_H
 
#include <utils/Singleton.h>   // 引入 Android Singleton 模板
#include <utils/String8.h>     // Android 字符串类（后续章节详解）
 
namespace android {
 
// DisplayManager 通过 CRTP 继承 Singleton<DisplayManager>
// 从而自动获得 getInstance() 静态方法
class DisplayManager : public Singleton<DisplayManager> {
    // 声明 Singleton<DisplayManager> 为友元类
    // 这一步至关重要：因为 getInstance() 内部需要调用 new DisplayManager()
    // 而 DisplayManager 的构造函数是 private 的
    // 如果不声明友元，基类无法访问子类的 private 构造函数
    friend class Singleton<DisplayManager>;
 
public:
    // 公开业务接口
    int getDisplayCount() const {
        return mDisplayCount;   // 返回当前显示器数量
    }
 
    void setDisplayCount(int count) {
        mDisplayCount = count;  // 设置显示器数量
    }
 
private:
    // 构造函数私有化 —— 只能通过 getInstance() 创建
    DisplayManager()
        : mDisplayCount(1) {    // 默认 1 个显示器
        // 初始化逻辑：打开显示设备、读取配置等
    }
 
    int mDisplayCount;          // 显示器数量
};
 
}  // namespace android
#endif
 
 
// ==================== DisplayManager.cpp ====================
#include "DisplayManager.h"
 
namespace android {
 
// 关键步骤：使用宏在 .cpp 中定义静态成员
// 不写这一行，链接时会报 undefined reference 错误
ANDROID_SINGLETON_STATIC_INSTANCE(DisplayManager)
 
}  // namespace android
 
 
// ==================== main.cpp ====================
#include "DisplayManager.h"
#include <stdio.h>
 
using namespace android;
 
int main() {
    // 通过 getInstance() 获取唯一实例的引用
    DisplayManager& dm = DisplayManager::getInstance();
 
    // 调用业务方法
    printf("Display count: %d\n", dm.getDisplayCount()); // 输出: 1
 
    dm.setDisplayCount(2);
 
    // 再次获取 —— 返回的是同一个实例
    DisplayManager& dm2 = DisplayManager::getInstance();
    printf("Display count: %d\n", dm2.getDisplayCount()); // 输出: 2
 
    // dm 和 dm2 指向同一个对象
    printf("Same instance: %s\n",
           (&dm == &dm2) ? "YES" : "NO"); // 输出: YES
 
    return 0;
}

instance = new TYPE();  // TYPE = DisplayManager

// 内存布局示意（DisplayManager 对象在堆上只有一份）
//
// Stack (Thread A)          Heap                        Static Data (.bss)
// ┌──────────────┐         ┌─────────────────────┐     ┌──────────────────────┐
// │ dm (引用)     │ ──────▶ │ DisplayManager 对象  │ ◀── │ sInstance (指针)      │
// └──────────────┘         │  mDisplayCount = 2   │     ├──────────────────────┤
//                          └─────────────────────┘     │ sLock (Mutex)        │
// Stack (Thread B)                 ▲                   └──────────────────────┘
// ┌──────────────┐                 │
// │ dm2 (引用)    │ ───────────────┘
// └──────────────┘

// frameworks/native/libs/binder/include/binder/ProcessState.h（简化）
class ProcessState : public virtual RefBase,   // 引用计数基类
                     public Singleton<ProcessState> // 单例能力
{
    friend class Singleton<ProcessState>;         // 允许基类构造
    // ... 其他成员 ...
 
private:
    ProcessState(const char* driver);             // 私有构造，参数为 Binder 驱动路径
};

// Meyer's Singleton —— C++11 起线程安全
class MeyerSingleton {
public:
    // C++11 保证：局部 static 变量只会被初始化一次
    // 即使多线程同时进入，编译器会自动插入同步机制
    static MeyerSingleton& getInstance() {
        static MeyerSingleton instance;   // 局部静态变量，首次执行时构造
        return instance;                  // 直接返回引用
    }
 
private:
    MeyerSingleton() {}                   // 私有构造
};

// ❌ 错误！不要这样做
DisplayManager* p = &DisplayManager::getInstance();
delete p;  // 悬空指针灾难！后续 getInstance() 仍返回已释放的内存

// ✅ 正确的使用模板
 
// 1. 头文件中：继承 + friend + 私有构造
class MyService : public Singleton<MyService> {
    friend class Singleton<MyService>;   // 必须
private:
    MyService();                         // 必须私有
public:
    void doWork();                       // 公开业务接口
};
 
// 2. 源文件中：宏定义静态成员
ANDROID_SINGLETON_STATIC_INSTANCE(MyService)  // 必须
 
// 3. 使用时：始终通过引用接收
MyService& svc = MyService::getInstance();  // 用引用，不用指针
svc.doWork();

// SharedBuffer 内存布局示意（简化）
// ┌─────────────────────┬──────────────────────────┐
// │   SharedBuffer头部    │     实际字符串数据          │
// │  (refCount + size)   │  "hello\0"               │
// │      8~16 bytes      │  由 data() 指针返回        │
// └─────────────────────┴──────────────────────────┘
//                        ↑
//                  mString 指向这里
//
// 关键操作：
//   acquire()  → refCount++  （引用+1）
//   release()  → refCount--  （引用-1，降到0时 free 整块内存）
//   bufferFromData(ptr) → 从数据区指针反推出 SharedBuffer 头部地址

// String8 拷贝构造 —— 引用计数方案
String8::String8(const String8& o)
    : mString(o.mString)                        // 直接复用同一块数据指针
{
    SharedBuffer::bufferFromData(mString)       // 从 mString 反推出 SharedBuffer 头部
        ->acquire();                            // 引用计数 +1
}
 
// String8 析构 —— 释放引用
String8::~String8()
{
    SharedBuffer::bufferFromData(mString)       // 找到 SharedBuffer 头部
        ->release();                            // 引用计数 -1，若归零则 free
}

// String16 拷贝赋值 —— 引用计数交换
void String16::setTo(const String16& other)
{
    SharedBuffer::bufferFromData(other.mString)
        ->acquire();                            // 先 acquire 新的
    SharedBuffer::bufferFromData(mString)
        ->release();                            // 再 release 旧的
    mString = other.mString;                    // 指针切换
}

#include <utils/String8.h>
using namespace android;
 
// 1. 默认构造：指向全局空串
String8 s1;                                     // ""
 
// 2. 从 C 字符串构造（UTF-8）
String8 s2("Hello Android");                    // 分配 SharedBuffer，拷贝数据
 
// 3. 从指定长度的 C 字符串构造
String8 s3("Hello Android", 5);                 // 只取前5字节 → "Hello"
 
// 4. 从 String16 构造（自动 UTF-16 → UTF-8 转换）
String16 wide(u"你好世界");                      // UTF-16 字符串
String8 s4(wide);                               // 内部调用 utf16_to_utf8
 
// 5. 拷贝构造（引用计数 +1，无数据复制）
String8 s5(s2);                                 // s5 与 s2 共享同一 SharedBuffer

// format —— 像 sprintf 一样构造字符串
String8 msg = String8::format(
    "Error code: %d, file: %s",                 // 格式模板
    errno,                                      // 替换 %d
    "/data/local/tmp/test.txt"                  // 替换 %s
);
// 结果类似: "Error code: 2, file: /data/local/tmp/test.txt"

String8 s("Hello");
 
// --- 访问 ---
const char* raw = s.string();                   // 获取底层 C 字符串指针（const char*）
size_t len = s.length();                        // 字符串字节长度（不含 \0）
size_t sz = s.size();                           // 同 length()
bool empty = s.isEmpty();                       // 是否为空串
 
// --- 修改 ---
s.setTo("World");                               // 重新设置内容
s.append(" C++");                               // 追加内容 → "World C++"
s += " Native";                                 // 运算符重载 → "World C++ Native"
 
// --- 比较 ---
String8 a("abc"), b("abd");
int cmp = a.compare(b);                         // < 0（字典序 a < b）
bool eq = (a == b);                             // false
bool lt = (a < b);                              // true
 
// --- Unicode 相关 ---
size_t utf32Len = s.getUtf32Length();           // UTF-32 码点数（真实字符数）

String8 path("/data/local/tmp/test.conf");
 
// --- 路径分解 ---
String8 dir  = path.getPathDir();               // "/data/local/tmp"
String8 leaf = path.getPathLeaf();              // "test.conf"
String8 ext  = path.getPathExtension();         // ".conf"
String8 base = path.getBasePath();              // "/data/local/tmp/test"
 
// --- 路径拼接 ---
String8 root("/sdcard");
root.appendPath("Download");                    // → "/sdcard/Download"
root.appendPath("file.zip");                    // → "/sdcard/Download/file.zip"
// appendPath 自动处理分隔符，不会出现 "/sdcard//Download"
 
// --- 不修改原始对象的拼接 ---
String8 newPath = root.appendPathCopy("subdir");// root 不变，返回新对象
 
// --- 路径遍历 ---
String8 full("/system/lib/hw/audio.primary.so");
String8 remains;
String8 first = full.walkPath(&remains);        // first = "system"
                                                // remains = "lib/hw/audio.primary.so"

#include <utils/String16.h>
using namespace android;
 
// 1. 从 C 字符串构造（UTF-8 → UTF-16 自动转换）
String16 s1("Hello");                           // 内部调用 allocFromUTF8
 
// 2. 从 String8 构造
String8 narrow("Android Framework");
String16 s2(narrow);                            // UTF-8 → UTF-16
 
// 3. 从 char16_t 数组构造
String16 s3(u"你好");                            // 直接 UTF-16 数据
 
// 4. 获取原始数据
const char16_t* raw = s1.string();              // 返回 char16_t* 指针
size_t len = s1.size();                         // UTF-16 编码单元数（非字节数）
 
// 5. 修改
s1.setTo(s2);                                   // 引用计数方式赋值
s1.append(s3);                                  // 追加
 
// 6. 比较
int cmp = s1.compare(s2);                       // 使用 strzcmp16 逐单元比较
bool eq = (s1 == s2);

// UTF-8 → UTF-16
String8 utf8Str("Hello 世界");                   // UTF-8 编码
String16 utf16Str(utf8Str);                      // 调用 allocFromUTF8 内部函数
                                                 // 遍历 UTF-8 字节序列 → 生成 char16_t 序列
 
// UTF-16 → UTF-8
String16 wide(u"Android 安卓");                   // UTF-16 编码
String8 narrow(wide);                             // 调用 utf16_to_utf8 内部函数
                                                 // 遍历 char16_t 序列 → 生成 UTF-8 字节序列

#include <binder/Parcel.h>
using namespace android;
 
// --- 发送端 (Client) ---
Parcel data;
String16 serviceName("com.example.MyService");   // Binder 服务名用 String16
data.writeString16(serviceName);                 // 序列化到 Parcel
 
// --- 接收端 (Server) ---
String16 received = data.readString16();         // 从 Parcel 反序列化
String8 narrow(received);                        // 如需 Native 侧使用，转为 UTF-8
ALOGD("Service: %s", narrow.string());           // 日志输出用 string() 获取 C 串

// StaticString16 通常用于全局常量定义
// 避免运行时的 SharedBuffer 分配和引用计数开销
static const StaticString16<20> kServiceName(u"android.os.IServiceManager");
 
// 可以安全地传递给接受 const String16& 的函数
// 因为 StaticString16 继承自 String16
void registerService(const String16& name);
registerService(kServiceName);                   // OK

#include <utils/String8.h>
#include <utils/String16.h>
#include <binder/Parcel.h>
#include <utils/Log.h>
 
using namespace android;
 
// 模拟一个 Native Service 的 onTransact 方法
status_t MyService::onTransact(
    uint32_t code,                               // Binder 事务码
    const Parcel& data,                          // 客户端发来的数据
    Parcel* reply,                               // 返回给客户端的数据
    uint32_t flags)                              // 标志位
{
    switch (code) {
    case LOAD_RESOURCE: {
        // 1. 从 Parcel 读取 UTF-16 字符串（Java 传来的）
        String16 resName16 = data.readString16(); // 读取资源名
 
        // 2. 转为 UTF-8 用于文件系统操作
        String8 resName8(resName16);              // UTF-16 → UTF-8
 
        // 3. 利用 String8 的路径操作构建完整路径
        String8 basePath("/data/app/resources");
        basePath.appendPath(resName8);            // 安全拼接路径
 
        // 4. 获取文件扩展名进行类型判断
        String8 ext = basePath.getPathExtension();// 如 ".png"
        ALOGD("Loading resource: %s (ext: %s)",
              basePath.string(),                  // 转 const char* 用于日志
              ext.string());
 
        // 5. 返回结果给 Java 层（用 String16）
        String16 result16(String8::format(
            "loaded:%s", basePath.string()));      // 格式化 + 转回 UTF-16
        reply->writeString16(result16);           // 写入 Parcel
 
        return NO_ERROR;
    }
    default:
        return BBinder::onTransact(code, data, reply, flags);
    }
}

// 引入 Android Vector 头文件（位于 libutils）
#include <utils/Vector.h>
 
// Android 所有基础工具类都在 android 命名空间下
using namespace android;
 
// 声明一个存储 int 的 Vector
Vector<int> intVec;
 
// 声明一个存储智能指针的 Vector（最常见用法之一）
Vector<sp<IBinder>> binderVec;

// ═══════════════════════════════════════════════════════
//  Vector 基础操作演示
// ═══════════════════════════════════════════════════════
 
#include <utils/Vector.h>          // 引入 Vector 头文件
#include <utils/Log.h>             // 引入 Android 日志
using namespace android;           // 使用 android 命名空间
 
void basicDemo() {
    // 1. 默认构造：创建一个空的 int 型 Vector
    Vector<int> vec;               // mCount=0, mCapacity=0
 
    // 2. 尾部追加元素 — 最常用的插入方式
    vec.add(10);                   // vec = [10],        返回插入位置的索引 0
    vec.add(20);                   // vec = [10, 20],    返回索引 1
    vec.add(30);                   // vec = [10, 20, 30]
 
    // 3. 在指定位置插入元素（index=1 的位置）
    vec.insertAt(15, 1);           // vec = [10, 15, 20, 30]
    // 参数说明：insertAt(value, index)
    // 底层会将 index 后的所有元素向后 memmove
 
    // 4. 获取元素数量（等价于 std::vector::size()）
    size_t count = vec.size();     // count = 4
 
    // 5. 读取元素 — 三种方式
    int a = vec[0];                // 方式一：operator[]，不做越界检查
    int b = vec.itemAt(1);         // 方式二：itemAt()，带越界断言（debug 模式）
    const int& c = vec.top();      // 方式三：获取最后一个元素的引用
 
    // 6. 可写引用 — editItemAt()
    vec.editItemAt(2) = 25;        // vec = [10, 15, 25, 30]
    // 注意：operator[] 返回的是 const 引用，修改必须用 editItemAt()
 
    // 7. 判空
    bool empty = vec.isEmpty();    // false
 
    // 8. 清空容器（释放所有元素，但不一定释放内存）
    vec.clear();                   // mCount=0，容量可能保留
}

void insertRemoveDemo() {
    Vector<int> vec;
    // 批量添加测试数据
    vec.add(100);                  // index 0
    vec.add(200);                  // index 1
    vec.add(300);                  // index 2
    vec.add(400);                  // index 3
    vec.add(500);                  // index 4
 
    // ── 插入操作 ──
 
    // insertAt(item, index, numItems)：在 index 处插入 numItems 个 item
    vec.insertAt(150, 1);          // 在 index=1 处插入 150
    // vec = [100, 150, 200, 300, 400, 500]
 
    // replaceAt(item, index)：替换指定位置的元素
    vec.replaceAt(250, 2);         // 把 index=2 的 200 替换为 250
    // vec = [100, 150, 250, 300, 400, 500]
 
    // ── 删除操作 ──
 
    // removeAt(index)：删除指定位置的元素
    vec.removeAt(0);               // 删除第一个元素 100
    // vec = [150, 250, 300, 400, 500]
    // 底层操作：将 index 之后的元素整体 memmove 向前
 
    // removeItemsAt(index, count)：从 index 开始删除 count 个元素
    vec.removeItemsAt(1, 2);       // 从 index=1 开始删除 2 个元素 (250, 300)
    // vec = [150, 400, 500]
 
    // pop()：删除并返回最后一个元素（等价于 back() + pop_back()）
    // 注意：Android Vector 没有名为 pop() 的函数
    // 但可以组合使用：
    int last = vec.top();          // 获取尾元素 500
    vec.removeAt(vec.size() - 1);  // 手动删除尾元素
    // vec = [150, 400]
}

void searchSortDemo() {
    Vector<int> vec;
    vec.add(50);                   // index 0
    vec.add(10);                   // index 1
    vec.add(40);                   // index 2
    vec.add(30);                   // index 3
    vec.add(20);                   // index 4
 
    // ── 线性查找 ──
    // indexOf(item)：从头查找第一个匹配元素，返回索引；找不到返回 -1
    ssize_t idx = vec.indexOf(30); // idx = 3（找到了，位于 index 3）
    ssize_t bad = vec.indexOf(99); // bad = -1（未找到，NAME_NOT_FOUND）
 
    // ── 排序 ──
    // sort()：使用默认比较（operator<）进行升序排序
    vec.sort();                    // vec = [10, 20, 30, 40, 50]
 
    // sort(compar)：使用自定义比较函数排序
    // 比较函数签名：int (*compar)(const T* lhs, const T* rhs)
    vec.sort([](const int* a, const int* b) -> int {
        return *b - *a;            // 降序排列
    });
    // vec = [50, 40, 30, 20, 10]
}

// 伪代码：VectorImpl::_grow() 核心逻辑简化版
void VectorImpl::_grow(size_t where, size_t amount) {
    // 计算新的需要的最小容量
    size_t newCount = mCount + amount;          // 新的元素总数
 
    if (newCount > mCapacity) {                 // 需要扩容
        // ── 增长策略核心 ──
        size_t newCapacity = mCapacity;         // 从当前容量开始
 
        if (mCapacity < 4) {
            newCapacity = 4;                    // 最小容量保证为 4
        } else if (mCapacity < 8) {
            newCapacity = 8;                    // 8 以下直接提到 8
        } else {
            // 关键：每次扩容增加 50%（即乘以 1.5）
            newCapacity = mCapacity + (mCapacity / 2);
        }
 
        // 确保新容量至少能容纳所有元素
        if (newCapacity < newCount) {
            newCapacity = newCount;
        }
 
        // 重新分配内存（realloc 或 malloc+memcpy）
        void* newStorage = realloc(mStorage, newCapacity * mItemSize);
        mStorage = newStorage;                  // 更新存储指针
        mCapacity = newCapacity;                // 更新容量
    }
 
    // 如果是中间插入，需要 memmove 腾出空间
    if (where < mCount) {
        memmove(                                // 将 where 后的元素向后移动
            (char*)mStorage + (where + amount) * mItemSize,
            (char*)mStorage + where * mItemSize,
            (mCount - where) * mItemSize
        );
    }
 
    mCount = newCount;                          // 更新元素数量
}

void preAllocDemo() {
    Vector<sp<Layer>> layers;
 
    // 假设我们知道大约有 64 个图层
    layers.setCapacity(64);        // 一次性分配 64 个元素的空间
    // 此时 mCapacity=64, mCount=0
    // 后续 add() 在 count < 64 时都不会触发 realloc
 
    for (int i = 0; i < 64; i++) {
        layers.add(new Layer());   // 每次 add 都是 O(1)，无扩容开销
    }
 
    // 如果确定后续不再添加元素，可以收缩内存
    // （减少 mCapacity 到 mCount，释放多余内存）
    // 注意：Android Vector 本身没有 shrink_to_fit()
    // 但可以通过 setCapacity(vec.size()) 近似实现
}

#include <utils/Vector.h>
#include <utils/RefBase.h>         // sp<T> 定义
#include <binder/IBinder.h>        // IBinder 定义
 
using namespace android;
 
// ── 模拟一个引用计数对象 ──
class MyService : public RefBase {
public:
    MyService(int id) : mId(id) {  // 构造函数，保存服务 ID
        ALOGD("MyService(%d) created", mId);
    }
 
    ~MyService() {                 // 析构函数
        ALOGD("MyService(%d) destroyed", mId);
    }
 
    int getId() const { return mId; }
 
private:
    int mId;                       // 服务标识
};
 
void smartPointerDemo() {
    Vector<sp<MyService>> services;   // 存储强引用的 Vector
 
    {
        sp<MyService> svc1 = new MyService(1);  // refCount=1
        sp<MyService> svc2 = new MyService(2);  // refCount=1
 
        services.add(svc1);        // Vector 内部拷贝 sp<T>，refCount 变为 2
        services.add(svc2);        // 同理，refCount=2
    }
    // svc1, svc2 离开作用域，refCount 各减 1，变为 1
    // 对象仍然存活，因为 Vector 中还持有一份强引用
 
    // 访问 Vector 中的智能指针
    sp<MyService> ref = services[0];   // refCount 短暂变为 2
    ALOGD("Service ID = %d", ref->getId());
 
    // 从 Vector 中移除
    services.removeAt(0);          // Vector 释放 sp<T> 副本，refCount 减 1
    // 如果 ref 是最后的持有者（refCount=1），离开作用域后对象被析构
 
    services.clear();              // 清空，所有 sp<T> 被析构
    // MyService(2) 的 refCount 归零，对象被 delete
}

#include <utils/SortedVector.h>
using namespace android;
 
void sortedDemo() {
    SortedVector<int> sv;
 
    // add() 会自动插入到正确的有序位置
    sv.add(30);                    // sv = [30]
    sv.add(10);                    // sv = [10, 30]  — 10 插入到 30 之前
    sv.add(20);                    // sv = [10, 20, 30]
    sv.add(50);                    // sv = [10, 20, 30, 50]
    sv.add(40);                    // sv = [10, 20, 30, 40, 50]
 
    // indexOf() 在 SortedVector 中使用二分查找，O(log n)
    ssize_t idx = sv.indexOf(30);  // idx = 2，O(log n) 高效查找
 
    // merge()：合并另一个 Vector 的所有元素（归并）
    SortedVector<int> sv2;
    sv2.add(25);
    sv2.add(35);
    sv.merge(sv2);                 // sv = [10, 20, 25, 30, 35, 40, 50]
}

// 简化自 AOSP SurfaceFlinger 代码
class SurfaceFlinger : public BnSurfaceComposer {
private:
    // 使用 Vector 存储所有 Display 上的可见图层
    Vector<sp<Layer>> mVisibleLayers;      // 可见图层列表
 
    // 使用 SortedVector 存储按 Z 轴排序的图层
    SortedVector<sp<Layer>> mLayersByZ;    // Z 轴有序图层
 
public:
    // 每帧合成时调用
    void rebuildLayerStacks() {
        mVisibleLayers.clear();            // 清空上一帧的可见图层
 
        // 预分配容量，避免帧内 realloc
        mVisibleLayers.setCapacity(mLayersByZ.size());
 
        // 遍历所有图层，筛选可见的
        for (size_t i = 0; i < mLayersByZ.size(); i++) {
            const sp<Layer>& layer = mLayersByZ[i];  // 只读访问
            if (layer->isVisible()) {      // 判断是否可见
                mVisibleLayers.add(layer); // 加入可见列表
            }
        }
        // 至此 mVisibleLayers 包含本帧所有需要合成的图层
    }
 
    // 添加新图层
    status_t addLayer(const sp<Layer>& layer) {
        // SortedVector::add() 自动按 Layer 的 Z 值排序
        mLayersByZ.add(layer);
        return NO_ERROR;
    }
 
    // 移除图层
    status_t removeLayer(const sp<Layer>& layer) {
        ssize_t idx = mLayersByZ.indexOf(layer);  // O(log n) 查找
        if (idx >= 0) {
            mLayersByZ.removeAt(idx);      // 移除，sp<T> 自动管理引用计数
            return NO_ERROR;
        }
        return NAME_NOT_FOUND;             // Android 错误码：未找到
    }
};

Mutex mLock;                       // Android Mutex（基于 pthread_mutex）
Vector<int> mSharedVec;            // 共享容器
 
void threadSafeAdd(int value) {
    Mutex::Autolock lock(mLock);   // RAII 自动加锁/解锁
    mSharedVec.add(value);         // 在锁保护下操作
}

// 每帧调用一次
void onFrame() {
    Vector<sp<RenderNode>> nodes;     // 每帧创建新 Vector
    collectVisibleNodes(nodes);        // 填充约 200 个节点
    renderAll(nodes);                  // 渲染
}   // 帧结束，nodes 析构

// 定义在 KeyedVector.h 中
// 这是 KeyedVector 存储的最小单元：键值对
template <typename KEY, typename VALUE>
struct key_value_pair_t {
    typedef KEY    key_t;       // 键的类型别名
    typedef VALUE  value_t;     // 值的类型别名
 
    KEY   key;                  // 存储键
    VALUE value;                // 存储值
 
    // 默认构造函数
    key_value_pair_t() {}
 
    // 带参构造：用给定的 key 和 value 初始化
    key_value_pair_t(const KEY& k, const VALUE& v)
        : key(k), value(v) {}
 
    // 定义"小于"操作符 —— 这是排序的核心！
    // 只按 key 比较，value 不参与排序逻辑
    inline bool operator<(const key_value_pair_t& o) const {
        return strictly_order_type(key, o.key);  // 调用 Android 的类型安全比较函数
    }
 
    // "大于"操作符，同样只看 key
    inline bool operator>(const key_value_pair_t& o) const {
        return strictly_order_type(o.key, key);
    }
 
    // 默认赋值拷贝操作符，不相关代码
    inline const KEY& getKey() const { return key; }   // getter
    inline const VALUE& getValue() const { return value; } // getter
};

// KeyedVector 类模板
// KEY 必须支持 < 比较操作
// VALUE 可以是任意可拷贝类型
template <typename KEY, typename VALUE>
class KeyedVector {
public:
    typedef KEY    key_type;                          // 键类型
    typedef VALUE  mapped_type;                       // 值类型
    typedef key_value_pair_t<KEY, VALUE> value_type;  // 内部存储的 pair 类型
 
    // 构造与析构
    inline                  KeyedVector() {}
                            // 默认析构由编译器生成即可
 
    // =================== 容量相关 ===================
    inline  size_t          size() const { return mVector.size(); }       // 返回元素个数
    inline  bool            isEmpty() const { return mVector.isEmpty(); } // 判空
    inline  size_t          capacity() const { return mVector.capacity(); } // 底层数组容量
 
    // =================== 查找操作 ===================
    // 根据 key 查找，返回索引；未找到返回负值
    ssize_t                 indexOfKey(const KEY& key) const;
 
    // 根据 key 取值（const 版本）；key 不存在时行为未定义！
    const VALUE&            valueFor(const KEY& key) const;
 
    // 根据索引取值 —— 注意是索引不是 key
    const VALUE&            valueAt(size_t index) const;
    const KEY&              keyAt(size_t index) const;
 
    // =================== 修改操作 ===================
    // 添加键值对（key 不能已存在，否则返回错误）
    status_t                add(const KEY& key, const VALUE& value);
 
    // 替换键值对（key 已存在则更新 value，不存在则插入）
    status_t                replaceValueFor(const KEY& key, const VALUE& value);
 
    // 根据 key 删除
    status_t                removeItem(const KEY& key);
 
    // 根据索引删除
    status_t                removeItemsAt(size_t index, size_t count = 1);
 
    // 清空
    inline  void            clear() { mVector.clear(); }
 
private:
    SortedVector<key_value_pair_t<KEY, VALUE>> mVector;  // 核心：底层就是一个排序数组！
};

SortedVector<key_value_pair_t<KEY, VALUE>> mVector;  // 唯一的成员变量

// indexOfKey：根据 key 查找对应的索引位置
template <typename KEY, typename VALUE>
ssize_t KeyedVector<KEY, VALUE>::indexOfKey(const KEY& key) const {
    // 构造一个临时的 key_value_pair_t，只填充 key 部分
    // value 部分使用默认构造（因为排序只看 key，value 无所谓）
    key_value_pair_t<KEY, VALUE> pair(key, VALUE());
 
    // 委托给 SortedVector 的 indexOf
    // SortedVector::indexOf 内部执行二分搜索
    return mVector.indexOf(pair);
}
 
// valueFor：根据 key 直接取值
template <typename KEY, typename VALUE>
const VALUE& KeyedVector<KEY, VALUE>::valueFor(const KEY& key) const {
    // 先用 indexOfKey 找到索引
    ssize_t i = this->indexOfKey(key);
 
    // 断言：key 必须存在！否则直接 crash
    LOG_ALWAYS_FATAL_IF(i < 0, "%s: key not found", __func__);
 
    // 用索引访问底层数组，取出 pair 的 value 部分
    return mVector.itemAt(i).value;
}

// add：添加新的键值对
template <typename KEY, typename VALUE>
status_t KeyedVector<KEY, VALUE>::add(const KEY& key, const VALUE& value) {
    // 将 key 和 value 打包成 pair
    key_value_pair_t<KEY, VALUE> pair(key, value);
 
    // 委托给 SortedVector::add
    // SortedVector::add 会：
    //   1. 二分搜索找到插入位置（保持有序）
    //   2. 如果 key 已存在，返回 BAD_VALUE
    //   3. 如果 key 不存在，在正确位置插入（可能触发 memmove）
    ssize_t result = mVector.add(pair);
 
    // result >= 0 表示成功插入，值为插入后的索引
    // result < 0 表示失败（如 key 已存在）
    return (result >= 0) ? NO_ERROR : result;
}
 
// replaceValueFor：插入或更新
template <typename KEY, typename VALUE>
status_t KeyedVector<KEY, VALUE>::replaceValueFor(const KEY& key, const VALUE& value) {
    // 先查找 key 是否已存在
    ssize_t i = this->indexOfKey(key);
 
    if (i >= 0) {
        // key 已存在 —— 原地更新 value（不改变排序）
        // 注意：这里需要获取可变引用，所以用 editValueAt
        mVector.editItemAt(i).value = value;
        return NO_ERROR;
    } else {
        // key 不存在 —— 作为新元素插入
        return this->add(key, value);
    }
}

#include <utils/KeyedVector.h>   // Android 头文件
#include <utils/String8.h>       // Android 字符串
 
using namespace android;
 
void basicUsage() {
    // =================== 创建 ===================
    // 创建一个 int -> String8 的映射表
    KeyedVector<int, String8> configMap;
 
    // =================== 插入 ===================
    // add(): 添加新键值对，key 不能重复
    configMap.add(1001, String8("screen_brightness"));   // 添加 key=1001
    configMap.add(1002, String8("volume_level"));        // 添加 key=1002
    configMap.add(1003, String8("wifi_enabled"));        // 添加 key=1003
 
    // 尝试添加重复 key —— 会失败！
    status_t err = configMap.add(1001, String8("duplicate"));
    // err < 0，表示添加失败（key 已存在）
 
    // replaceValueFor(): 存在则更新，不存在则插入
    configMap.replaceValueFor(1001, String8("screen_brightness_v2"));  // 更新
    configMap.replaceValueFor(1004, String8("bluetooth_enabled"));     // 新插入
 
    // =================== 查找 ===================
    // indexOfKey(): 查找 key 对应的索引
    ssize_t idx = configMap.indexOfKey(1002);  // 返回 >= 0 的有效索引
    if (idx >= 0) {
        // valueAt(): 根据索引取值
        const String8& val = configMap.valueAt(idx);   // "volume_level"
        // keyAt(): 根据索引取 key
        const int& k = configMap.keyAt(idx);           // 1002
    }
 
    // valueFor(): 直接根据 key 取值（key 必须存在！）
    const String8& brightness = configMap.valueFor(1001);  // "screen_brightness_v2"
 
    // =================== 遍历 ===================
    // 遍历是按 key 升序的（因为底层是排序数组）
    for (size_t i = 0; i < configMap.size(); i++) {
        int key = configMap.keyAt(i);           // 依次为 1001, 1002, 1003, 1004
        const String8& value = configMap.valueAt(i);  // 对应的 value
        ALOGD("Config[%d] = %s", key, value.c_str());
    }
 
    // =================== 删除 ===================
    // removeItem(): 根据 key 删除
    configMap.removeItem(1003);   // 删除 key=1003 的条目
 
    // removeItemsAt(): 根据索引删除（可批量）
    configMap.removeItemsAt(0);   // 删除第 0 个元素（即 key 最小的那个）
 
    // clear(): 清空所有元素
    configMap.clear();
}

// frameworks/av/services/audioflinger/AudioFlinger.h
// 音频服务用 KeyedVector 管理所有的音频会话（AudioSession）
// key = audio_session_t (会话ID)
// value = AudioSessionRef (会话引用对象)
 
// 根据会话 ID 快速查找对应的会话对象
KeyedVector<audio_session_t, sp<AudioSessionRef>> mAudioSessions;
 
// 新建会话时
mAudioSessions.add(sessionId, new AudioSessionRef(sessionId, pid));
 
// 查找会话
ssize_t idx = mAudioSessions.indexOfKey(sessionId);
if (idx >= 0) {
    sp<AudioSessionRef> session = mAudioSessions.valueAt(idx);
    // 使用 session...
}

// frameworks/native/services/surfaceflinger/SurfaceFlinger.h
// 显示服务用 KeyedVector 维护 Display 到 Device 的映射
// 典型的 "少量元素 + 频繁查找" 场景
// （手机通常只有 1-3 个显示设备：主屏、副屏、虚拟屏）
 
KeyedVector<wp<IBinder>, sp<DisplayDevice>> mDisplays;
 
// 根据 Display token 快速定位 DisplayDevice
sp<DisplayDevice> device = mDisplays.valueFor(displayToken);

// frameworks/native/services/sensorservice/SensorService.h
// 传感器服务管理连接的客户端
KeyedVector<int, sp<SensorEventConnection>> mActiveConnections;
 
// 遍历所有活跃连接，推送传感器数据
for (size_t i = 0; i < mActiveConnections.size(); i++) {
    sp<SensorEventConnection> conn = mActiveConnections.valueAt(i);
    conn->sendEvents(events, count);  // 向每个客户端推送事件
}

// DefaultKeyedVector 在构造时指定一个"默认值"
// 当 valueFor() 找不到 key 时，返回默认值而不是 crash
template <typename KEY, typename VALUE>
class DefaultKeyedVector : public KeyedVector<KEY, VALUE> {
public:
    // 构造函数接受一个默认值
    inline DefaultKeyedVector(const VALUE& defValue = VALUE())
        : mDefault(defValue) {}                   // 保存默认值
 
    // 重写 valueFor —— 找不到时返回 mDefault
    const VALUE& valueFor(const KEY& key) const {
        ssize_t i = this->indexOfKey(key);        // 查找 key
        if (i >= 0) {
            return KeyedVector<KEY, VALUE>::valueAt(i);  // 找到了，返回真实值
        } else {
            return mDefault;                       // 没找到，返回默认值
        }
    }
 
private:
    VALUE mDefault;   // 存储默认返回值
};

void defaultKeyedVectorDemo() {
    // 创建一个默认值为 "UNKNOWN" 的映射表
    DefaultKeyedVector<int, String8> errorCodeMap(String8("UNKNOWN_ERROR"));
 
    // 添加已知的错误码映射
    errorCodeMap.add(200, String8("OK"));                    // HTTP 200
    errorCodeMap.add(404, String8("NOT_FOUND"));             // HTTP 404
    errorCodeMap.add(500, String8("INTERNAL_SERVER_ERROR")); // HTTP 500
 
    // 查找已知 key —— 返回真实值
    String8 msg1 = errorCodeMap.valueFor(200);    // "OK"
    String8 msg2 = errorCodeMap.valueFor(404);    // "NOT_FOUND"
 
    // 查找未知 key —— 安全返回默认值，不会 crash！
    String8 msg3 = errorCodeMap.valueFor(999);    // "UNKNOWN_ERROR"
    String8 msg4 = errorCodeMap.valueFor(418);    // "UNKNOWN_ERROR" (I'm a teapot 😄)
}

// ❌ 错误示范：遍历中删除会导致索引混乱
for (size_t i = 0; i < map.size(); i++) {
    if (shouldRemove(map.valueAt(i))) {
        map.removeItemsAt(i);   // 删除后 i+1 变成了 i，但循环会 i++，跳过一个元素！
    }
}
 
// ✅ 正确做法：从后向前遍历删除
for (ssize_t i = map.size() - 1; i >= 0; i--) {
    if (shouldRemove(map.valueAt(i))) {
        map.removeItemsAt(i);   // 删除尾部元素不影响前面的索引
    }
}

#include <utils/Mutex.h>   // Android 互斥锁
 
class MyService {
    mutable Mutex mLock;                              // 互斥锁
    KeyedVector<int, String8> mRegistry;              // 受保护的数据
 
public:
    // 写操作：获取排他锁
    status_t registerItem(int id, const String8& name) {
        Mutex::Autolock _l(mLock);                    // RAII 方式自动加锁/解锁
        return mRegistry.add(id, name);               // 安全写入
    }
 
    // 读操作：同样需要锁（防止读到写了一半的数据）
    String8 lookupItem(int id) const {
        Mutex::Autolock _l(mLock);                    // 加锁
        ssize_t idx = mRegistry.indexOfKey(id);       // 安全读取
        if (idx >= 0) {
            return mRegistry.valueAt(idx);            // 返回副本（锁释放后引用失效）
        }
        return String8();                             // key 不存在返回空串
    }
};

// KeyedVector<int, String8> 内存布局示意
//
// KeyedVector 对象本身
// +-----------------------------------------------+
// | mVector (SortedVector)                         |
// |   +-------------------------------------------+
// |   | mStorage ---> [ 指向堆上连续数组的指针 ]    |
// |   | mCount = 3    (当前元素数)                  |
// |   | mCapacity = 4 (预分配容量)                  |
// |   +-------------------------------------------+
// +-----------------------------------------------+
//
// 堆上的连续数组 (mStorage 指向的内存)
// +------------------+------------------+------------------+------------------+
// | pair[0]          | pair[1]          | pair[2]          | (空闲slot)       |
// | key=100          | key=200          | key=300          |                  |
// | value="wifi"     | value="bt"       | value="nfc"      |                  |
// +------------------+------------------+------------------+------------------+
// ^                                                        ^
// |<------- 已用空间 (size=3) -------->|<-- 预留 (cap=4) -->|
//
// 注意：元素严格按 key 升序排列 (100 < 200 < 300)
// 如果插入 key=150，需要将 pair[1] 和 pair[2] 整体后移一位

KeyedVector<int, String8> kvMap;
kvMap.add(1, String8("alpha"));
kvMap.add(2, String8("beta"));
kvMap.add(3, String8("gamma"));
 
const String8& ref = kvMap.valueFor(2);    // 获取引用
kvMap.add(4, String8("delta"));            // 插入新元素
ALOGD("Value: %s", ref.c_str());          // 使用之前的引用

// === Message：极简的消息载体 ===
struct Message {
    int what;  // 消息标识符，用于区分消息类型（类似 Java 层 Message.what）
    Message() : what(0) {} // 默认构造，what 初始化为 0
    Message(int w) : what(w) {} // 带参构造，指定消息类型
};
 
// === MessageHandler：消息处理的抽象基类 ===
class MessageHandler : public virtual RefBase {
public:
    // 纯虚函数，子类必须实现此方法来处理消息
    virtual void handleMessage(const Message& message) = 0;
 
protected:
    virtual ~MessageHandler(); // 析构函数为 protected，配合 RefBase 引用计数
};
 
// === LooperCallback：fd 事件回调的抽象基类 ===
class LooperCallback : public virtual RefBase {
public:
    // fd 事件就绪时被调用
    // fd: 触发事件的文件描述符
    // events: 就绪的事件掩码 (EVENT_INPUT / EVENT_OUTPUT / EVENT_ERROR 等)
    // data: addFd() 时传入的用户自定义数据
    // 返回值：1 表示继续监听，0 表示移除该 fd
    virtual int handleEvent(int fd, int events, void* data) = 0;
 
protected:
    virtual ~LooperCallback();
};

// --- Looper 的创建与线程绑定 ---
 
// 构造函数：创建 epoll 实例和唤醒用的 eventfd
Looper::Looper(bool allowNonCallbacks)
    : mAllowNonCallbacks(allowNonCallbacks) // 是否允许无回调的 fd 监听
{
    // 创建 eventfd，用于线程间唤醒
    // EFD_NONBLOCK: 非阻塞模式
    // EFD_CLOEXEC: exec 时自动关闭
    mWakeEventFd.reset(eventfd(0, EFD_NONBLOCK | EFD_CLOEXEC));
 
    // 创建 epoll 实例，EPOLL_CLOEXEC 同上
    mEpollFd.reset(epoll_create1(EPOLL_CLOEXEC));
 
    // 准备 epoll_event 结构体
    struct epoll_event eventItem;
    memset(&eventItem, 0, sizeof(epoll_event)); // 清零，避免未初始化字段
    eventItem.events = EPOLLIN;                  // 监听"可读"事件
    eventItem.data.fd = mWakeEventFd.get();      // 关联到 wake 用的 eventfd
 
    // 把 wakeEventFd 注册到 epoll，这样 wake() 写入时能唤醒 epoll_wait
    epoll_ctl(mEpollFd.get(), EPOLL_CTL_ADD, mWakeEventFd.get(), &eventItem);
}
 
// 静态方法：为当前线程准备一个 Looper（类似 Java Looper.prepare()）
void Looper::prepare(bool allowNonCallbacks) {
    // 每个线程通过 TLS 存储自己的 Looper 指针
    sp<Looper> looper = Looper::getForThread(); // 先检查当前线程是否已有 Looper
    if (looper == nullptr) {
        // 若没有，则创建新的 Looper 并绑定到当前线程
        looper = sp<Looper>::make(allowNonCallbacks);
        Looper::setForThread(looper);
    }
}
 
// 静态方法：获取当前线程绑定的 Looper（类似 Java Looper.myLooper()）
sp<Looper> Looper::getForThread() {
    // 从 TLS 中取出当前线程的 Looper
    // 内部使用 pthread_getspecific() 实现
    ...
}

// --- pollOnce() 的核心实现（简化版）---
 
// timeoutMillis: 超时时间，-1 表示永久等待，0 表示立即返回
int Looper::pollOnce(int timeoutMillis,
                     int* outFd,         // [输出] 就绪的 fd
                     int* outEvents,     // [输出] 就绪的事件类型
                     void** outData)     // [输出] 用户自定义数据
{
    int result = 0;
    for (;;) { // 无限循环，直到有事件需要返回
        // 1. 先检查并分发已就绪的"响应"（上一次 pollInner 产生的结果）
        while (mResponseIndex < mResponses.size()) {
            const Response& response = mResponses.itemAt(mResponseIndex++);
            int ident = response.request.ident; // 获取 fd 的标识符
            if (ident >= 0) {
                // ident >= 0 表示这是由 addFd 指定了 ident 的 fd（无回调模式）
                // 将结果通过输出参数返回给调用者
                if (outFd != nullptr) *outFd = response.request.fd;
                if (outEvents != nullptr) *outEvents = response.events;
                if (outData != nullptr) *outData = response.request.data;
                return ident; // 返回 ident，调用者根据 ident 判断事件来源
            }
        }
 
        // 2. 如果上一轮 pollInner 已标记需要返回某个 result，则立即返回
        if (result != 0) {
            if (outFd != nullptr) *outFd = 0;
            if (outEvents != nullptr) *outEvents = 0;
            if (outData != nullptr) *outData = nullptr;
            return result;
        }
 
        // 3. 进入内部轮询——这里才是真正可能阻塞的地方
        result = pollInner(timeoutMillis);
    }
}

// --- pollInner() 核心实现（简化版）---
 
int Looper::pollInner(int timeoutMillis) {
    // ========== 第一阶段：计算超时时间 ==========
    // 如果消息队列中有定时消息即将到期，需要调整超时时间
    if (mNextMessageUptime != LLONG_MAX) {
        nsecs_t now = systemTime(SYSTEM_TIME_MONOTONIC); // 获取当前单调时钟
        int messageTimeoutMillis = toMillisecondTimeoutDelay(now, mNextMessageUptime);
        if (messageTimeoutMillis >= 0
            && (timeoutMillis < 0 || messageTimeoutMillis < timeoutMillis)) {
            timeoutMillis = messageTimeoutMillis; // 取较小的超时值，确保消息能及时被处理
        }
    }
 
    int result = POLL_WAKE; // 默认返回 POLL_WAKE
 
    // 清空上一轮的响应列表
    mResponses.clear();
    mResponseIndex = 0;
 
    // ========== 第二阶段：epoll_wait 阻塞等待 ==========
    struct epoll_event eventItems[EPOLL_MAX_EVENTS]; // 就绪事件数组（栈上分配，高效）
    // 这里是整个消息系统的核心阻塞点！
    // 线程会在此处休眠，直到：
    //   1) 有 fd 事件就绪（包括 wake 事件）
    //   2) 超时时间到达
    int eventCount = epoll_wait(
        mEpollFd.get(),       // epoll 实例
        eventItems,           // 输出：就绪事件数组
        EPOLL_MAX_EVENTS,     // 最大返回事件数（通常为 16）
        timeoutMillis         // 超时毫秒数，-1 = 永久等待
    );
 
    // ========== 第三阶段：处理 epoll 返回的事件 ==========
    if (eventCount < 0) {
        // epoll_wait 出错（通常是被信号中断 EINTR）
        result = POLL_ERROR;
    } else if (eventCount == 0) {
        // 超时，没有任何事件就绪
        result = POLL_TIMEOUT;
    } else {
        // 有事件就绪，逐个处理
        for (int i = 0; i < eventCount; i++) {
            int fd = eventItems[i].data.fd;       // 就绪的 fd
            uint32_t epollEvents = eventItems[i].events; // 就绪的事件掩码
 
            if (fd == mWakeEventFd.get()) {
                // 这是 wake 事件——有人调用了 wake() 唤醒我们
                if (epollEvents & EPOLLIN) {
                    awoken(); // 读取 eventfd 中的数据（清除就绪状态）
                }
            } else {
                // 这是用户通过 addFd() 注册的 fd 事件
                // 将其封装为 Response，稍后在 pollOnce() 中分发
                Response response;
                response.events = epollEvents;
                response.request = mRequests.valueAt(requestIndex);
                mResponses.push(response); // 加入响应队列
            }
        }
    }
 
    // ========== 第四阶段：处理到期的 Native 消息 ==========
    nsecs_t now = systemTime(SYSTEM_TIME_MONOTONIC);
    while (mMessageEnvelopes.size() != 0) {
        const MessageEnvelope& messageEnvelope = mMessageEnvelopes.itemAt(0);
        if (messageEnvelope.uptime <= now) {
            // 消息已到期，取出并调用 handler 处理
            sp<MessageHandler> handler = messageEnvelope.handler;
            Message message = messageEnvelope.message;
            mMessageEnvelopes.removeAt(0); // 从队列中移除
 
            // 调用用户注册的 MessageHandler
            handler->handleMessage(message);
        } else {
            // 最早的消息尚未到期，记录其到期时间供下次 pollInner 计算超时
            mNextMessageUptime = messageEnvelope.uptime;
            break; // 队列有序，后面的消息更晚到期，无需继续检查
        }
    }
 
    // ========== 第五阶段：分发 fd 回调 ==========
    for (size_t i = 0; i < mResponses.size(); i++) {
        Response& response = mResponses.editItemAt(i);
        if (response.request.ident == POLL_CALLBACK) {
            // 这是带回调的 fd 事件
            int fd = response.request.fd;
            int events = response.events;
            void* data = response.request.data;
            // 调用用户注册的回调
            int callbackResult = response.request.callback->handleEvent(fd, events, data);
            if (callbackResult == 0) {
                removeFd(fd); // 回调返回 0，表示不再监听该 fd
            }
            response.request.callback.clear(); // 释放回调引用
            result = POLL_CALLBACK; // 标记有回调被处理
        }
    }
 
    return result;
}

// --- wake()：唤醒正在 epoll_wait 中阻塞的线程 ---
void Looper::wake() {
    uint64_t inc = 1; // 写入值为 1（eventfd 会累加）
    // 向 eventfd 写入，触发 EPOLLIN 事件
    // 这会使 epoll_wait() 立即返回
    ssize_t nWrite = TEMP_FAILURE_RETRY(  // TEMP_FAILURE_RETRY: 被信号中断时自动重试
        write(mWakeEventFd.get(), &inc, sizeof(uint64_t))
    );
    if (nWrite != sizeof(uint64_t)) {
        // 写入失败（极少发生，除非 fd 被关闭）
        if (errno != EAGAIN) {
            LOG_ALWAYS_FATAL("Could not write wake signal to fd %d",
                             mWakeEventFd.get());
        }
    }
}
 
// --- awoken()：消费 eventfd 中的数据，重置就绪状态 ---
void Looper::awoken() {
    uint64_t counter;
    // 读取 eventfd 中的值，读完后 eventfd 计数归零
    // 如果不读取，epoll_wait 下次还会立即返回（水平触发模式 Level-Triggered）
    TEMP_FAILURE_RETRY(
        read(mWakeEventFd.get(), &counter, sizeof(uint64_t))
    );
}