HP-Socket: a C/C++ TCP, UDP and HTTP framework built on IOCP and EPOLL

What HP-Socket solves, and who it is written for

Writing a socket server that holds tens of thousands of concurrent connections means solving the same problems repeatedly: an event loop that scales on each operating system, memory management that does not fragment under churn, and a buffer strategy that does not copy payloads more times than necessary. HP-Socket packages those pieces behind a listener interface, so the application supplies callbacks and the framework owns the transport.

The README splits the audience explicitly. Server components are built on IOCP on Windows and EPOLL on Linux, combined with a memory pool and private heap, and are aimed at large scale and high concurrent communication. Agent components share that architecture but act as multi-client objects: one Agent object can create and handle large-scale Socket connections at the same time. Client components use Event-Select or POLL, create one communication thread per object and manage a single Socket connection, which the README marks as suitable for small-scale client scenarios. That three-way split is the design decision that matters most: you pick the component family from your concurrency profile, not from your protocol.

The project is not a protocol implementation you embed and forget. It is a framework in the older sense: you subclass a listener, implement OnConnect, OnReceive, OnClose and the rest, and the component drives your code. Teams that expect a modern async/await surface or a package manager one-liner will find the integration style unfamiliar, but the callback contract is small and stable across the component families.

The listener and component model, and the eight-step lifecycle

Every HP-Socket program follows the same sequence, which the README lists as eight steps: create the listener object, create the component object and bind it to the listener, start the component, connect to a destination host (Agent only), process network events, stop the component, destroy the component, destroy the listener. In C++ the destruction steps are handled by smart pointer types such as CTcpPullServerPtr, so steps seven and eight happen automatically when the objects leave scope. In the C API you call Destroy_HP_TcpPullAgent and Destroy_HP_TcpPullAgentListener yourself, and forgetting either leaks.

The listener is where your logic lives. The C++ example subclasses CTcpPullServerListener and declares OnPrepareListen, OnAccept, OnHandShake, OnReceive, OnSend, OnClose and OnShutdown. The C API keeps the same events but wires them with function pointers: Create_HP_TcpPullAgentListener returns a listener handle, and HP_Set_FN_Agent_OnConnect, HP_Set_FN_Agent_OnSend, HP_Set_FN_Agent_OnPullReceive, HP_Set_FN_Agent_OnClose and HP_Set_FN_Agent_OnShutdown attach your callbacks. The pull variants deliver a length to OnReceive and expect you to fetch the data, which is why the callback signature in both examples takes an int iLength rather than a buffer.

Two details in the C example are worth noting because they shape application code. HP_Agent_Start takes a bind address and a boolean, shown as "0.0.0.0" and TRUE, and then HP_Agent_Connect is called once per remote host with a host, a port and a context pointer. So an Agent is a single object fanning out to many destinations, which is a different mental model from a client that owns one connection. The README does not document reconnection policy, backpressure behaviour when the send queue fills, or what happens to in-flight data on Stop; those are questions the development guide is the place to check.

Building HP-Socket and running the C++ TCP server example

The README does not give a package manager command or a CMake invocation. What the repository layout shows is a Windows directory and a Linux directory at the top level, alongside Doc/, DotNet/ and MacOS/, so the build inputs are platform-specific and you are expected to build from source rather than install a binary. The README points to the HP-Socket Development Guide PDF under Doc/ for the full documentation, and that is where build instructions belong if they exist.

Once the library is available, the smallest usable server is the README's C++ example. Include the umbrella header, subclass the pull server listener, and start the component on a port:

#include <hpsocket/HPSocket.h>

class CListenerImpl : public CTcpPullServerListener
{
public:
    virtual EnHandleResult OnPrepareListen(ITcpServer* pSender, SOCKET soListen);
    virtual EnHandleResult OnAccept(ITcpServer* pSender, CONNID dwConnID, UINT_PTR soClient);
    virtual EnHandleResult OnReceive(ITcpServer* pSender, CONNID dwConnID, int iLength);
    virtual EnHandleResult OnClose(ITcpServer* pSender, CONNID dwConnID, EnSocketOperation enOperation, int iErrorCode);
};

The declarations above are the contract you implement. The next block is the lifecycle the README shows in main, with the bind address and port taken verbatim from the example:

int main(int argc, char* const argv[])
{
    CListenerImpl s_listener;
    CTcpPullServerPtr s_pserver(&s_listener);

    if(!s_pserver->Start("0.0.0.0", 5555))
        exit(1);

    // ... ...

    s_pserver->Stop();
    return 0;
}

