1. 本功能主要作用和特点
F-Stack 的 LD_PRELOAD 模块（libff_syscall.so）从 2023-05 初版提交到现在演进三年了，这篇讲的是 2026 年上半年给它做的无锁环形队列改造（FF_USE_RING_IPC），顺带把这三年从初版到现在的优化和修改一起捋一遍。
F-Stack 的标准接入方式是改代码：应用调 ff_* 前缀 API + ff_run() 主循环，代码侵入大。为了降低存量应用的迁移门槛，2023 年社区在 dev 分支提交了 adapter/syscall 目录（commit 8f5f1dfbb，2023-05-03），提供 libff_syscall.so 动态库，通过 LD_PRELOAD 劫持 Linux socket 系统调用转发给 fstack 实例进程处理，应用零代码修改即可接入。初版发布时官方定位很克制：「目前功能尚不完善，仅供测试使用」。
三年后的今天，这个模块已经支持 fork、accept4、_FORTIFY_SOURCE 包装函数、epoll polling 模式，并且把 APP 与 fstack 之间的 IPC 从信号量三层同步演进到了 DPDK 无锁 rte_ring 双环 SPSC。几个关键点：
- 免改代码接入：socket/bind/connect/read/write/epoll/kevent/select 全部劫持，存量应用（Nginx、netperf 等）零代码修改直接跑在 F-Stack 上
- 双环 SPSC：FF_USE_RING_IPC 用 rte_ring 单生产者单消费者模式替换 sem_wait/sem_post，消灭全局锁和 O(n) 遍历
- 诚实收敛：ring 改造经过 v1~v3.7 共七轮实测迭代，最终结论不是”ring 全面胜利”，而是”ring 在 LD_PRELOAD + FF_MULTI_SC 场景下没有性能优势，生产推荐 sem”——这是这篇最想说的：优化要有对照、有证伪、敢于否定自己
2. 本功能的主要适用场景
2.1 存量应用免改代码接入 F-Stack
这是 LD_PRELOAD 模块的根本定位。历史 issue 档案里，官方对”现有多线程/多进程/Go/netperf 类应用怎么移植”的回答，推荐方案第一条几乎都是它：不用改源码，先起 fstack 实例进程，再 LD_PRELOAD 拉起应用。适配的接口面包括 socket 全家桶、epoll 全家桶、kqueue/kevent、select、fork，以及 glibc _FORTIFY_SOURCE 编译的 recv_chk/read_chk/__recvfrom_chk 包装函数。
2.2 Nginx 免改代码集成
Nginx 官方默认携带 1.16.1，经 LD_PRELOAD 接入无需改任何代码，需要同时开 FF_KERNEL_EVENT + FF_MULTI_SC 两个编译开关，配置上 multi_accept on、listen reuseport。不适用场景明确：多实例做客户端（反向代理）暂不支持，需要像社区 @铁皮大爷 那样在 hook 层加 RSS 对称 hash 选实例。
2.3 fork 多进程模型应用
2025-05 的 fork 支持（commit 4891fabf5，PR #887）之后，每个 fork 出来的进程都拥有独立的 FreeBSD struct thread，行为对标 Linux 内核 fork。配合 FF_MULTI_SC，Nginx master fork worker 的经典模型可以跑通。
2.4 不太适合的场景
- 追求极致性能：每组应用实例要 2 个 CPU 核（1 个 fstack + 1 个 APP），CPU 几乎翻倍，官方原话”性价比不高”。要极致性能还是直接改代码用标准 F-Stack
- 8 核以上的短连接场景：LD_PRELOAD 性能不如标准 F-Stack，受 APP 与 fstack 匹配度影响
3. 本功能的架构特征
3.1 整体拓扑
核心通信载体是 DPDK 大页共享内存上的 ff_so_context（简称 sc）。APP 把要执行的 socket 操作填进 sc，fstack 实例主循环处理并把结果写回。fstack 实例和 APP 建议跑在同 NUMA 节点的不同物理核上。
3.2 初版同步机制：信号量三层同步
初版（2023-05 ~ 2026-04 默认路径）sc 的同步靠三层机制：
| 层 | 机制 | 位置 |
|---|---|---|
| 状态机 | FF_SC_IDLE → FF_SC_REQ → FF_SC_REP → FF_SC_IDLE | ff_socket_ops.h |
| 互斥锁 | rte_spinlock_t lock（sc 级 + zone 级全局锁） | ff_socket_ops.h |
| 信号量 | sem_t wait_sem（POSIX 跨进程信号量，futex 实现） | ff_socket_ops.h |
一次 socket 调用的往返流程：
3.3 新同步机制：双 Ring SPSC
2026-04-09 的 commit d2b71ac89 引入 FF_USE_RING_IPC：用 DPDK rte_ring（SPSC 模式）替代 sem。请求环 APP 生产 fstack 消费，响应环 fstack 生产 APP 消费：
状态语义的等价迁移：sc 在 req_ring 中 = 旧 FF_SC_REQ；在 rsp_ring 中 = 旧 FF_SC_REP；两个 ring 都不在 = 空闲。spinlock 和状态机转换不再参与同步逻辑。
3.4 为什么选 rte_ring
spec 文档（SPEC-002）里给了四条理由：F-Stack 本身大量使用 rte_ring（dispatch_ring、msg_ring），零学习成本；DPDK 原生 SPSC 无需自研无锁算法；Hugepage + rte_memzone 已验证跨进程可见；比 VPP 的 svm_msg_q 更简单。APP 与 fstack 实例 1:1 绑定，天然满足 SPSC 约束。
4. 具体做了哪些改造、遇到了哪些问题、怎么解决的
后续比较枯燥，不需要深入研究实现过程的可以跳过本节，直接看第 5 节怎么用。
4.1 初版遗留问题清单（ring 改造的动机）
初版的信号量机制在 spec 文档（SPEC-001）里被列了 5 条性能瓶颈：
- 内核态切换：sem_wait/sem_post 走 futex 系统调用，每次 100-200ns，epoll_wait 短超时场景被放大
- 超时精度差：sem_timedwait 用 CLOCK_REALTIME，受 NTP 调时影响，唤醒粒度受调度器 tick（1-4ms）限制；还有个竞态：超时返回后 fstack 才 sem_post，导致下次 sem_timedwait 立即返回读到过期结果
- O(n) 遍历：ff_handle_each_context 每轮遍历全部 32 个 sc 的 status 字段，绝大多数处于 IDLE 也要脏读
- alarm_event_sem 补偿机制脆弱：5 个示例程序里只有 1 个真正调用它，其余全注释掉了
- 模式分裂：信号量模式（低 CPU 高延迟）和轮询模式 FF_PRELOAD_POLLING_MODE（低延迟 100% CPU）通过编译宏二选一，运行时不可切换
4.2 三年中间演进（2023-08 ~ 2026-03，ring 之前的沉淀）
ring 不是凭空出现的，中间这三年社区补了不少坑，按时间排：
| 时间 | commit | 内容 |
|---|---|---|
| 2023-08 | 0ee517ed0 | 修 Ubuntu 22.04 / kernel 5.19 / gcc 11.4 编译错误（#777），pre-C99 声明问题 |
| 2025-03 | 5de6ec6d2 | 新增 epoll polling 模式，改善 RTT 敏感场景延迟 |
| 2025-03 | 3c21f2253 | 修 ff_hook_recvfrom sh_fromlen 未初始化导致返回 -1（PR #872） |
| 2025-03 | e3766b423 | accept4 支持 + ff_socket 支持 LINUX_SOCK_CLOEXEC/NONBLOCK |
| 2025-05 | 111816e29 | hook recv_chk/read_chk/_recvfrom_chk，FORTIFY_SOURCE 编译的应用可用 |
| 2025-05 | 4891fabf5 | 完整 fork 支持（PR #887），每个进程独立 FreeBSD struct thread |
| 2026-03 | b36ce995d | 修 ioctl 可变参数签名冲突编译错误（#942，PR #1048） |
其中 ioctl 那个坑值得展开一句：glibc 里 ioctl(2) 是可变参数签名 int ioctl(int, unsigned long, …)，而 ff_declare_syscalls.h 按定参注册，新工具链一编就炸。这类”glibc 签名 vs hook 声明”的不一致，是 LD_PRELOAD 这类方案的天生雷区，只能靠社区逐一踩坑修复。
4.3 ring 初版落地（2026-04）
2026-03-27 先产出了 4 篇 spec（需求/架构/接口/测试），审核通过后 2026-04-09 一次性提交 d2b71ac89：双 rte_ring SPSC、FF_USE_RING_IPC 编译开关、三种等待策略（busy-poll/yield-poll/eventfd，默认 yield-poll）、rte_rdtsc 替代 sem_timedwait 做微秒级超时、alarm_event_sem 改为 sentinel 入队。设计上严格走”编译宏切换 + 旧路径不动”，可渐进迁移。
4.4 ring 性能优化攻坚战（2026-05，七轮迭代的教训全集）
初版 ring 一上实测就出问题：短连接 QPS 9.1w，比 sem 基线 10.5w 低 12.4%。于是有了 v1~v3.7 的七轮迭代，这段过程是这篇最有价值的部分——不是”怎么修好的”，而是”怎么一步步证伪自己的错误假设”。
第一轮假设（H10/H11，v1）：只读了 ff_socket_ops.c 的 ring 分支，下结论”sem 模式没有 30us drain 强制空轮询”。被证伪——对照 else 分支发现 sem 同样有 if (diff_tsc >= drain_tsc) break 循环。教训：单边代码分析，不对照另一分支就下结论。
第二轮假设（H15，v2）：基于”sem 有 nb_handled 旁路而 ring 没有”，假设 ring 的 dequeue burst 跨核读 prod.tail 导致 LLC miss 暴增。perf stat 实测证伪：ring 的 LLC miss 反而比 sem 少 23%（6.8K/s 量级，不构成瓶颈）。教训：没先验证可证伪的物理量就把假设写进文档。
第三轮（v3.1）：把”每 256 次 PAUSE 触发 sched_yield”按纯算术推成次因（H18），实测三组配置（yield 阈值 0xFF/0x1FFF/busy-poll）QPS 全部 9.2w，voluntary_ctxt_switches 增长约等于 0——spin_count 是局部变量，短连接场景单次 wait 根本到不了 256 次。教训：频率类估算先做 10 秒采样，别做 30 分钟的弯路。
第四轮（v3.2）：perf top callgraph 锁定真因——ff_ring_process_requests Self 15.44%（每次主循环 spin 都走完整 dequeue burst 函数调用栈，即使 nb=0）+ ff_ring_send_response Self 3.33%（每次响应写 rsp_ring->prod.tail，触发 APP 核 cache invalidate）。同期还证伪了自己两条假设：H21 把 wrk 延迟差 +190us 当成单 syscall 开销（差 3 个数量级，真因是 CPU 占用挤压）；H24 在 perf 已给明确证据后还发散”跨 NUMA”环境假设（同环境对照实验的唯一变量是 IPC 实现本身）。
方案 C 的失败（v3.3，H25）：想用 atomic pending_count 旁路复刻 sem 的 nb_handled 快速跳过，结果 QPS 反劣化 4%（9.1w → 8.7w）。根因：APP 每次 syscall 多写 atomic 2-4 次，跨核 cache 乒乓比省掉的 dequeue 路径更贵。这个方案当天实施当天回退，代码随后彻底删除（f344d945f）。教训写进了文档的”对称评估表”方法论：任何优化必须同时列出”消除的物理量”和”新引入的物理量”，后者数量级必须明显小于前者才允许实施。
D2 的成功（v3.4，+9.7%）：放弃响应 ring，fstack 处理完直接写 sc->completion（sc cache line 0 上本来就预留的字段），APP 端 spin completion 标志。写频率与 sem 基线完全一致，零新跨核字段。QPS 9.1w → 10.0w，ff_ring_send_response 从 perf top 消失。
D5（+1.3%）：ff_ring_process_requests 改为先 rte_ring_empty() 内联快速空判断，空时不展开函数调用栈。Self 18.98% → 4.53%，但 QPS 只涨 1.3%——省下的 CPU 立刻被 main loop spin 填满。这是关键的洞察起点：fstack lcore 100% CPU + 30us drain 设计下，IPC 省下的 CPU 不会 1:1 变 QPS。
D6（+0.9%）：ff_handle_socket_ops_ring 标 static inline，主循环直接函数名调用（去函数指针），与 sem 模式的 ff_handle_socket_ops 对齐。10.13w → 10.22w。
最终收敛：ring 单 worker QPS 10.22w，距 sem 的 10.5w 还差 2.7%。perf top 显示两边 main loop CPU 占比已完全一致（50.13% vs 50.41%），剩余差距来自 rte_ring_sc_dequeue_burst 的 acquire fence 和 ring 元数据维护——sem 的 dirty read 是 plain load 无 fence。这是 SPSC 架构的物理代价，单 worker 单 lcore 场景不可消除。
4.5 意外收获：sem 路径的启动饥饿修复
ring 攻坚过程中顺带修了一个老问题（8125beece，2026-05-25）。现象：sem 模式 + FF_MULTI_SC + config.ini 里 idle_sleep=0 时，多 worker 启动、还没任何流量，nginx 第二个 worker 卡死在 ff_attach_so_context 的 rte_spinlock_lock，gdb 堆栈和死锁一模一样。
但它是饥饿不是死锁：fstack secondary lcore 专核紧自旋，每 50-100us 释锁一次但释锁窗口 <<1us（idle_sleep=0 不让 CPU），nginx worker 是普通调度进程，cmpxchg 永远慢一拍，命中窗口概率趋近 0。修复只改了 13+/5- 行：进入 while 前快照 tmp（in-use sc 数），unlikely(!tmp) 时 unlock → pause → lock 让出窗口，有负载时零影响。最优补丁是”条件性让出”不是”无条件让出”。
【注1】这条饥饿现象同时说明：跨进程自旋锁竞争里，专核 DPDK lcore 永远胜过普通调度进程，这是物理机制不是代码 bug。能用配置（idle_sleep 改 1）消除的现象，根因 99% 是时间窗/调度类问题。
4.6 多核长连接实测：最终证伪 ring 的设计目标（v3.5~v3.7）
单 worker 收敛后转向多核对照。结果比预想残酷：
| 场景 | 结论 |
|---|---|
| 多核短连接（1/2/4 核） | ring ≡ sem（差距 -1.9%/0%/-0.3%，噪声范围） |
| 多核长连接（1/2/4 核） | ring 稳定劣于 sem 2.4%~4.5%，方向一致且大于噪声 |
长连接把 ring 的劣势放大而不是抵消：FF_MULTI_SC 下每个 fstack lcore 与 nginx worker 是 1:1 同 zone，sem 的 zone 锁是 fstack lcore 独占持有（cache line 一直 exclusive，近乎零成本），而 ring 每次 dequeue 都要 acquire fence 同步内存系统，高 QPS 下线性放大。当初”长连接下 sem 全程持锁压力升高、ring lock-free 优势将显现”的预测被彻底证伪。
v3.7 终版结论（2026-05-25 晚）：
- 性能层面：ring 在任何已测场景下均无 net win，sem 仍是 LD_PRELOAD + FF_MULTI_SC 的最优配置
- 鲁棒性层面：ring 主循环 lock-free 的理论价值（启动饥饿免疫）已被 8125beece 在 sem 源头修复
- 架构层面：ring 代码保留（FF_USE_RING_IPC + D2/D5/D6 作为默认行为，c62d56a3b），作为”多线程同进程共享 sc”和”多进程间共享 sc（worker 数 > fstack 实例数）”的未来预留能力，当前 fork 多进程场景默认不启用
【注2】这个收敛结论值得反复看：一个设计良好、实现了完整 spec、优化了七轮的方案，最终被对照实验判定”不如老方案”。如果只有实现没有对照基线，这个结论永远不会出现。性能优化工作里，”对照组先于优化”比”数据先于理论”更值钱。
4.7 ring 之后还在继续（2026-05 ~ 08）
收敛之后模块没有停：README 全面刷新（bc7c380b2，2026-05-26）；ff_hook_bind 增加 addrlen 边界检查（8762e05c1，2026-06-08，#1068）；新增 UDP echo server 示例（2215dc4f2，2026-08-07，#1063）。
5. 如何使用、如何配置、使用效果
5.1 编译
export FF_PATH=/data/f-stack
export PKG_CONFIG_PATH=/usr/lib64/pkgconfig:/usr/local/lib64/pkgconfig:/usr/lib/pkgconfig
cd /data/f-stack/adapter/syscall
# Nginx 无缝接入：同时开 FF_KERNEL_EVENT + FF_MULTI_SC
export FF_KERNEL_EVENT=1
export FF_MULTI_SC=1
# 可选：启用无锁 ring IPC（默认关闭，见 5.4 推荐配置）
#export FF_USE_RING_IPC=1
make clean; make all
编译产物：fstack（实例程序）、libff_syscall.so（劫持库）、5 个 helloworld 示例 + main_stack_udp 示例。FF_USE_RING_IPC 与 FF_PRELOAD_POLLING_MODE 互斥，Makefile 有编译期检查，同时定义直接报错。
5.2 运行
# 1. 先起 fstack 实例（lcore_mask 等配置同标准 F-Stack）
bash ./start.sh -b adapter/syscall/fstack
# 2. 再以 LD_PRELOAD 方式拉起应用
export LD_PRELOAD=/data/f-stack/adapter/syscall/libff_syscall.so
export FF_NB_FSTACK_INSTANCE=4 # 与 nginx worker 数 1:1
/usr/local/nginx/sbin/nginx
运行时环境变量：FF_NB_FSTACK_INSTANCE（实例数，默认 1）、FF_INITIAL_LCORE_ID（起始核，默认 0x4）、FF_PROC_ID（进程号，配合 CPU 绑定）。应用能自己绑核的（如 nginx worker_cpu_affinity）优先自己绑。
5.3 Nginx 配置要点（免改代码，但要调配置）
worker_processes 4;
worker_cpu_affinity 10000 100000 1000000 10000000;
events {
worker_connections 1024;
multi_accept on; # F-Stack epoll 是 kqueue 封装，必须开
use epoll;
}
http {
access_log off;
sendfile off; # 用 F-Stack 必须关
keepalive_timeout 0;
server {
listen 80 reuseport; # 每个 fd 对接不同 fstack 实例的 sc
location / {
return 200 "0123456789abcdefghijklmnopqrstuvwxyz";
}
}
}
注意 kern.maxfiles 不应大于 65536（保证 epoll fd 到内核 fd 的正确映射）。
5.4 使用效果与推荐配置
性能数据（E5-2670 v3 双路 / 10G X540，v3.7 终版实测）：
| 场景 | Sem | Ring | 差距 |
|---|---|---|---|
| 多核短连接 1/2/4 核（万 QPS） | 10.4 / 20.8 / 35.9 | 10.2 / 20.8 / 35.8 | ≤2%（噪声） |
| 多核长连接 1/2/4 核（万 QPS） | 33.3 / 65.9 / 130.5 | 31.8 / 64.3 / 127.0 | -2.4%~-4.5% |
| 单 worker 优化轨迹 | — | 9.1w → 10.22w（+12.3%） | 距 sem 10.5w 差 2.7% |
生产推荐配置（2026-05-25 终版）：
# LD_PRELOAD + nginx 多 worker 推荐（默认，不开 ring）
make FF_KERNEL_EVENT=1 FF_MULTI_SC=1
# config.ini: idle_sleep = 0（8125beece 之后安全），pkt_tx_delay = 50（短连接）/ 100（长连接）
ring 路径仅在以下任一情况启用：单进程内多线程需共享 sc；多进程间共享 sc（worker 数 > fstack 实例数）；或者接受 -2.4%~-4.5% 的性能损失换取主循环 lock-free 设计。
对 F-Stack 使用者的整体建议：LD_PRELOAD 是”少改代码”的折中，不是”性能最优”的路径。要追求极致还是标准 F-Stack 改代码接入；只想快速迁移存量应用，LD_PRELOAD + sem 默认配置就够用，ring 等未来多对多共享场景再启。
6. 延伸阅读：
- ring 需求/架构/接口/测试 spec：docs/ld_preload_ring_spec/zh_cn/01~04
- v3.7 终版性能分析（七轮迭代完整复盘）：docs/ld_preload_ring_spec/zh_cn/ring_ipc_perf_offline_analysis.md
- 模块官方文档（含 2023-05 ~ 2026-05 全部 feature updates）：adapter/syscall/README.md
- 初版公众号介绍（2023-05）：https://mp.weixin.qq.com/s/hmxCEu0kOzp5X5TEB7r3OQ
- 三层架构文档：docs/zh_cn/01-LAYER1-ARCHITECTURE.md
- 知识图谱：docs/zh_cn/KNOWLEDGE_GRAPH_WIKI.md
- 历史 issue 档案：docs/zh_cn/f-stack-issue-ana.md
