Skip to content
Projects

Hical61/Hical has 63 GitHub stars and 13 forks. GitHot measured 0 stars in 24 hours, +1 in 7 days, and +1 in 15 days. Last checked 2026-11-16 00:16 UTC. Last push 2026-11-03.

How these counts are measured

What you can do

  • Native network stack — picohttpparser zero-copy HTTP parsing + self-developed WebSocket (RFC 6455), zero heap allocation
  • C++26 Reflection — Automatic route registration + JSON serialization; seamless C++20 macro fallback
  • Coroutine async I/O — asio::awaitable<T> + co_await, sync fast path with zero coroutine frame overhead
  • PMR three-tier pool — Global synchronized / thread-local lock-free pool for connection-level allocations; request path uses ReadBufferPool + stack arrays + FixedBuffer for actual zero heap allocation

Measured star growth

in 24h
0
in 7 days
+1
in 15 days
+1
in 1 month
Collecting history

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Modern C++20 web framework with optional C++26 reflection and PMR memory pools — built on Boost.Asio, coroutines, high performance

Web & Apps

README.md

Original

hical

CI License: MIT C++ Standard Platform Boost GitHub release GitHub stars PRs Welcome HttpArena H/1.1 HttpArena WebSocket

📖 Upgrade/migration guide → CHANGELOG
💬 Questions or ideas → Discussion

Hical is a modern C++20/26 high-performance web framework built on Boost.Asio with a native HTTP/WebSocket stack (picohttpparser + self-developed WebSocket), leveraging C++26 reflection and PMR memory pooling for maximum throughput.

Status: Stable — production-ready, follows Semantic Versioning.

HTTP/2 双端支持仍为候选实现,正在完成最终验收;默认构建和默认客户端继续使用 HTTP/1.1。接入方式与范围见 HTTP/2 使用指南。

English | 简体中文

Why Hical?

Every number below is from HttpArena — an independent benchmark that runs each framework on the same machine, in the same round, against the same load generator. No vendor hardware, no hand-picked scenarios.

Throughput & concurrency — all profiles

Category Profile Conns Throughput Avg latency p99 CPU Memory
Connection baseline 4,096 3,202,325 req/s 1.28 ms 1.80 ms 6288.6% 133 MiB
pipelined 4,096 18,365,348 req/s 3.57 ms 5.72 ms 6626.4% 148 MiB
limited-conn 4,096 2,385,743 req/s 1.70 ms 25.00 ms 6185.3% 73 MiB
Concurrency async (10 ms wait) 32,000 1,920,543 req/s 16.52 ms 19.00 ms 6428.7% 900 MiB
Workload json-comp 4,096 395,704 req/s 10.18 ms 235.90 ms 6284.4% 78 MiB
json-comp 16,384 381,469 req/s 39.04 ms 997.90 ms 6530.0% 214 MiB
json-tls 4,096 895,583 req/s 4.56 ms 63.82 ms 6731.7% 518 MiB
8gbit (stream echo) 512 49,350 req/s 103.9 µs 147.0 µs 287.4% 107 MiB
WebSocket echo-ws 512 3,460,015 msg/s 147 µs 296 µs 6313.2% 47 MiB
echo-ws 4,096 3,503,912 msg/s 1.17 ms 1.75 ms 6608.7% 158 MiB
echo-ws 16,384 3,062,490 msg/s 5.31 ms 6.48 ms 6591.1% 533 MiB
echo-ws-pipeline 512 37,055,516 msg/s 220 µs 384 µs 6620.9% 47 MiB
echo-ws-pipeline 4,096 36,420,220 msg/s 1.80 ms 2.19 ms 6740.8% 159 MiB
echo-ws-pipeline 16,384 32,132,291 msg/s 8.12 ms 9.39 ms 6718.7% 533 MiB
echo-ws-limited 512 1,866,258 msg/s 185 µs 560 µs 5741.8% 81 MiB
echo-ws-limited 4,096 2,192,315 msg/s 540 µs 1.01 ms 6461.4% 168 MiB

Latency & CPU efficiency — fixed-rate paced load

Unlike the peak-throughput profiles, these pin the offered rate, so every server that holds it delivers the same RPS and the ranking comes down to CPU cost per request, measured from cgroup v2 cpu.stat:

Profile Pinned rate Held CPU / req CPU Mean latency p99
latency-1m 1,000,000 req/s 99.8% 22.55 µs 2460.8% 94.5 µs 175.0 µs
latency-10k 10,000 req/s 99.8% 29.78 µs 28.5% 80.9 µs 112.0 µs
latency-500k-8cpu 500,000 req/s, 4 cores / 8 threads 86.1% 18.52 µs 796.2% 1.25 s 4.98 s

Key takeaways

  • Pipelined HTTP/1.1: 18.37 M req/s. Every request in one read batch shares a single write, instead of one syscall each.
  • Batched WebSocket: 36.42 M msg/s. The same idea applied to frames.
  • Memory is the differentiator. 4,096 concurrent connections cost 133 MiB. The HTTP/1.1 composite leader needs 4.3 GiB on the same run — a gap of over 30× that comes from the three-tier PMR pool, the connection-level ReadBufferPool, and the rule that an idle connection holds no read buffer at all.
  • Cheap at saturation. Holding a pinned 1 M req/s, one request costs 22.55 µs of CPU time summed across every thread — read straight out of the container's cgroup cpu.stat, not sampled.

