MuPDF Fitz JNI 在 Jetpack Compose 虚拟列表中的线程安全与渲染架构 (Thread Safety and Rendering Architecture of MuPDF Fitz JNI in Jetpack Compose)

2026-09-23 暂无评论

1. 适用场景与背景

在 Android 原生应用中，使用高性能 C/C++ 渲染核心（如 MuPDF Fitz 引擎，com.artifex.mupdf.fitz 与 AndroidDrawDevice）进行大型 PDF 文档解析与按页栅格化渲染（Rasterization），并结合声明式 UI 框架 Jetpack Compose 的虚拟列表 LazyColumn 进行多页瀑布流呈现时，常遇到底层崩溃与渲染抖动问题。

2. 核心陷阱与症状 (Pitfall & Symptoms)

底层 JNI 并发冲突崩溃 (Native Segmentation Fault / Abort)：
- 现象：在快速滑动 PDF LazyColumn 列表时，应用瞬间发生 Native 崩溃，日志打印 Fatal signal 11 (SIGSEGV) 或 mupdf context error。
- 根本原因：MuPDF Fitz 的底层句柄（fz_context、fz_document、fz_page）使用 ThreadLocal 状态机制。当 Compose 的多个页面项在后台协程池（如 Dispatchers.IO）中通过并发的 LaunchedEffect 同时调用同一个 Document 实例的 loadPage() 或 drawPage() 时，引发了 C 层的竞态条件（Race Condition）。
虚拟列表滚动回弹与跳动 (Scroll Jitter)：
- 现象：滑动时列表项因为 Bitmap 尚未渲染完成而高度为 0，等到渲染完成后突然撑开，导致列表剧烈抖动、滚动位置重置。
宿主 JVM 单元测试链接失败 (UnsatisfiedLinkError in JVM Tests)：
- 现象：运行主机 JVM 单元测试（:app:testDebugUnitTest）时，只要代码直接引用或初始化了 MuPDF 类，就会尝试执行 System.loadLibrary("mupdf_java")，由于 Windows 开发机缺少 Linux ELF 动态链接库（.so），测试全部红屏报错。

3. 架构解决方案与最佳实践 (Solution & Architecture)

3.1 互斥锁保护原生会话 (Mutex Thread-Safety)

在包装类（如 MuPdfDocumentRenderer）内部使用 Kotlin 协程互斥锁 Mutex，将对底层 Document 指针的访问强制串行化：

private val mutex = Mutex()

override suspend fun renderPage(pageIndex: Int, targetWidth: Int): Bitmap? = withContext(Dispatchers.IO) {
    if (closed) return@withContext null
    mutex.withLock {
        var page: Page? = null
        try {
            page = document.loadPage(pageIndex)
            val bounds = page.bounds
            val scale = targetWidth.toFloat() / (bounds.x1 - bounds.x0)
            AndroidDrawDevice.drawPage(page, Matrix(scale))
        } finally {
            try { page?.destroy() } catch (_: Throwable) {}
        }
    }
}

[IMPORTANT]
每个 Page 实例在渲染或提取边界后，必须在 finally 块中立即显式调用 page.destroy() 释放其对应的 C 语言堆内存指针，严禁依赖 JVM 的 GC Finalizer。

3.2 页面预计算与宽高比占位 (Aspect Ratio Pre-calculation)

在实际像素尚未光栅化之前，先由轻量级的 getPageDimensions(pageIndex) 提取 bounds.width 与 bounds.height：

在 Compose 的卡片容器上直接应用 Modifier.aspectRatio(width / height)；
页面未加载完成时展示固定比例的骨架占位图与进度指示器，彻底消除 LazyColumn 滚动抖动。

3.3 内存 LRU 缓存与平滑回收 (Bitmap LRU Cache)

使用 LruCache<String, Bitmap> 缓存最近可见的 12~16 页，避免同一屏反复轻微上下滚动时的 CPU 重新渲染开销；
缩放变更时，按桶划分（如 (targetWidth / 100) * 100）避免 1px 尺寸微动导致缓存抖动穿透；
在文档会话退出（DisposableEffect.onDispose）或 Tab 关闭时，显式调用 renderer.close() 执行 cache.evictAll() 与 document.destroy()。

3.4 抽象解耦与测试友好 (Interface Decoupling)

定义通用接口 PdfDocumentRenderer : Closeable：

interface PdfDocumentRenderer : Closeable {
    val pageCount: Int
    suspend fun getPageDimensions(pageIndex: Int): PdfPageDimensions
    suspend fun renderPage(pageIndex: Int, targetWidth: Int): Bitmap?
    suspend fun loadOutline(): List<PdfOutlineItem>
    fun isClosed(): Boolean
}