libhv — Cross-Platform C/C++ Network Library for TCP, HTTP & WebSocket

Introduction

libhv is a cross-platform network library for C and C++ that aims to be easier to use than libevent, libev, and libuv while maintaining high performance. It provides built-in HTTP client/server, WebSocket, TCP/UDP, SSL/TLS, and MQTT implementations in a single library with a consistent event-loop API.

What libhv Does

• Provides an event-driven, non-blocking I/O framework with epoll, kqueue, IOCP, and select backends for cross-platform support
• Implements a full HTTP/1.1 and HTTP/2 server and client with routing, middleware, and file serving built in
• Supports WebSocket client and server with automatic ping/pong and reconnection handling
• Includes TCP and UDP client/server abstractions with customizable codecs for protocol framing
• Offers MQTT client support and KCP (reliable UDP) protocol implementation

Architecture Overview

libhv uses a multi-threaded event-loop architecture. The main event loop handles acceptor sockets and timer management, while worker threads each run their own event loops for connection handling. I/O multiplexing is abstracted behind a unified API that selects the optimal backend per platform (epoll on Linux, kqueue on macOS/BSD, IOCP on Windows). The HTTP module layers on top of the event loop with a request/response model, while lower-level TCP/UDP access is available through channel abstractions.

Self-Hosting & Configuration

• Build from source using CMake on Linux, macOS, Windows, or Android with optional OpenSSL/mbedTLS for SSL
• Install as a system library or embed directly into your project as a submodule
• Configure event loop thread count, connection timeouts, and buffer sizes programmatically
• Enable SSL/TLS by linking against OpenSSL or mbedTLS at compile time
• The built-in httpd example can serve static files and proxy requests out of the box

Key Features

• Unified API across platforms: write once, compile on Linux, macOS, Windows, Android, and embedded systems
• Built-in HTTP server with router, static file serving, and middleware support without external dependencies
• Connection auto-reconnection for TCP and WebSocket clients with configurable backoff
• Memory-efficient I/O with zero-copy buffer management and configurable high-water marks
• Includes wrk-like HTTP benchmarking tool (bin/wrk) for load testing

Comparison with Similar Tools

• libuv — Lower-level event loop library used by Node.js; libhv adds HTTP, WebSocket, and MQTT on top
• libevent — Mature event notification library; libhv provides a simpler API with built-in protocol support
• Boost.Asio — C++ networking library requiring Boost; libhv is standalone with C and C++ APIs
• Poco — Comprehensive C++ library with networking; libhv is more focused and lightweight
• cpp-httplib — Header-only C++ HTTP library; libhv adds event-driven I/O, WebSocket, TCP/UDP, and MQTT

FAQ

Q: What platforms does libhv support? A: Linux, macOS, Windows, FreeBSD, Android, and various embedded platforms. It uses platform-specific I/O multiplexing automatically.

Q: Does libhv support HTTP/2? A: Yes. HTTP/2 support is available when built with the nghttp2 library. HTTP/1.1 works without any external dependencies.

Q: Can I use libhv from C or only C++? A: libhv provides both a C API and a C++ wrapper. The core library is written in C for maximum portability.

Q: How does performance compare to libuv? A: Benchmarks show comparable throughput to libuv for raw TCP, with the advantage of built-in HTTP parsing and routing that eliminates the need for additional libraries.

Sources

• https://github.com/ithewei/libhv
• https://github.com/ithewei/libhv/wiki