MuPDF C 编码风格指南:命名、缩进与引用计数规则解析

原创2026-10-05 17:58:562,275 阅读
文章标签:图像处理OCR文档

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):

  1. 必须使用硬制表符(hard tab)缩进;
  2. 禁止在左边界之外做任何形式的垂直对齐(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),生命周期有限。 你不能将其保存超过当前函数的执行时长,也不能把它塞进结构体中长期持有。如果确实需要长期使用,你有两个选择:

  1. 调用对应的 keep 函数(如 fz_keep_document、fz_keep_bitmap)将其"升级"为你自己的引用;
  2. 自行制作一份拷贝。

这一点在 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 代码库最高效的入门路径。

登录后查看全文
mupdf