facil.io 框架基准测试实战指南:基于 FrameworkBenchmarks 的 C 语言 JSON 与 PLAINTEXT 实现解析
facil.io 框架基准测试实战指南:基于 FrameworkBenchmarks 的 C 语言 JSON 与 PLAINTEXT 实现解析
本文基于 TechEmpower FrameworkBenchmarks 仓库中 facil.io 测试目录 的官方说明与源码,完整剖析该 C 语言事件驱动 Web 框架如何接入基准测试体系:从测试类型配置、路由与响应处理的核心实现,到构建脚本、Docker 运行参数,再到事件驱动与内存所有权两大设计约束。读完本文,你将掌握在 FrameworkBenchmarks 中为 facil.io(或类似 C 框架)新增、验证与运行基准测试的完整路径,并能理解 http_pause/http_resume、fiobj_dup 等 API 在事件驱动编程中的正确用法。
测试概况:facil.io 当前覆盖的测试类型
根据 README.md 的说明,facil.io 基准测试当前实现了两个无数据库依赖的测试类型:
| 测试类型 | 实现状态 | 测试 URL |
|---|---|---|
| JSON | ✅ 已实现 | http://localhost:8080/json |
| PLAINTEXT | ✅ 已实现 | http://localhost:8080/plaintext |
| DB | ❌ 未实现(本版本) | http://localhost:8080/db |
| QUERY | ❌ 未实现(本版本) | http://localhost:8080/query?queries= |
| CACHED QUERY | ❌ 未实现(本版本) | http://localhost:8080/cached_query?queries= |
| UPDATE | ❌ 未实现(本版本) | http://localhost:8080/update?queries= |
| FORTUNES | ❌ 未实现(本版本) | http://localhost:8080/fortunes |
测试基于完整的 HTTP 框架栈(不包含任何数据库支持)运行。数据库类测试(DB、QUERY、CACHED QUERY、UPDATE、FORTUNES)在文档中明确标注为 "Not implemented for this version",README 中这些测试的 URL 位于注释块内,仅作规划参考。
在 benchmark_config.json 中,本次测试被声明为 approach: "Realistic"、classification: "Micro"、database: "None"、orm: "Raw"、webserver: "None",服务端口固定为 8080,路由为 /json 与 /plaintext。等效的声明也出现在 config.toml 中,说明该框架测试同时支持两种元数据格式。
核心实现解析:bench_app.c 的请求处理链路
整个测试实现集中在 bench_app.c 一个文件中,仅依赖 http.h 与 fio_cli.h 两个头文件。其运行主流程(main 函数,第 54-87 行)依次完成:CLI 参数初始化 → 注册路由 → 预创建可复用对象 → 启动 HTTP 监听 → 启动 facil.io 事件循环(reactor)。
基于哈希表实现的最小路由器
路由部分使用 facil.io 的通用哈希容器 FIO_SET 宏体系构建,见 bench_app.c 第 160-171 行:
typedef void (*fio_router_handler_fn)(http_s *);
#define FIO_SET_NAME fio_router
#define FIO_SET_OBJ_TYPE fio_router_handler_fn
#define FIO_SET_KEY_TYPE fio_str_s
#define FIO_SET_KEY_COPY(dest, obj) fio_str_concat(&(dest), &(obj))
#define FIO_SET_KEY_DESTROY(obj) fio_str_free(&(obj))
#define FIO_SET_KEY_COMPARE(k1, k2) fio_str_iseq(&(k1), &k2)
#define FIO_INCLUDE_STR
#define FIO_STR_NO_REF
#include <fio.h>
路由表本质上是一个以字符串路径为键、函数指针为值的哈希表。route_add 将路径字符串包装为 fio_str_s 并插入哈希表(第 174-179 行),注释特别说明 facil.io 哈希表支持最多 96 次完全冲突,因此可以直接使用字符串长度作为哈希种子。route_perform(第 182-195 行)在每次请求到来时先为响应注入 Server 头,再从哈希表按请求路径查找处理函数,找不到则返回 http_send_error(h, 404)。
JSON 响应:每次请求动态序列化
on_request_json(第 94-105 行)展示了 facil.io 的 FIOBJ 对象模型用法:
static void on_request_json(http_s *h) {
http_set_header(h, HTTP_HEADER_CONTENT_TYPE, http_mimetype_find("json", 4));
FIOBJ json;
/* create a new Hash to be serialized for every request */
FIOBJ hash = fiobj_hash_new2(1);
fiobj_hash_set(hash, JSON_KEY, fiobj_dup(JSON_VALUE));
json = fiobj_obj2json(hash, 0);
fiobj_free(hash);
fio_str_info_s tmp = fiobj_obj2cstr(json);
http_send_body(h, tmp.data, tmp.len);
fiobj_free(json);
}
关键细节:JSON_KEY("message")与 JSON_VALUE("Hello, World!")在 main 中通过 fiobj_str_new 一次性创建并复用(第 67-68 行),但每次请求仍新建哈希对象,通过 fiobj_dup 复制值后再 fiobj_obj2json 序列化,最后用 http_send_body 直接发送响应体。
PLAINTEXT 响应:最简路径
on_request_plain_text(第 108-111 行)将 Content-Type 设为 text/plain(通过 http_mimetype_find("txt", 3) 查表),然后直接发送 13 字节的 "Hello, World!",没有任何对象序列化开销。
命令行参数:CLI 帮助器
cli_init(第 118-154 行)基于 fio_cli_start 注册了以下参数,这些参数同时决定了测试容器启动时的行为:
| 参数 | 别名 | 含义 |
|---|---|---|
-threads |
-t |
工作线程数,默认依赖系统 |
-workers |
-w |
进程数,默认依赖系统 |
-port |
-p |
监听端口,默认在代码中设为 8080 |
-address |
-b |
绑定地址 |
-public |
-www |
静态文件服务目录(可选) |
-log |
-v |
是否输出请求日志 |
-database |
-db |
数据库地址(URL),默认取环境变量 DBHOST,否则为 localhost |
注意 -db 参数当前仅为后续数据库类测试预留:它不会影响 JSON/PLAINTEXT 的运行,但从 setup-common.sh 与 Dockerfile 可见,构建体系已为将来接入 tfb-database 容器做好准备。
事件驱动设计:新增数据库测试的必读约束
README 的 "Adding Tests" 一节给出了两条对后续贡献者至关重要的设计约束,这也是理解 facil.io 与其他阻塞式框架测试实现差异的核心。
约束一:请求处理必须是事件驱动的
facil.io 被设计为事件驱动(evented)模型。当需要接入数据库类测试时,不要在线程中同步等待数据库结果,而应使用 http_pause / http_resume 机制:
http_pause(h):将请求暂停处理(挂起当前响应上下文);- 数据库异步结果到达后,在回调中调用
http_resume(h)恢复请求处理。
这正是易踩的坑:如果忘记在结果到达后恢复请求,该请求将永远悬挂。README 特别提醒"at which point, remember to resume the request"。
如果事件驱动方案在某个实现场景下不可行(例如使用的数据库客户端不提供异步 API),README 给出的替代方案是增加线程数:通过命令行 -t 参数提高线程数来换取并发处理能力。这一点在 facil.io.dockerfile 的启动命令中已有体现:
CMD ./facil_app/tmp/fioapp -p 8080 -db "tfb-database" -w -2 -t 2
-w -2 表示让工作进程数由系统自动决定(负值通常表示按 CPU 核心推导),-t 2 表示每个进程使用 2 个线程。
约束二:内存所有权归设计(Memory Ownership Oriented)
README 强调 facil.io 采用"内存所有权归设计":将数据放入其他对象(如设置 header 值、哈希值)的函数,接管数据的所有权,但不接管其键(key)的所有权。
具体到添加 HTTP header 的例子:
- header 的**名称(key)**仍由调用方持有所有权,调用方使用完毕后应负责释放;
- header 的**值(value)**从此归 header 集合所有,调用方不能再使用它,除非先用
fiobj_dup复制一份。
这一规则只适用于"把数据放入对象"的函数(详见 FIOBJ 文档),不适用于收发型函数——例如 pubsub_publish 或 pub/sub 处理器,这类场景数据是"透传或复制"的,不会被放进可访问对象,因此不存在所有权转移。
这一约束在 bench_app.c 中有直接印证:route_perform 中设置 Server 头时使用 fiobj_dup(HTTP_VALUE_SERVER)(第 184 行),因为 HTTP_VALUE_SERVER 是全局复用的 FIOBJ 对象,若直接传给 http_set_header 让其接管所有权,下一次请求就无法再使用它。同理,JSON handler 中 fiobj_hash_set(hash, JSON_KEY, fiobj_dup(JSON_VALUE)) 也必须复制,否则键值会被哈希对象接管。
构建与运行:从源码到 Docker 容器
构建脚本 setup-common.sh
setup-common.sh 负责获取 facil.io 框架源码:
- 默认下载版本为
0.7.0.beta7(GitHub 上 boazsegev/facil.io 的 tarball); - 若设置环境变量
FIO_EDGE=1,则从master分支拉取最新开发版源码,用于在开发机上验证 edge 版本:$ FIO_EDGE=1 tfb --mode verify --test facil.io - 若
facil_app目录已存在且未设置FIO_EDGE,脚本会跳过下载(避免重复拉取)。
Dockerfile 构建链
facil.io.dockerfile 完整展示了编译与打包流程:
FROM gcc:6.4.0
COPY ./ ./
RUN ./setup-common.sh
# 1. we don't need more than 32K concurrent connections
# 2. facil.io hash maps are resistant to hash flooding, we can use a faster hashing function.
ENV CFLAGS="-DFIO_MAX_SOCK_CAPACITY=65536 -DFIO_USE_RISKY_HASH=1"
# compile test
RUN cp -f bench_app.c facil_app/src/app.c
# Build the app
RUN cd facil_app && make -j build
EXPOSE 8080
CMD ./facil_app/tmp/fioapp -p 8080 -db "tfb-database" -w -2 -t 2
三个值得关注的编译期优化(均由 Dockerfile 注释说明):
FIO_MAX_SOCK_CAPACITY=65536:基准测试并发连接数不会超过 32K,将容量上限放大到 65536 即可覆盖压测场景;FIO_USE_RISKY_HASH=1:facil.io 的哈希表本身对哈希洪水(hash flooding)有抵抗能力,因此可以启用更快的哈希函数来换取性能;- 通过
cp将bench_app.c覆盖到facil_app/src/app.c,再执行make -j build编译出fioapp可执行文件。
压测工具链
JSON 与 PLAINTEXT 测试在运行时的压测脚本由 toolset/wrk/concurrency.sh(JSON 使用并发模型)与 toolset/wrk/pipeline.sh(PLAINTEXT 使用管道模型)驱动,两脚本均使用 wrk 工具并遵循"Primer(5 秒预热)→ Warmup(满并发预热)→ 分级并发"的压测节奏。PLAINTEXT 测试通过 pipeline.lua 实现 16 深度请求管道(pipeline: 16,见 plaintext.py 第 77-78 行),以单连接内串联请求的方式压测。
验证机制:工具链如何校验 facil.io 的响应
FrameworkBenchmarks 的 --mode verify 模式会逐项校验测试端点。对 facil.io 的两个端点,验证逻辑位于工具链测试类型中:
JSON 端点验证
json.py 会请求 base_url + /json,并依次执行(完整校验函数见 verifications.py):
basic_body_verification:响应体非空且必须是合法 JSON;verify_helloworld_object:对象必须包含message键且值不区分大小写地等于hello, world!(注意:小写 h,与源码中的"Hello, World!"匹配时大小写不敏感);键值对超过 27 个字符会给出警告;verify_status:HTTP 状态必须为 200;verify_headers:响应必须包含Server、Date、Content-Type头,必须有Content-Length或Transfer-Encoding之一,Content-Type必须匹配^application/json(; ?charset=(UTF|utf)-8)?$,且连续两次请求的Date头不得相同(防止响应被缓存)。
facil.io 的 on_request_json 通过 http_set_header 注入 Content-Type、route_perform 注入 Server 头、http_send_body 自动管理响应长度,恰好满足全部校验条件。
PLAINTEXT 端点验证
plaintext.py 的校验相对宽松:响应体包含 hello, world! 即可,但若返回超过必需的字节数会给出警告("Server is returning N more bytes than are required. This may negatively affect benchmark performance."),这正是 http_send_body(h, "Hello, World!", 13) 精确控制字节数的原因。Content-Type 则需匹配 ^text/plain(; ?charset=(UTF|utf)-8)?$。
整个校验流程由 framework_test.py 的 verify_urls 调度:依次对每个测试类型调用 verify(),将结果以 pass / warn / fail 三级写入结果目录的 verification.txt,任何 fail 都会导致该测试整体不通过。
新增测试的工程流程参考
仓库的 scaffolding/README.md 给出了 TFB 框架测试的通用接入流程,对 facil.io 同样适用:
- 将实现源码置于测试目录下(facil.io 的做法是单一
bench_app.c); - 编辑
benchmark_config.json声明端点与端口; - 创建
<name>.dockerfile(facil.io 为facil.io.dockerfile),可在其中声明多个实现变体,例如facil.io-mysql.dockerfile对应benchmark_config.json中的facil.io-mysql条目; - 运行
tfb --mode verify --test facil.io验证端点可达且响应正确; - 验证通过后可将测试加入 CI 配置,并完善 README。
结语
facil.io 的这份基准测试实现是理解"事件驱动 C 框架如何接入 Web 基准测试体系"的极佳样本:JSON/PLAINTEXT 两个端点只用了约 110 行 C 代码,却完整覆盖了路由注册、FIOBJ 对象复用、响应头注入与精确字节控制;而 README 中关于 http_pause/http_resume 与内存所有权归属的两条约束,则为将来接入数据库类测试划清了技术边界。若要在本仓库基础上为 facil.io 补齐 DB、QUERY 等测试,建议从 fiobj 对象模型与异步数据库客户端回调这两处入手,并始终牢记:事件循环内的请求生命周期由 pause/resume 控制,对象所有权由"谁放入谁接管值、调用方保留键"的规则决定。