After Start returns true the server is listening on port 5555 and your OnAccept and OnReceive callbacks fire as connections arrive and data lands. The README's example leaves the wait-for-exit section as a comment, so the process needs its own loop or signal handling before Stop is reached. If Start returns false the example exits with status 1; there is no error detail in that path, and the README does not describe how to retrieve the failure reason.

Where HP-Socket stops being the right tool

The licence is the first constraint. The repository metadata reports NOASSERTION, meaning the LICENSE file at the top level does not resolve to a recognised SPDX identifier through the tooling that produced that field. For a component that gets compiled into a shipping product, that is a question to settle before writing code, not after. Nothing in the README clarifies the terms, so the LICENSE file itself is the only source.

The second constraint is platform. The README links two extension projects rather than shipping them in-tree: HP-Socket for MacOS and HP-Socket for .Net, both hosted on Gitee. The repository does contain a MacOS directory and a DotNet directory, but the README's own framing treats macOS and .NET as extensions, which suggests they are maintained on a different cadence from the Windows and Linux core. If macOS is your primary target, verify the state of that code path yourself.

The third constraint is the Client component family. It uses Event-Select or POLL and one communication thread per object managing one Socket connection, which the README itself scopes to small-scale client scenarios. Reaching for a Client component to open thousands of outbound connections contradicts the stated design; the Agent family exists for that. Similarly, if your application is a single HTTP endpoint behind a reverse proxy, a full socket framework with a listener subclass and manual lifecycle management is more machinery than the problem needs.

How HP-Socket differs from libevent and Boost.Asio

libevent and Boost.Asio are the obvious reference points, and the difference is where the abstraction line sits. libevent gives you an event loop and a set of bufferevent helpers; you own the connection state machine, the accept loop and the buffer lifecycle. Asio gives you an executor model with completion handlers and, in recent standards, coroutines. Both leave memory strategy to you or to the allocator.

HP-Socket moves the line up. It ships the accept loop, the connection table, the send and receive buffers, and an internal memory pool with private heaps, and exposes the result as a listener with named events. The README also names the libraries it builds on: mimalloc and jemalloc for allocation, OpenSSL for the SSL components, llhttp for HTTP parsing, zlib and brotli for compression, and kcp. That list tells you the framework is assembled from established pieces rather than reimplementing parsing and TLS.

The trade-off is control. With Asio you can swap in a different allocator, run the loop on a custom executor, or integrate with an existing reactor. With HP-Socket you implement the listener interface and the framework decides the rest. For a team that wants a working high-concurrency server on Windows and Linux without building the plumbing, that is the point. For a team that needs to co-schedule network I/O with an existing event loop, the callback model is a wall rather than a convenience.

Version cadence, upgrade cost and licence questions

The release history is uneven rather than steady. v6.0.7 was tagged on 2025-10-14, v6.0.8 on 2026-02-12, and v6.0.9 on 2026-08-31, which is also the date of the last push to the dev branch. That is roughly three releases in under a year, with gaps of about four and six and a half months. The repository is not archived, and the most recent activity is close to the present, so the project is live; the spacing simply means you should not assume a monthly patch stream.

Upgrade cost is hard to estimate from the README because it does not document API stability guarantees between minor versions. The C API is explicit about lifetime: you call Create_HP_TcpPullAgent and Destroy_HP_TcpPullAgent, and the listener has its own create and destroy pair. If a release changes a function pointer signature or an event enum, that pairing is where the breakage surfaces. Pin the version you build against and read the release notes for v6.0.8 and v6.0.9 before moving.

On licensing, the NOASSERTION value is the fact to act on. It does not mean the project is unlicensed; it means the automated classification did not match a known identifier. Whether that matters depends on how you distribute your product, and that determination is for your legal review, not for this article. The practical step is to read the LICENSE file at the repository root and compare it against whatever your organisation requires.

Editorial conclusion

HP-Socket fits teams already shipping native Windows or Linux services in C or C++ that need one API across TCP, UDP, HTTP and SSL, and that are willing to read the PDF development guide before writing code. It is the wrong choice if you need a permissively licensed, SPDX-clean dependency, or if you want a pure managed stack with no native library to build. Before adopting it, open the LICENSE file and confirm which terms actually apply, then check whether the CI and build files under Windows/ and Linux/ cover the compiler and platform you target.

Frequently asked questions

Official sources

1. Issues
2. ldcsaa/HP-Socket on GitHub
3. Project website
4. README
5. Releases