FrameworkBenchmarks 中 Lwan 基准测试实现详解:C 处理器与 Lua 脚本双版本解析
FrameworkBenchmarks 中 Lwan 基准测试实现详解:C 处理器与 Lua 脚本双版本解析
本技术指南以 TechEmpower Framework Benchmarks 仓库中 frameworks/C/lwan/README.md 为核心,围绕 Lwan 高性能 Web 服务器在基准测试中的完整接入方案展开:C 版全部测试端点(JSON、Plaintext、DB、Query、Cached Queries、Fortunes)与 Lua 版轻量端点如何实现、如何配置路由与数据库连接,以及如何用 wrk 与测试类型脚本验证结果。读完本文,你将掌握在 FrameworkBenchmarks 体系内理解与复现 Lwan 基准测试所需的全部配置参数、源码细节与运行前提。
一、Lwan 基准测试整体结构
本测试基于 Lwan 目录,并同时提供 C 版本与 Lua 版本两套基准实现:
| 版本 | 语言 | 覆盖测试点 | 核心文件 |
|---|---|---|---|
| C 版 | C | JSON / Plaintext / DB / Query / Cached Queries / Fortunes | src/techempower.c、src/database.c、src/json.c |
| Lua 版 | Lua(LuaJIT) | JSON / Plaintext | techempower.conf、src/json.lua |
两份 Dockerfile 分别对应两种形态:lwan.dockerfile 启用 MySQL 后端(USE_MYSQL=1),lwan-lua.dockerfile 则默认走 SQLite 且不预置数据库环境变量。两个版本的测试配置在 benchmark_config.json 与 config.toml 中被声明为 default 与 lua 两组。
二、C 版本:六个基准测试端点的实现
C 版本的全部六个测试端点均由同一个入口程序 src/techempower.c 实现,且使用同一个配置文件 techempower.conf 完成路由注册。
2.1 路由配置:site 与 handler 的绑定
techempower.conf 是整个 Lwan 基准测试的路由骨架。listener *:8080 声明监听所有网卡地址的 8080 端口;site {} 内使用 &handler /path 语法把 C handler 绑定到 URL,其中 & 前缀表示引用可执行模块:
listener *:8080
site {
# For main TWFB benchmarks
&plaintext /plaintext
&json /json
&db /db
&queries /queries
&cached_queries /cached-queries
&fortunes /fortunes
# For test harness
&quit_lwan /quit-lwan
&plaintext /hello
}
这里有两个细节值得注意:
- 除六个正式测试端点外,配置中还注册了
/quit-lwan(对应 src/techempower.c 中的quit_lwanhandler,直接调用exit(0))和/hello(Plaintext 的别名),用于测试工具链的控制与验收。 - 每个
&handler名称都会在源码中找到同名函数,例如LWAN_HANDLER(plaintext)、LWAN_HANDLER(json)、LWAN_HANDLER(quit_lwan),Lwan 通过宏把 handler 函数注册进模块系统。
2.2 各端点的访问地址与预期响应
按 frameworks/C/lwan/README.md 的 Test URLs 一节,六个端点的访问方式如下:
| 测试 | 地址 | 预期响应 |
|---|---|---|
| JSON | http://localhost:8080/json |
{"message":"Hello, World!"} |
| Plaintext | http://localhost:8080/plaintext |
Hello, World! |
| DB | http://localhost:8080/db |
单条 World 记录 {"id":N,"randomNumber":M} |
| Query | http://localhost:8080/query?queries= |
长度为 1–500 的 World 记录数组 |
| Cached Queries | http://localhost:8080/cached-queries?count= |
长度为 1–500 的 World 记录数组 |
| Fortunes | http://localhost:8080/fortunes |
HTML 表格,含 12 条固定数据加 1 条附加数据 |
注意 README 中 URL 写作 /query?queries= 与 /cached-queries?count=,而在配置文件里实际绑定的路径是 /queries 与 /cached-queries。以 benchmark_config.json 为准,正式声明的 URL 为:
"query_url": "/queries?queries=",
"cached_query_url": "/cached-queries?count=",
2.3 JSON 端点:基于描述符的声明式编码
json handler 使用静态字符串 hello_world("Hello, World!")构造响应。关键在于 Lwan 采用了 Zephyr 项目移植来的声明式 JSON 描述符机制(见 src/json.h):
struct hello_world_json {
const char *message;
};
static const struct json_obj_descr hello_world_json_desc[] = {
JSON_OBJ_DESCR_PRIM(struct hello_world_json, message, JSON_TOK_STRING),
};
JSON_OBJ_DESCR_PRIM 通过 offsetof 计算字段偏移、用 __alignof__ 记录对齐,让编码器无需反射即可直接读写结构体;json_response_obj() 再调用 json_obj_encode_full() 把数据编码进响应缓冲区并设置 application/json 的 MIME 类型。编码器在 src/json.c 中实现,包含基于 has_zero()/has_value() 位运算技巧的转义检测,以及对描述符中键名的"预拼引号+冒号"优化,减少每次编码时的间接调用(见 src/json.c 中 encode_key() 的注释)。
2.4 Plaintext 端点:零拷贝静态字符串
plaintext handler 是最极端的性能路径,直接用 lwan_strbuf_set_static() 把 hello_world 字符串的静态内存引用赋给响应缓冲区,完全避免复制与堆分配,并设置 text/plain MIME 类型:
LWAN_HANDLER(plaintext)
{
lwan_strbuf_set_static(response->buffer, hello_world,
sizeof(hello_world) - 1);
response->mime_type = "text/plain";
return HTTP_OK;
}
2.5 DB 与 Query 端点:随机 World 记录查询
DB 与 Query 共用同一条 SQL 预编译语句(random_number_query),通过 db_prepare_stmt() 准备、db_query() 执行:
static const char random_number_query[] =
"SELECT randomNumber, id FROM world WHERE id=?";
dbhandler:执行单次查询,随机键为rand() % 10000,返回单条 JSON 对象。querieshandler:解析queries参数并做边界裁剪,LWAN_MIN(500, LWAN_MAX(1, parse_long(queries_str, -1)))保证取值在 1–500 之间;随后循环查询并填充struct queries_json数组(最多 500 个元素),再用json_response_arr()编码成 JSON 数组。代码注释指出每条响应约 32 字节,因此预先lwan_strbuf_grow_to(response->buffer, 32 * queries)以避免构建过程中的重分配与拷贝。
参数边界与测试工具的对应关系
测试工具 toolset/test_types/query/query.py 会依次请求 queries 取值为 2、0、foo、501、空串的情况,并期望:
- 正常整数值返回等长数组;
- 超过 500 被截断为 500,低于 1 被提升为 1;
- 非数值参数在当前轮次仅告警(
warn),未来轮次将升级为失败(见 toolset/test_types/verifications.py 中verify_query_cases()的注释)。Lwan 的parse_long()对非数字返回 -1,再被钳制到 1,恰好满足该规则。
2.6 Cached Queries 端点:缓存条目的协程安全访问
cached_queries handler 将随机键对应的 World 记录缓存在 Lwan 的通用缓存 struct cache 中(创建于 src/techempower.c 的 main(),缓存有效期 3600 秒即 1 小时)。每次请求先 rand() % 10000 生成键,再从缓存取出 db_json_cached 条目并拷贝到结果数组。
为了在协程上下文中安全地取缓存引用,源码自定义了 my_cache_coro_get_and_ref_entry():它刻意不调用 coro_defer(),理由是当缓存元素过多时,coro_defer 数组会发生重分配、把内联存储"降级"到堆上,同时大量间接调用也会拖慢每次请求的处理(见 src/techempower.c 中该函数的详细注释)。该函数最多重试 64 次,遇 EWOULDBLOCK 时先 coro_yield 让出协程、再按重试次数递减地 lwan_request_sleep。
2.7 Fortunes 端点:协程驱动模板渲染
Fortunes 是最复杂的端点,采用 Lwan 模板引擎 + 协程迭代器的组合:
- 模板编译:
main()中调用lwan_tpl_compile_string_full()编译硬编码的 HTML 模板字符串fortunes_template_str(含{{#item}}…{{/item}}序列块)。 - 协程生成器:
fortune_list_generator()以协程函数形式工作——它用SELECT * FROM Fortune查询全部数据,逐行coro_strdup复制消息、追加到fortune_array,再补充一条固定文本"Additional fortune added at request time.",最后按消息字典序fortune_array_sort排序,并通过coro_yield逐条产出。 - 描述符绑定:模板通过
fortune_desc与struct Fortune绑定,其中TPL_VAR_STR_ESCAPE(item.message)负责 HTML 转义,TPL_VAR_SEQUENCE指定序列生成器。
响应 Content-Type 为 text/html; charset=UTF-8,缓冲区预先扩到 1500 字节。
测试侧对 Fortunes 的 HTML 结构有严格比对: toolset/test_types/fortune/fortune_html_parser.py 内置了 valid_fortune 标准串(12 条固定数据 + Additional fortune added at request time.),并忽略 <meta>、<link>、<script>、<thead>、<tbody> 等不影响语义的标签。
三、数据库抽象层:MySQL 与 SQLite 双后端
基准测试的数据库访问由 src/database.c 统一抽象,对外只暴露 struct db(disconnect / prepare 两个函数指针)与 struct db_stmt(bind / step / finalize 三个函数指针),上层业务代码完全不感知后端差异。
3.1 后端的切换逻辑
src/techempower.c 的 main() 通过环境变量 USE_MYSQL 决定连接方式:
- MySQL 分支:读取
MYSQL_USER、MYSQL_PASS、MYSQL_HOST、MYSQL_DB四个环境变量,任一缺失即lwan_status_critical()终止;调用db_connect_mysql(),内部使用mysql_real_connect()连接并mysql_set_character_set(con, "utf8")。 - SQLite 分支(默认):连接
techempower.db,并执行三个 PRAGMA 以逼近 MySQL 的读写性能形态:
static const char *pragmas[] = {"PRAGMA mmap_size=44040192",
"PRAGMA journal_mode=OFF",
"PRAGMA locking_mode=EXCLUSIVE", NULL};
其中 mmap_size 约 42 MiB 启用内存映射,journal_mode=OFF 关闭 WAL 日志,locking_mode=EXCLUSIVE 锁定单连接独占访问。
3.2 线程本地连接与签名式结果绑定
连接实例以线程本地存储(static __thread struct db *database)缓存在 get_db() 中,每个线程首次访问时才懒连接。语句结果读取采用"签名串"约定:db_stmt_step(stmt, "ii", &random_number, &id) 中,'i' 表示整型列、's' 表示字符串列(字符串还需附带缓冲区长度参数)。MySQL 后端据此动态构建 MYSQL_BIND 数组并 mysql_stmt_bind_result,SQLite 后端则按签名调用 sqlite3_column_int/text。参数绑定同样按 's'/'i' 映射到 MYSQL_TYPE_STRING/MYSQL_TYPE_LONG 或 sqlite3_bind_text/int。
该层对迁移到其他数据库(如 PostgreSQL)非常友好:只需新增一组 bind/step/finalize 实现并接入
struct db的函数指针表即可,业务 handler 无需改动。
四、Lua 版本:模块化脚本端点
Lua 版本复用同一个 techempower.conf,通过 lua 模块暴露 /lua. 前缀的脚本化路由,并提供两个 handler:
lua /lua. {
default_type = text/plain
cache period = 1h
script='''local json = require "src/json"
function handle_get_plaintext(req)
req:set_response("Hello, World!")
return nil
end
function handle_get_json(req)
req:set_headers({['Content-Type']='application/json'})
req:set_response(json.encode({message="Hello, World!"}))
return nil
end'''
}
- 访问
http://localhost:8080/lua.plaintext时,handle_get_plaintext()直接返回纯文本Hello, World!; - 访问
http://localhost:8080/lua.json时,handle_get_json()先设置 JSON Content-Type,再通过 src/json.lua 的json.encode输出{"message":"Hello, World!"}。
default_type = text/plain 声明未显式指定类型的默认 MIME;cache period = 1h 说明脚本与路由结果可缓存 1 小时。Lua JSON 编解码器采用 rxi 的 src/json.lua(版本 0.1.2),支持编码/解码对象、数组、字面量、Unicode 与代理对转义,并内置循环引用与稀疏数组检测。
五、构建与运行环境
5.1 编译参数
Makefile 展示了针对基准的激进编译优化:
CFLAGS = -mtune=native -march=native -O3 -fno-plt -flto -ffat-lto-objects -DNDEBUG \
-falign-functions=32 -malign-data=abi \
-include /lwan/build/lwan-build-config.h \
-I /lwan/src/lib \
$(shell pkg-config mariadb --cflags) \
$(shell pkg-config sqlite3 --cflags) \
$(shell pkg-config luajit --cflags)
-march=native -mtune=native:按宿主机 CPU 指令集优化(仅适合测试专用容器,不能跨机移植二进制);-flto -ffat-lto-objects:链接期优化;-fno-plt减少 PLT 间接跳转;-falign-functions=32、-malign-data=abi与-include lwan-build-config.h对齐 Lwan 的构建配置;- 链接时
-Wl,-whole-archive静态并入liblwan.a,并链接 mariadb、sqlite3、luajit、pthread、zlib。
5.2 Docker 镜像构建
lwan.dockerfile 以 ubuntu:22.04 为基础,分四步完成构建:
- 安装
git pkg-config build-essential cmake zlib1g-dev libsqlite3-dev libmariadb-dev wget libluajit-5.1-dev; - 拉取并编译 mimalloc(
-DMI_SECURE=OFF,CFLAGS="-flto -ffat-lto-objects"); - 拉取 Lwan 指定版本源码,
cmake -DCMAKE_BUILD_TYPE=Release -DUSE_ALTERNATIVE_MALLOC=mimalloc后构建lwan-static; - 执行
make clean && make编译本测试程序,产出techempower可执行文件。
运行期环境变量(MySQL 版)如下:
ENV LD_LIBRARY_PATH=/usr/local/lib:/usr/lib
ENV USE_MYSQL=1
ENV MYSQL_USER=benchmarkdbuser
ENV MYSQL_PASS=benchmarkdbpass
ENV MYSQL_DB=hello_world
ENV MYSQL_HOST=tfb-database
ENV LD_PRELOAD=/usr/local/lib/libmimalloc.so
CMD ["./techempower"]
LD_PRELOAD 预加载 mimalloc,替换系统分配器;MySQL 主机名指向测试编排网络中的 tfb-database。Lua 版 lwan-lua.dockerfile 不设置 USE_MYSQL 等变量,因此默认走 SQLite(techempower.db)。
5.3 元数据声明
benchmark_config.json 把测试声明为两类:
default(C 版):database: mysql,approach: Realistic,classification: Micro,orm: Raw,language: C;lua(Lua 版):URL 为/lua.json与/lua.plaintext,language: Lua,flavor: Lua。
config.toml 与之对应地按 [main] 与 [lua] 两组声明了相同的信息,供新版测试工具链读取。
六、测试流程:从 URL 到 wrk 压测
6.1 测试类型与验证逻辑
仓库在 toolset/test_types 下为每个测试点定义了验证器,与 Lwan 六个端点一一对应:
- json:校验
{"message":"Hello, World!"}(键值大小写不敏感,多余字段与多余字节数仅告警,见 verifications.py 的verify_helloworld_object()); - plaintext:要求响应包含
hello, world!(大小写不敏感),多余字节告警; - db:校验
id在 1–10000、randomNumber为正整数,并额外统计数据库实际执行的查询数; - query 与 cached-query:按
2 / 0 / foo / 501 / 空五组参数请求,通过verify_query_cases()校验数组长度与每个元素的键值类型; - fortune:用
FortuneHTMLParser对 HTML 做归一化后与标准串逐行 diff。
此外 verifications.py 的 verify_headers() 会强制检查 Server、Date、Content-Type 头、Content-Length/Transfer-Encoding 大小头,并验证连续两次请求的 Date 头不同(防响应缓存),Content-Type 必须匹配 application/json、text/html; charset=UTF-8 或 text/plain 的正则。
6.2 wrk 压测脚本
压测由 toolset/wrk/query.sh(Query/Cached Queries)与 toolset/wrk/pipeline.sh(Plaintext 流水线)执行,流程分三步:Primer(-d 5 -c 8 -t 8 预热连接)→ Warmup(全并发跑一个完整时长)→ 正式测量(按多个并发级别逐档压测并记录 STARTTIME/ENDTIME)。Plaintext 使用 pipeline.lua 脚本模拟请求流水线(每个连接多请求在途)。
七、验证清单:一键确认服务就绪
按 README 提供的地址,可用 curl 快速自检全部端点(前提:8080 端口服务已通过 ./techempower 启动,且按后端需要配置 MySQL 环境变量或准备 techempower.db):
curl -v http://localhost:8080/json
curl -v http://localhost:8080/plaintext
curl -v http://localhost:8080/db
curl -v "http://localhost:8080/queries?queries=5"
curl -v "http://localhost:8080/cached-queries?count=5"
curl -v http://localhost:8080/fortunes
curl -v http://localhost:8080/lua.json
curl -v http://localhost:8080/lua.plaintext
可重点观察响应头是否包含 Content-Type: application/json / text/plain / text/html; charset=UTF-8 与正确的 Content-Length,这正是 toolset/test_types/verifications.py 的通过条件。若用 Docker 运行,可用 docker build -f frameworks/C/lwan/lwan.dockerfile -t tfb-lwan frameworks/C/lwan 构建镜像,再以 -e 传入 USE_MYSQL、MYSQL_HOST 等环境变量并按 benchmark_config.json 的端口声明映射 -p 8080:8080 运行。
八、总结
Lwan 基准测试是理解"如何把一款零拷贝、协程驱动的 C Web 服务器接入标准化基准体系"的典型样例:六个 C handler 覆盖了从静态字符串(Plaintext)、声明式 JSON 编码(JSON/DB/Query)到缓存条目读取(Cached Queries)、协程模板渲染(Fortunes)的全部性能路径;数据库抽象层通过函数指针表把 MySQL/SQLite 的差异隔离在 src/database.c 内部;Lua 版本则展示了基于 LuaJIT 的模块化轻量实现。阅读时建议以 src/techempower.c 为入口,对照 techempower.conf 的路由声明与 toolset/test_types 的验证逻辑,即可完整串起"路由 → 处理 → 响应 → 验收"的整条链路。