Hical

[Hical] Router 是怎么做到 O(1) 路由匹配的？兼谈 ~40ns 的 dispatchSync 快速路径 本专栏文章：拆开 Hical · 第 2 篇 上一篇我们跟踪了一个 HTTP 请求从 socket 字节到响应序列化的全过程。走到 Router.dispatch() 这一步时我们跳过去了——现在把它展开。 一个 HTTP 框架的 Router 基本只有一件事要做：给定 method + path，找到对应的 handler。听起来简单，但"怎么找"的差异可以把延迟拉开一个数量级。 1. 三种路由、三种策略 Hical 的 Router 支持三种路由： 1 2 3 静态路由: GET /api/users → hash map O(1) 参数路由: GET /api/users/{id} → per-method vector 线性匹配 通配符路由: GET /static/*path → 优先级最低，兜底匹配 匹配优先级：静态 > 参数 > 通配符。为什么是这个顺序？静态路由一 hash 命中就返回，参数路由需要逐个匹配，通配符是兜底的——先试最快的。 2. 静态路由：透明哈希消除 string_view→string 转换 2.1 问题 静态路由的 key 是 method + path 的组合。如果存在 unordered_map 里： ...

[Hical] Vyukov MPSC 无锁队列在 HTTP 服务器上的实战：GenericConnection 的写路径 本专栏文章：拆开 Hical · 第 4 篇 前面三篇都在 HTTP 层面打转——请求怎么解析、路由怎么匹配、中间件怎么执行。这一篇沉到网络层，看一个具体的问题：多个协程想往同一个 socket 写数据时，怎么不加锁？ 答案藏在 GenericConnection 的 Vyukov MPSC 无锁队列里。 1. 问题：多个协程同时往一个连接上写 先搞清楚为什么会有这个问题。HTTP/2 和 WebSocket 都允许在一个 TCP 连接上并发地处理多个"流"： 1 2 3 线程 A（协程处理 WebSocket frame）──→ 想往 socket 写数据 线程 B（协程处理心跳 ping） ──→ 也想往 socket 写数据 线程 C（IO 线程正在写上一批数据） ──→ socket 只能同时一个写操作 传统的做法是 std::mutex + std::queue。但这里有三个痛点： 生产者多、消费者一个：多个协程往队列里塞数据，只有一个写协程取出来发给 socket mutex 竞争：每秒几十万次 send → 几十万次 mutex lock/unlock → 内核态的 futex 开销 队列长度短：大多数时候队列深度 < 5，争锁的开销比实际写数据还大 2. Vyukov MPSC 队列：核心原理 Dmitry Vyukov 的 MPSC 队列专门为"多生产者、单消费者"场景设计。先直观理解——想象排队买票： ...

[Hical] 一个 HTTP 请求在 Hical 里经历了什么？从 socket 字节到路由分发 本专栏文章：拆开 Hical · 第 1 篇 用过 Web 框架的人很多，知道"一个请求怎么从 socket 字节变成 handler 参数"的人很少。大部分框架把这层封装得严严实实，你只要写 app.get("/", handler) 就行。 但这篇文章要干相反的事——把 Hical 的整个请求处理链路扒开看。读完你能回答：请求头为什么零堆分配、响应头怎么一次 async_write 发出去、ReadBufferPool 为什么是请求级 borrow 而不是连接级持有。 1. 大图：一个请求的完整旅程 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 socket 上来了字节 │ ▼ readBuf = ReadBufferPool::acquire() ← 借一块 8KB 缓冲 │ ▼ picohttpparser 解析 → phr_header[64] ← 请求头解析到栈数组 │ ▼ 构造 NativeRequest (string_view) ← 零拷贝,指针指到 readBuf │ ▼ Router::dispatch(req) ──→ handler 协程 ← 你的业务代码 │ ▼ NativeResponse::serializeHeadTo(buf) ← 序列化到栈上 512 字节 │ ▼ async_write(socket, buf) ← 一次异步写 │ ▼ readBuf 还给 ReadBufferPool::return_() ← 归还 8KB 缓冲 下面每一步都拆开讲"为什么这样设计"。 ...

[Hical] 一套 API，两套实现：C++26 反射双轨是怎么设计的 本专栏文章：拆开 Hical · 第 7 篇（完结篇） 这是系列的最后一篇，也是最"前沿"的一篇——C++26 反射在中文技术社区几乎没有实战文章，因为它太新了。Hical 是目前全网唯二（或许唯一）在 open-source 项目中用 C++26 反射的生产级框架。 但 Hical 等不到所有编译器都支持 P2996——它必须兼容 GCC 14、Clang 20、MSVC 2022。所以它做了一套双轨架构：C++26 原生反射和 C++20 宏 fallback 提供相同的用户 API。 1. 问题：你要 JSON 序列化，但不想每个 struct 手写 to_json/from_json 假设你定义了一个 DTO： 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 struct User { std::string name; int age; std::string email; }; // 你想要的： auto json = hical::meta::toJson(user); // → {"name":"张三","age":25,"email":"z3@example.com"} auto user2 = hical::meta::fromJson<User>(json); // 你不想要的： boost::json::object to_json(const User& u) { boost::json::object obj; obj["name"] = u.name; obj["age"] = u.age; obj["email"] = u.email; return obj; } // ↑ 每个 DTO 手写一遍，字段增删时忘了更新序列化 → 静默 bug 传统方案（nlohmann/json）靠宏来自动生成，但需要每个类型手动注册。Hical 的做法是让框架自动发现结构体的字段。 ...

[Hical] 中间件洋葱模型怎么做到"连续 N 个同步中间件只分配一次协程帧"？ 本专栏文章：拆开 Hical · 第 3 篇 上一篇文章讲了 Router 的 dispatchSync——当 handler 是同步的，跳过协程帧分配。同样的思路也应用在中间件上。 大多数框架的中间件是"一层一个协程"——3 个中间件 = 3 个协程帧 = 3 次堆分配。但 Hical 问了一个问题：如果 N 个中间件都是同步的（不用 co_await），为什么不能把它们合并成一个协程帧？ 答案是：可以。而且 Hical 实现了。 1. 先理解洋葱模型 1.1 标准中间件的三个角色 一个 HTTP 请求经过中间件管道时，有三种类型的操作： 1 2 3 请求进来 ──→ before1 ──→ before2 ──→ handler ──→ after2 ──→ after1 ──→ 响应出去 ↑ ↑ ↑ ↑ 前置拦截 前置处理 后置修改 后置处理 Before：在 handler 之前执行。可以拦截请求、直接返回响应（如认证失败返回 401） Handler：核心业务逻辑 After：在 handler 之后执行。可以修改响应头（如加安全头、压缩 body） 1.2 传统方案：一层一个协程 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 // 全异步中间件链：N 个中间件 = N 个协程 lambda MiddlewareNext makeChain(asyncHandler1, asyncHandler2, asyncHandler3, finalHandler) { // 从内到外构建 auto inner = [h3, finalHandler](req) -> Awaitable<HttpResponse> { co_return co_await h3(req, finalHandler); }; auto middle = [h2, inner](req) -> Awaitable<HttpResponse> { co_return co_await h2(req, inner); }; auto outer = [h1, middle](req) -> Awaitable<HttpResponse> { co_return co_await h1(req, middle); }; return outer; } 3 个协程 lambda → 3 个协程帧 → 3 次堆分配。 ...

[Hical] 为什么不用每个连接一个 timer 协程？IdleScanner 的集中式空闲扫描设计 本专栏文章：拆开 Hical · 第 5 篇 本篇讲一个大多数 HTTP 框架都有的、但很少被拿出来单独聊的功能：空闲连接超时断开。 功能本身不复杂——如果一个 keep-alive 连接 60 秒没有新请求，就关掉它。但"怎么实现"有两种完全不同的路线，方案选择直接影响内存和 CPU 成本。 1. 方案 A：每连接一个 timer 协程（大多数框架的做法） 1 2 3 4 5 6 7 8 9 为每个连接创建一个 steady_timer，然后 co_await 在它上面： co_spawn(io_context, [self]() -> Awaitable<void> { steady_timer timer(60s); auto result = co_await (timer.async_wait() || socket.async_read(...)); // 如果 timer 先到 → 超时关闭 // 如果 socket 先到 → 取消 timer，处理请求 }); 问题在哪？ ...

[Hical] 你的协程内存去哪里了？三层 PMR 内存池设计 本专栏文章：拆开 Hical · 第 6 篇 前几篇我们都在聊"怎么做"，这篇聊"内存去哪了"。 HTTP 服务器处理一个请求时，至少有这些内存分配：读缓冲（8KB）、请求头解析、URL decode、body 字符串、JSON 对象、响应序列化缓冲、中间件属性注入。每秒 10 万请求 → 每秒数百万次的 malloc/free。 C++17 的 PMR（多态内存资源）给了我们一个机会——换掉默认的 new/delete，用分层的分配器策略。Hical 把这个机会用到了极致。 1. PMR 的最简入门 如果你没用过 PMR，这里 30 秒快速理解： 1 2 3 4 5 6 7 8 // 传统方式：全局 new/delete（不知道这内存在哪、持续多久） std::string s = "hello"; // malloc → free // PMR 方式：你指定分配器的"上游" char buf[1024]; // 栈上的一块内存 std::pmr::monotonic_buffer_resource pool(buf, sizeof(buf)); std::pmr::string s("hello", &pool); // 分配在栈上的 buf 里！ // pool 析构 → buf 回收 → 不需要 free！ PMR 的核心思想：分离"我要内存"和"从哪拿内存"。 不同的分配器适合不同的场景： ...

性能优化思路：从测量到代码的五层递进方法论 优化不靠直觉，靠数据。这篇文章是我在给 Hical 做性能优化时沉淀下来的一套方法论：从"用 profiler 找到真正的瓶颈"，到架构选型、系统间交互、数据结构、再到最后的代码级微优化，一共五层，层层递进。每一层都有对应的工具、实战案例和"什么时候别优化"的提醒。看完你会发现，大部分性能问题根本轮不到写代码，先想清楚在哪一层出手，比埋头优化重要得多。 目录 第零层：测量——找到真正的瓶颈 性能优化五层模型 架构级性能优化 （子）系统间性能优化 数据结构与算法性能优化 代码级性能优化 性能回归检测：优化完了怎么守住 第零层：测量——找到真正的瓶颈 优化不是凭直觉猜，是数据驱动的工程决策。没有 profiling 数据就动手，相当于在黑屋子里开枪——打中算运气，打不中浪费子弹。我在 Hical 上踩过的第一个坑就是猜错了方向：光凭代码感觉觉得是协程帧太多，结果 perf 一跑，14.5% 的 CPU 其实耗在调度器上。所以，先量，再动。 工具链：每种工具回答一个问题 工具 回答什么问题 Hical 实战 perf record + 火焰图 CPU 时间花在哪了 perf record -g -F 99 → docker 内 10s wrk strace -c 系统调用频次和时间占比 epoll_ctl 31351 次占 25.92% GTest 性能用例 函数级性能断言 test_router_perf.cpp，100K 次 dispatch 计时 wrk / wrk2 端到端吞吐和延迟分布 wrk -c100 -t4 -d30s heaptrack / valgrind massif 内存分配热点 找意外的大分配 perf stat -d IPC、分支预测率、cache miss 看整体健康度 火焰图怎么看 拿 Hical 实际火焰图数据来说（docker 内 wrk -c10000 -d10s，perf record -g -F 99）： ...

写在前面 两万多行代码写下来，我把踩过的坑和想明白的事都总结在这了。不讲概念，只聊实战中每个设计"为什么这么做"。 搞 C++ Web 框架这事，从第一行代码到现在，说实话走了不少弯路。今天不聊怎么用，聊聊底层那些设计决策——为什么要这么写，当时碰到了什么问题，怎么一步步改成现在这样的。 一、编译期就把活干完 1. 一套模板搞定 TCP 和 SSL 最早我是分别写了 TcpConnection 和 SslConnection 两个类，代码重复率 80%以上，改一个 bug 要改两遍。后来换成 GenericConnection<SocketType>，内部用 if constexpr 做分支： 1 2 3 if constexpr (hIsSslStream<SocketType>) { co_await stream_.async_handshake(...); } 编译器直接在编译期把不匹配的分支丢掉——纯 TCP 的二进制里一个字节的 SSL 代码都没有。维护成本砍半，运行时零开销。这不是什么高深技巧，但真正落地用好的项目不多。 2. 用不到的模块，连编译都不参与 数据库、OpenAPI 这些模块，不是每个项目都用得上。我用 CMake option + 宏隔离的方式处理： 1 option(HICAL_WITH_DATABASE "Enable DB middleware" OFF) 代码里所有 DB 相关的逻辑都包在 #ifdef HICAL_HAS_DATABASE 里。你不开这个 option，这些代码连语法检查都不走，更别说占二进制体积了。比运行时搞个 feature flag 干净太多——运行时 flag 意味着代码虽然不执行，但死代码还在那占着 icache。 3. TRACE 日志：Release 下彻底消失 开发时满屏 TRACE 日志方便调试，但生产环境绝对不能有这些开销。我的做法是 NDEBUG 下 HICAL_LOG_TRACE 直接展开成 ((void)0)——注意，这不是"判断级别后跳过"，而是连参数求值的代码都不存在于二进制中。 ...

写在前面 你有没有想过，一个高并发网络服务器在同时给几千个客户端发消息时，底层到底在忙什么？ 最直觉的做法是加把锁——谁要发消息就抢锁、写 socket、放锁。但问题来了：如果 1000 个协程同时要给同一个连接发数据，它们就得排队等这把锁。锁竞争带来的上下文切换、cache 失效，会把性能拖进泥潭。 Hical 框架的解法很酷：用一个 MPSC（多生产者单消费者）无锁队列 做缓冲，配合一个协程写循环做消费。发消息的线程只管往队列里扔节点（wait-free，永远不阻塞），写循环协程在 IO 线程上批量取出、合并发送。 这篇文章会带你从零搞懂这个设计。不需要你有无锁编程的基础，但最好知道 C++ 的 atomic、shared_ptr 和"什么是协程"大概是怎么回事。 一、先搞清楚问题：为什么普通的锁不行？ 1.1 一个典型场景 假设你写了个聊天服务器。用户 A 发了条群消息，服务器要转发给群里 200 个在线用户。这意味着： 1 用户A的消息 → 广播逻辑 → 同时调用 200 个连接的 send() 如果 send() 内部用 mutex 保护写操作： 1 2 3 4 5 6 7 8 9 10 11 // 朴素实现（有严重性能问题） void Connection::send(std::string data) { std::lock_guard lock(writeMutex_); // 200个协程在这里排队 writeBuffer_.append(data); if (!writing_) { writing_ = true; doWrite(); // 触发实际的 socket 写入 } } 问题出在哪？ ...