MuPDF 编码风格指南:SumatraPDF 所依赖的 C 库命名、类型与引用计数规范

原创2026-09-20 10:39:061,413 阅读
文章标签:桌面应用

MuPDF 编码风格指南:SumatraPDF 所依赖的 C 库命名、类型与引用计数规范

MuPDF 是一个轻量级、高性能的 PDF 渲染库,也是 SumatraPDF 解析与渲染 PDF、XPS、EPUB 等格式的底层引擎(见 EngineMupdf.cpp)。本文基于官方仓库中的 coding-style.md 整理,系统讲解 MuPDF C 库的缩进规则、函数命名体系、整数类型约定,以及贯穿全库的引用计数(reference counting)所有权模型。读完本文,你将掌握读懂和编写 MuPDF 风格 C 代码的必备知识,并能在 src 下阅读 SumatraPDF 对 MuPDF 引擎的调用时,准确判断"谁负责释放、何时可以借用"。

一、缩进:两条硬规则

MuPDF 的缩进风格只有两条硬性规则,其余全部"从周围的源码推断"即可:

  1. 使用硬制表符(hard tabs)缩进,不使用空格;
  2. 除左边缘外,禁止任何垂直对齐(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;
  • lookup vs find:按名称查找对象/值时,若返回借用指针或值用 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 这类集成项目中安全地调用它,掌握这些规则都是第一步。

登录后查看全文
sumatrapdf