Reproduce it

The numbers above come from HttpArena's controlled environment — your own hardware will produce different ones. To run the same kind of comparison locally, including Drogon / Cinatra / Crow / Gin / Actix:

cd benchmark && docker compose up

Core Features

  • Native network stack — picohttpparser zero-copy HTTP parsing + self-developed WebSocket (RFC 6455), zero heap allocation
  • C++26 Reflection — Automatic route registration + JSON serialization; seamless C++20 macro fallback
  • Coroutine async I/O — asio::awaitable<T> + co_await, sync fast path with zero coroutine frame overhead
  • PMR three-tier pool — Global synchronized / thread-local lock-free pool for connection-level allocations; request path uses ReadBufferPool + stack arrays + FixedBuffer for actual zero heap allocation
  • Full-featured middleware — Onion model, CORS, Session, Logging, OpenAPI 3.0 doc generation
  • WebSocket — permessage-deflate compression, Hub broadcast, subprotocol negotiation, heartbeat
  • Database middleware — Coroutine connection pool + auto-transaction + slow query detection (Boost.MySQL)
  • Production-ready — SSL/TLS, SO_REUSEPORT multi-acceptor, static file ETag/304, Docker deployment
  • 可选 HTTP/2 候选实现 — TLS ALPN、单连接多路复用、现有路由与中间件复用;服务端和客户端均需显式启用

Full feature list in Architecture.

Quick Start

#include "core/HttpServer.h"

using namespace hical;

int main()
{
    HttpServer server(8080);

    server.router().get("/", [](const HttpRequest&) -> HttpResponse {
        return HttpResponse::json({{"message", "Hello, Hical!"}});
    });

    server.router().get("/users/{id}",
        [](const HttpRequest& req) -> HttpResponse {
            return HttpResponse::json({{"userId", req.param("id")}});
        });

    server.start();
}
curl http://localhost:8080/
# {"message":"Hello, Hical!"}

Full tutorial at docs/quickstart.md, more examples in examples/.

Requirements

Dependency Notes
C++20/26 C++26 optional (reflection)
Boost >= 1.82 Asio, System, JSON; DB >= 1.85;生产 HTTP 客户端 >= 1.86
OpenSSL Required
nghttp2 >= 1.70.0, < 2 仅启用 HTTP/2 时需要,使用静态 C 库;HTTP/2 需 OpenSSL >= 1.1.1
zlib Required (WebSocket compression)
CMake >= 3.28 Build system
GCC 14+ / Clang 20+ / MSVC 2022+ Compiler

Build

# Linux / macOS
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
ctest --test-dir build --output-on-failure

# Windows (MSYS2 MINGW64)
cmake -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
cmake --build build

# Windows (MSVC + vcpkg)
cmake -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_TOOLCHAIN_FILE=C:/vcpkg/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release

Optional modules:

cmake -B build -DHICAL_WITH_DATABASE=ON ...    # Database middleware
cmake -B build -DHICAL_WITH_OPENAPI=OFF ...    # Disable OpenAPI
cmake -B build -DHICAL_ENABLE_REFLECTION=ON ...# C++26 Reflection
cmake -B build -DHICAL_WITH_HTTP_CLIENT=ON ...# 协程客户端,默认 OFF,需 Boost >= 1.86
cmake -B build -DHICAL_WITH_HTTP2=ON ...      # TLS HTTP/2,默认 OFF,需静态 nghttp2

HTTP/2 与客户端开关可独立组合。服务端还需在启动前调用 enableSsl() 和 enableHttp2();客户端默认 hHttp1Only,可选择 hNegotiateHttp2 或 hHttp2Only。HTTP/2 不包含 h2c、gRPC 或 WS/SSE 升级,完整示例见 HTTP/2 使用指南。

当前候选收紧了连接池重试:POST/PATCH 默认不自动重放,其他允许的方法最多重试一次,仍须满足协议证据或陈旧连接的瞬态错误条件。相对 v2.7.2 的 H1 行为变化与完整边界见 Unreleased 和 重试说明。

Docker

# Production deployment
docker compose -f docker/prod/docker-compose.yml up -d

Installation

vcpkg (Recommended)

vcpkg install hical61-hical
find_package(hical CONFIG REQUIRED)
target_link_libraries(my_app PRIVATE hical::hical_core)

Conan

Download the Conan source package from GitHub Releases and export to local cache:

# Download & extract (replace VERSION with actual version)
curl -LO https://github.com/Hical61/Hical/releases/download/vVERSION/hical-VERSION-conan-src.tar.gz
tar xzf hical-VERSION-conan-src.tar.gz

# Export to local Conan cache
cd hical
conan export . --version=VERSION
conan install . --build=missing
find_package(hical REQUIRED)
target_link_libraries(my_app PRIVATE hical::hical_core)

See Integration Guide for details.

Documentation

Contributing

Contributions are welcome! Basic workflow:

  1. Fork this repository
  2. Create a feature branch (git checkout -b feat/my-feature)
  3. Ensure clang-format checks and tests pass
  4. Submit a Pull Request

See CONTRIBUTING.md for details.

Contact

License

MIT