MuPDF C 编码风格指南:命名、缩进与引用计数规则解析
MuPDF C 编码风格指南:命名、缩进与引用计数规则解析
本文以 MuPDF 官方编码风格文档为骨架,系统梳理其 C 库(fitz 公共层与 pdf/xps 等解释器层)在缩进、命名、基础类型假设与引用计数上的硬性约定,并结合仓库源码(如 source/fitz/document.c、source/fitz/bitmap.c、source/fitz/context.c)印证这些规则在实际实现中的落地方式。读完本文,你将能够快速读懂 MuPDF 源码的命名语义、准确判断一个函数返回值是否"归你所有",以及为 MuPDF 贡献代码时写出风格一致的补丁。
缩进:两条不可妥协的硬规则
MuPDF 的缩进风格非常简洁,其全部精髓浓缩为两条硬性规则(详见 docs/reference/c/coding-style.md):
- 必须使用硬制表符(hard tab)缩进;
- 禁止在左边界之外做任何形式的垂直对齐(Do not vertically align anything beyond the left edge)。
这意味着你不需要(也不应该)手动把赋值号 =、注释符 // 之类的元素在列方向上对齐,也不需要在行首使用空格。如果你偏好不同的视觉宽度,只需在自己的编辑器中配置自己喜欢的 tab 宽度(如 4 或 8 空格宽度),只要遵循上述两条规则,任何人的代码在你的编辑器里都会整齐一致——这正是"tab 缩进 + 不做列对齐"的协作价值:样式冲突被彻底消除。
其余细节可以通过观察既有源码自然习得:
- 大括号独占一行(Allman 风格),例如:
void
fz_drop_document(fz_context *ctx, fz_document *doc)
{
if (fz_drop_imp(ctx, doc, &doc->refs))
{
...
}
}
if、for、while与其表达式之间留一个空格,例如if (cond)而非if(cond)。
从 source/fitz/document.c 的实现可以看到,上述两条规则在真实的 MuPDF 代码中被严格执行:函数返回类型与函数名分行书写,左花括号独占一行,关键字与括号间有空格。
命名:动词驱动的函数命名体系
MuPDF 的函数命名遵循一套固定的短语模式,这让读者仅凭函数名就能推断其行为:
| 模式 | 语义 | 示例 |
|---|---|---|
verb_noun |
动作 + 对象 | fz_drop_document、fz_keep_bitmap |
verb_noun_with_noun |
动作 + 对象 + 介词对象 | fz_new_document_of_size |
noun_attribute |
名词 + 属性(读取属性) | fz_document_supports_accelerator |
set_noun_attribute |
设置属性 | fz_tune_image_scale |
noun_from_noun |
类型转换(避免 noun_to_noun) |
fz_new_bitmap_from_pixmap |
其中 verb_noun 模式在源码中随处可见,例如 source/fitz/bitmap.c 中的 fz_keep_bitmap / fz_drop_bitmap 成对出现,构成典型的生命周期管理接口。
前缀约定:导出的符号必须带前缀
对于导出的函数、宏、枚举、全局变量和类型,前缀是强制性的:
fz—— 用于公共通用代码(fitz层),如fz_context、fz_document;pdf、xps等 —— 用于各解释器特有代码,如pdf_obj、xps_document。
对于私有函数和类型,前缀是可选的(但鼓励使用)。在 MuPDF 源码中,大量内部辅助函数会写成 static 并省略前缀,例如 source/fitz/context.c 中的 fz_new_tuning_context、fz_keep_tuning_context 虽然是 static 私有函数,但仍保留了 fz_ 前缀。
避免无意义的 "get"
文档明确要求避免使用 get 作为函数名的一部分,因为它是一个无意义、冗余的填充词。例如读取文档元数据用的是 fz_lookup_metadata(见 include/mupdf/fitz/document.h),而不是 fz_get_metadata。
保留词:引用计数的语义标记
有一组词被保留用于表达引用计数语义,这是 MuPDF 命名体系中最关键的部分:
new、create、find、load、open、keep—— 返回一个你负责释放的对象;drop—— 放弃对传入对象的所有权(即减少一次引用并可能释放)。
当需要"查找"一个对象或值时,选择哪个词取决于返回值是否转移所有权:
lookup—— 返回值或借用指针(borrowed pointer),调用方不负责释放;find—— 返回一个调用方负责释放的对象。
例如 include/mupdf/fitz/document.h 中打开文档的 API 命名为 fz_open_document(返回 fz_document *,调用方随后必须 fz_drop_document),而查询书签的接口则是 fz_lookup_bookmark(借用式查询)。
类型:贯穿全库的位宽假设
MuPDF 对 C 基础整数类型做了明确且统一的假设,编写或阅读代码时必须遵守:
| 类型 | 约定 |
|---|---|
int |
至少 32 位 |
short |
恰好 16 位 |
char |
恰好 8 位 |
size_t |
用于数组大小、字符串长度与内存分配计量;32 位构建下为 32 位,所有 64 位构建下为 64 位 |
unsigned char / uint8_t |
用于数据缓冲区(byte buffer) |
int64_t |
用于文件/流内的偏移量(offset) |
此外,浮点运算优先使用 float 而非 double(在能够满足精度需求的前提下),并假设其符合 IEEE 规范。
这些约定与源码实现完全一致:例如 source/fitz/bitmap.c 的 fz_new_bitmap 接收 int w, int h 描述像素尺寸,而以 size_t 计算 h * stride 的内存分配(见 source/fitz/bitmap.c);source/fitz/buffer.c 的 fz_new_buffer(fz_context *ctx, size_t size) 也以 size_t 表达缓冲区大小。流内偏移相关接口在 fz_stream 体系中使用 64 位有符号整数,以支持超大文件。
引用计数:所有权转移的完整规则
MuPDF 的所有核心对象(fz_context、fz_document、fz_bitmap、fz_pixmap、fz_buffer 等)都通过引用计数管理生命周期,而所有权规则完全由函数名中的保留词表达。
取走所有权的词:new / find / load / open / keep
若一个函数名包含上述任一保留词,则其返回的对象归你所有,你必须在使用完毕后调用 drop、free 或 close 来释放,否则会造成泄漏。你只能通过以保留词命名的函数来转移这份所有权——即你不能在一个名为 fz_some_utility 的普通函数里返回一个你持有的对象并指望调用方去释放。
源码佐证:在 source/fitz/document.c 中,fz_new_document_of_size 创建对象后立即 doc->refs = 1,把初始引用计数置为 1,表示"这份所有权已交付给调用方"。对应的 fz_keep_document(source/fitz/document.c)通过 fz_keep_imp(ctx, doc, &doc->refs) 递增引用计数,而 fz_drop_document(source/fitz/document.c)通过 fz_drop_imp 递减并在归零后执行真正的清理(释放用户 CSS、调用 drop_document 回调、释放结构体本身)。同样的模式出现在 source/fitz/bitmap.c:fz_keep_bitmap 递增 refs,fz_drop_bitmap 在计数归零后释放 samples 与结构体。
释放所有权的词:drop
drop 表示放弃传入对象的所有权——即减少一次引用;当引用计数归零时,对象会被真正销毁。注意与"释放内存"的细微差别:drop 的是所有权(引用),对象是否真正释放取决于计数。
借用对象:没有保留词的函数返回值
任何由不包含保留词命名的函数返回的对象,都是借用的(borrowed),生命周期有限。 你不能将其保存超过当前函数的执行时长,也不能把它塞进结构体中长期持有。如果确实需要长期使用,你有两个选择:
- 调用对应的
keep函数(如fz_keep_document、fz_keep_bitmap)将其"升级"为你自己的引用; - 自行制作一份拷贝。
这一点在 source/fitz/context.c 的 fz_drop_context 中同样体现:整个 MuPDF 上下文对象本身就是一个大型引用计数对象,fz_new_context(内部实现为 fz_new_context_imp,见 source/fitz/context.c)创建时引用计数为 1,多线程场景下子上下文通过 keep/drop 维护计数,直到最后一个引用释放时才会执行字体缓存、存储(store)、字形缓存等一系列终结清理(见 source/fitz/context.c)。
错误处理中的所有权
值得注意的还有 MuPDF 独特的错误处理范式:在 fz_always / fz_catch 块中正确释放对象。例如 source/fitz/context.c 中读取用户 CSS 文件的逻辑,无论成功与否都会在 fz_always 块中 fz_drop_buffer(ctx, buf),确保异常路径下也不泄漏——这是引用计数规则与 MuPDF 异常模型(fz_try/fz_catch/fz_always)配合使用的标准写法。
实战自查清单
在阅读或提交 MuPDF 代码时,可以用下面这份清单快速校验风格合规性:
- [ ] 缩进使用硬 tab,且未做任何超出左边界的列对齐;
- [ ] 大括号独占一行,
if/for/while后带空格; - [ ] 导出符号带有
fz_、pdf_、xps_等强制前缀; - [ ] 函数名符合
verb_noun等命名模式,且未使用无意义的get; - [ ] 返回自有对象的函数名包含
new/create/find/load/open/keep,并且调用方随后调用drop/free/close; - [ ] 返回借用对象的函数名不含保留词,且调用方未将其存入结构体或长期持有;
- [ ] 需要长期持有借用对象时,已调用
keep或制作拷贝; - [ ] 数组大小/字符串长度使用
size_t,数据缓冲区使用unsigned char,文件偏移使用int64_t,浮点优先float。
遵循这套约定,不仅是让代码"好看",更是让 MuPDF 的每个函数签名自带所有权契约:函数名本身就是文档。当你在 include/mupdf/fitz/ 下阅读公共头文件(如 include/mupdf/fitz/document.h)时,仅凭 fz_open_*、fz_keep_*、fz_drop_*、fz_lookup_* 的前缀组合,就能在几秒内判断每个 API 的调用与释放义务,这是理解这个大型 C 代码库最高效的入门路径。