Introduction to HXLibs
Relevant source files
The following files were used as context for generating this wiki page:
HXLibs is a modern C++20 library collection and web framework. It provides high-performance networking capabilities using asynchronous coroutines and advanced I/O mechanisms like io_uring and epoll. The project focuses on providing a modern developer experience through C++20 features, reflection, and high-concurrency server implementations.
Sources: vcpkg.json:6, static/indexByJson.html:61, documents/CodingStandards/CppStyle.md:4
Project Architecture and Core Technologies
HXLibs organizes its functionality into modular components, primarily focusing on networking, coroutines, and utility tools. It uses CMake for build management and vcpkg for dependency handling, specifically for openssl and sqlite3.
Core Technical Stack
The framework builds upon several key technologies to achieve high performance:
- Language Standard: Minimum C++20 requirement for modern syntax and coroutine support.
- I/O Engines: Supports
io_uringfor high-concurrency disk and network I/O, as well asepollfor event loops. - Asynchrony: Heavy reliance on C++ coroutines (
co_await,co_return) for non-blocking operations. - Serialization: Built-in reflection-based JSON serialization and deserialization.
Sources: documents/CodingStandards/CppStyle.md:4, CMakeLists.txt:1-12, vcpkg.json:7-10, static/indexByJson.html:61
Architecture Overview
The following diagram illustrates the high-level relationship between the network layer, the coroutine event loop, and the application endpoints.
The framework uses a compressed prefix tree for efficient route matching and dispatches requests to coroutine-based handlers.
Sources: static/index.html:77, static/indexByJson.html:61, tests/server/01_http_server.cpp:52-70
Networking and Web Framework
The networking module provides both HTTP/HTTPS servers and clients. It supports standard RESTful methods, WebSocket communication, and Server-Sent Events (SSE).
Server Components
The HttpServer class manages the lifecycle of the web server. Developers define behavior by adding endpoints with specific HTTP methods.
| Feature | Description | Relevant Methods/Classes |
|---|---|---|
| Routing | Matches paths to handlers using templates and wildcards. | addEndpoint<METHOD>(path, handler) |
| I/O Models | Supports Range Transfer and Chunked Encoding for files. | useRangeTransferFile, useChunkedEncodingTransferFile |
| Security | Provides SSL/TLS support via OpenSSL. | initSsl, HttpsClient |
| WebSocket | Full-duplex communication support. | WebSocketFactory, ws.sendText, ws.recvText |
Sources: examples/Server/02_https_server.cpp:25-78, tests/server/01_http_server.cpp:52-80, benchmarks/http/servers/hxlibs_server.cpp:55-70
Request Handling Flow
When a request arrives, the server processes it through the following sequence:
AI Integration Capabilities
HXLibs includes specialized clients for interacting with AI model APIs, such as DeepSeek. The AiClient supports standard chat completions and streaming via SSE.
AI Message Structure
The framework defines structured roles for AI interactions, ensuring type safety when building prompts.
- SystemMessage: Defines the AI's persona.
- UserMessage: Contains user input.
- AssistantMessage: Represents the model's response, including reasoning content.
- ToolMessage: Handles responses from function/tool calls.
Sources: examples/ai/ai.cpp:11-40
Streaming with SSE
The framework provides a coSseLoop to handle streaming responses efficiently using coroutines.
// Example AI Stream Handling
auto res = co_await cli.coChat(req, [](net::SseEvent sse) -> coroutine::Task<> {
if (!sse.data.empty()) {
log::hxLog.warning(sse.data);
}
co_return;
});
Sources: examples/ai/ai.cpp:88-100, examples/ai/ai.cpp:138-144
Coding Standards and Development
HXLibs enforces specific C++ styles to maintain consistency across the library.
Naming Conventions
- Files: CamelCase (e.g.,
AddressResolver.h). - Namespaces: Based on directory structure (e.g.,
namespace HX::coroutine). - Members: Prefixed with an underscore (e.g.,
_name). - Constants:
kprefix with CamelCase or PascalCase. - Macros: Upper case with
HX_prefix.
Sources: documents/CodingStandards/CppStyle.md:6-38
Build Configuration
The CMakeLists.txt manages different build modes and features.
| Variable | Default | Description |
|---|---|---|
CMAKE_BUILD_TYPE | Release | Set to Debug for memory leak checking and debugging. |
HXLIBS_ENABLE_DB_SQLITE3 | ON | Enables SQLite3 database support in development mode. |
IO_URING_DIRECT | OFF | Controls direct O_DIRECT I/O (currently experimental). |
Sources: CMakeLists.txt:18-38
Performance Benchmarking
HXLibs includes a comprehensive benchmarking suite to compare its performance against other frameworks like Asio, yalantinglibs, Nginx, and Spring Boot.
Benchmark Scenarios
The project tests multiple real-world traffic patterns:
- Short Response: Minimal payload to test framework overhead.
- JSON API: Standard API response testing.
- Dynamic Routing: Multi-level path and query parameter parsing.
- Memory vs. Disk I/O: Compares static resource delivery from memory against real file system reads via
useRangeTransferFile.
Sources: documents/HttpPerformanceBenchmark.md:32-48, benchmarks/http/servers/hxlibs_server.cpp:66-72
Performance Analysis
The benchmarking tool generates interactive HTML reports that visualize:
- Throughput (RPS): Median and per-round request-per-second data.
- Latency Distribution: P50 through P99.99 latency curves.
- Stability: Standard deviation and Coefficient of Variation (CV) across repeated rounds.
Sources: documents/HttpPerformanceBenchmark.md:52-65, benchmarks/http/scripts/report.py:167-210
Summary
HXLibs is a high-performance C++20 toolkit providing asynchronous networking, AI integration, and reflection-based utilities. By leveraging modern C++ features and efficient I/O engines like io_uring, it serves as a robust foundation for building high-concurrency web applications and AI-driven services.