福昕 PDF SDK 多线程安全使用指南

概述

自 v10.0 起，福昕 PDF SDK 引入内置线程安全机制；增强了 LibreOffice 转 PDF 多线程支持；从 v11.0 起，进一步增强了文档级多线程支持能力，尤其在 JavaScript、XFA、文档级对象方面。 为确保 SDK 在多线程环境中稳定高效运行，开发者仍需遵循特定的使用规范和初始化流程。

线程安全机制

1. 合规性引擎线程安全

• 版本要求：从 v10.0 版本开始，compliance 资源文件提供了默认的线程安全机制
• 初始化要求：对于多线程使用，必须在每个新线程开始前，首先调用 ComplianceEngine.initializeThreadContext API
• 使用顺序：初始化线程上下文后，才能安全使用合规性插件模块的其他接口

2. Office 转 PDF 多线程支持

• Linux平台：在Linux x86/x64架构下，提供专用的 LibreOffice 二进制程序支持多线程转换
• 实现方式：将对应架构的专用二进制引擎路径赋值给engine_path参数即可启用多线程转换

Java 示例：

String engine_path = "/resource-folder/x64/fxoffice2pdf"; // 请替换为正确的引擎路径。
Convert.fromWord(word_file_path, "", output_path, engine_path, word_convert_setting_data);

3. JavaScript 和 XFA 线程安全

• 版本要求：从 v11.0.0 版本开始， SDK 增强了 JavaScript 和 XFA 的线程安全处理
• 初始化要求：对于线程安全处理机制， 调用 Library::Initialize()重载版本，设置参数bool enable_js_xfa_threadsafety为true

4. 文档级别线程安全

• 架构改进：v11.0.0 版本对整体架构进行了改进，增强了文档级别的线程安全
• 核心规则：一个PDF文档仅支持在一个线程中处理，确保文档操作的数据一致性和安全性

平台限制

MacOS 平台限制 (Java)

• 不支持多线程：Mac Java 语言库目前不支持多线程操作
• 资源替换要求：需将资源包中 var\legacy 目录下的 pdfEngineLight.dylib 文件复制到 compliance/mac

多线程使用注意事项 (以 Java 为例)

💡 详细的 Java 对象释放机制可参考 福昕 PDF SDK Java 对象管理。

1. 初始化顺序（必须先初始化线程上下文）

// 正确的多线程初始化顺序
ComplianceEngine.initializeThreadContext(); // 必须先调用
// 然后才能使用其他合规性接口

2. 对象管理

• 手动释放 GSDK 对象：务必通过 .delete() 方法释放对象，避免内存泄漏
• 释放顺序：先释放子对象，再释放父对象
• 不依赖 GC：Java 的垃圾回收机制不会自动释放底层 C++ 对象，必须手动管理

示例

PDFDoc doc = new PDFDoc("sample.pdf");
doc.load(null);
PDFPage page = doc.getPage(0);
Annot annot = page.addAnnot(Annot.e_Link, rectF);
Link link = new Link(annot);

// 推荐释放顺序
link.delete();    // 子对象
annot.delete();   // 注释对象
page.delete();    // 页面对象
doc.delete();     // 文档对象

---