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 的核心思想：分离"我要内存"和"从哪拿内存"。 不同的分配器适合不同的场景： ...