MuPDF 编码风格指南:SumatraPDF 所依赖的 C 库命名、类型与引用计数规范
MuPDF 编码风格指南:SumatraPDF 所依赖的 C 库命名、类型与引用计数规范
MuPDF 是一个轻量级、高性能的 PDF 渲染库,也是 SumatraPDF 解析与渲染 PDF、XPS、EPUB 等格式的底层引擎(见 EngineMupdf.cpp)。本文基于官方仓库中的 coding-style.md 整理,系统讲解 MuPDF C 库的缩进规则、函数命名体系、整数类型约定,以及贯穿全库的引用计数(reference counting)所有权模型。读完本文,你将掌握读懂和编写 MuPDF 风格 C 代码的必备知识,并能在 src 下阅读 SumatraPDF 对 MuPDF 引擎的调用时,准确判断"谁负责释放、何时可以借用"。
一、缩进:两条硬规则
MuPDF 的缩进风格只有两条硬性规则,其余全部"从周围的源码推断"即可:
- 使用硬制表符(hard tabs)缩进,不使用空格;
- 除左边缘外,禁止任何垂直对齐(do not vertically align anything beyond the left edge)。
第二条规则意味着:不要为了让相邻行的 =、注释或类型对齐而额外插入空格,所有内容从行首按 tab 自然缩进即可。这样带来的好处是:每个开发者可以在自己的编辑器中自由设置 tab 显示宽度,只要遵循上述两条规则,任何 tab 宽度下代码都能正确对齐,彻底避免了"空格党 vs Tab 党"的冲突。
其余约定延续自源码现状(例如 ext/mupdf/source/fitz 目录下的实现文件):
- 花括号
{、}独占一行; if、for、while等关键字与后面的表达式之间保留一个空格。
二、命名规范:动词_名词体系与强制前缀
2.1 函数命名五式
MuPDF 要求函数名按照以下五种方案之一命名(均以下划线连接小写单词):
| 模式 | 含义 | 示例 |
|---|---|---|
verb_noun |
动作 + 对象 | pdf_open_document |
verb_noun_with_noun |
动作 + 对象 + 修饰对象 | fz_copy_option 等 |
noun_attribute |
对象 + 属性 | pdf_page_number 等 |
set_noun_attribute |
设置对象属性 | pdf_set_page_boxes 等 |
noun_from_noun |
类型转换(从 A 得到 B),避免 noun_to_noun |
fz_pixmap_from_page 等 |
2.2 前缀是强制的
所有导出的函数、宏、枚举、全局变量和类型都必须带前缀:
fz:通用代码(fitz 内核),例如fz_new_context、fz_drop_context;pdf、xps等:解释器(interpreter)专属代码,例如 pdf/document.h 中的pdf_open_document。
私有函数和类型的带前缀是可选的,但官方鼓励也加上。
前缀并非装饰,它在 30 万行级别的代码库中起到了"命名空间"的作用:一眼即可判断某个符号属于 fitz 内核还是某个格式解释器。从源码结构看,source 下 fitz/、pdf/、xps/、cbz/、html/、svg/ 等目录与这一前缀体系一一对应。
2.3 禁止 "get",保留字有特殊含义
- 避免使用
get,因为它是无意义、冗余的填充词(如getPage这类名字在 MuPDF 中不会出现); - 以下单词保留给引用计数体系使用,含义严格受控(详见第四节):
new、create、find、load、open、keep、drop; lookupvsfind:按名称查找对象/值时,若返回借用指针或值用lookup;若返回调用方负责释放的对象用find。这一区分在 store.h 中体现为fz_find_item(返回 store 中缓存项的借用指针)与文档打开类fz_open_document(返回需要释放的新对象)的差异。
三、类型约定:宽度有保证,浮点用 float
MuPDF 在 include/mupdf/fitz 的公共头文件中大量暴露 C 基础类型,并对其宽度做出明确假设:
| 类型 | 假设宽度 |
|---|---|
int |
至少 32 位 |
short |
恰好 16 位 |
char |
恰好 8 位 |
size_t |
32 位构建下为 32 位;所有 64 位构建下为 64 位,用于数组大小、字符串长度与分配大小 |
unsigned char / uint8_t |
表示字节缓冲(buffer)数据 |
int64_t |
文件/流内偏移量(offset) |
float |
IEEE 兼容,优先使用,尽量避免 double |
这套约定的工程意图很明确:
- 使用
size_t统一度量长度与分配,避免 32/64 位平台差异导致的内存问题; - 用无符号字节类型表达"原始字节流"语义,与
char的"字符"语义区分; - 文件偏移统一为
int64_t,保证大文件(超过 4GB)也能正确寻址; - 优先
float而非double:PDF 坐标、变换矩阵等大量几何运算在fz_matrix、fz_rect等结构中以float存储(见 geometry.h),在保证精度足够的前提下节省内存并利于 SIMD 优化。
四、引用计数:所有权语义是理解 MuPDF 的关键
这是编码风格文档中技术含量最高、也最影响正确性的部分。MuPDF 的对象生命周期完全由所有权单词约定驱动,读代码时看函数名即可判断内存责任归属。
4.1 两个单词阵营
- 取得所有权(take ownership):
new、create、find、load、open、keep—— 返回的对象由调用方负责释放; - 释放所有权(release ownership):
drop—— 放弃对传入对象的持有。
4.2 所有权转移规则
- 函数名含上述所有权单词时,返回的对象由调用者负责在返回前调用
drop(或free、close)释放; - 只有当你返回的函数本身也用所有权单词命名时,才可以把持有的对象所有权继续传递给调用者(所有权转移);
- 函数名不含任何所有权单词时,返回的是借用(borrowed)指针,生命周期有限:不要保存到当前函数返回之后,也不要塞进 struct 中长期持有。若确需长期持有,必须调用
keep增加引用计数,或自行复制一份。
4.3 源码印证
以 document.h 中最典型的文档生命周期为例:
fz_document *fz_open_document(fz_context *ctx, const char *filename); // open:取得所有权
fz_document *fz_keep_document(fz_context *ctx, fz_document *doc); // keep:增加引用
void fz_drop_document(fz_context *ctx, fz_document *doc); // drop:释放引用
PDF 解释器层同样遵循这一约定(pdf/document.h):
pdf_document *pdf_open_document(fz_context *ctx, const char *filename);
pdf_document *pdf_create_document(fz_context *ctx);
pdf_document *pdf_keep_document(fz_context *ctx, pdf_document *doc);
void pdf_drop_document(fz_context *ctx, pdf_document *doc);
而 context.h 中的 fz_new_context / fz_drop_context 则展示了另一种"所有权单词"用法:fz_new_context 创建新的 fz_context,fz_drop_context 释放之——每个线程的 fz_context 都必须用成对的 new/drop 管理。
缓存层最能体现 lookup 与 find、借用与持有的差别(store.h):
void *fz_find_item(fz_context *ctx, fz_store_drop_fn *drop, void *key, const fz_store_type *type);
void *fz_store_item(fz_context *ctx, void *key, void *val, size_t itemsize, const fz_store_type *type);
fz_find_item 从全局 store 缓存中查找条目,返回的是借用指针,调用方不能对其调用 drop;fz_store_item 存入新条目,由 store 接管所有权。这一设计让字体、图像等共享资源得以跨文档缓存复用,同时避免双重释放。
4.4 为什么这套约定如此重要
MuPDF 是面向嵌入式和高并发场景的 C 库,没有 RAII、没有 GC。所有权单词相当于一套"人肉 RAII":
- 可读性:函数签名即文档,调用方扫一眼函数名就知道该不该释放返回值;
- 安全性:严格遵守规则可避免 use-after-free(借用指针被长期保存)与内存泄漏(所有权对象未 drop)这两类 C 程序头号内存问题;
- 可审查性:代码评审时只需核对函数名中的所有权单词与调用点的 drop/keep 是否配对。
五、在 SumatraPDF 中观察这套风格的实际应用
SumatraPDF 通过 EngineMupdf.cpp 与 MuPDF 集成,其中大量代码直接遵循上述命名与所有权约定,是理解本指南的最佳"活教材":
- 打开文档时使用
pdf_open_document/fz_open_document取得所有权,随后在引擎析构路径中调用pdf_drop_document/fz_drop_document释放,形成成对的 open/drop; - 页、字体等短期对象多使用借用指针(如从文档句柄获取的页面指针),仅在当前函数作用域内使用;
- SumatraPDF 自身的 C++ 代码(src 下的
fz_*封装层)则把 MuPDF 的借用指针及时转换为fz_keep_*+fz_drop_*的智能持有,避免把借用指针越过函数边界保存。
阅读 EngineMupdf.cpp 时,你可以带着第四节的所有权模型逐行核对:每个 open/new/keep 是否在同一作用域内配对了 drop,每个从非所有权单词函数返回的指针是否只在本函数内使用——这正是指南想训练读者养成的习惯。
结语
MuPDF 编码风格的核心可以浓缩为三句话:Tab 缩进、禁止右对齐;导出的每个符号都必须带 fz_ 或 pdf_ 等前缀,函数名遵循动词_名词体系;new/open/keep 与 drop 构成唯一的内存所有权语言,借用指针不得跨函数保存。这套约定让 MuPDF 在不依赖 C++ 的情况下依然能够在大规模团队协作中保持可维护性。无论是为 MuPDF 贡献代码,还是在 SumatraPDF 这类集成项目中安全地调用它,掌握这些规则都是第一步。