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

> libhv is a high-performance, event-driven network library for C and C++ that provides HTTP client/server, WebSocket, TCP/UDP, SSL/TLS, and MQTT support with a simpler API than libevent or libuv.

## Install

Save in your project root:

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

## Quick Use
```bash
git clone https://github.com/ithewei/libhv.git
cd libhv && mkdir build && cd build
cmake .. && make -j$(nproc)
sudo make install

# Run the built-in HTTP server example
bin/httpd -p 8080
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-1b46c38f
Author: AI Open Source