How hoshimiaya/hoshimnet works
HoshiMNet is a small C++ TCP networking framework organized as a reusable library plus a top-level executable entry point. The codebase is built with CMake and is split into a low-level “base” layer and a network stack under hoshiMNet/net.
The architecture is centered on an event-driven reactor model. EventLoop owns the per-thread dispatch loop, Epoller wraps Linux epoll, and Channel represents an fd plus the events/callbacks registered for it. This is the core boundary for I/O handling: sockets are not actively polled by application code; they are driven by the loop through epoll notifications.
The socket and address layer is intentionally thin. Socket wraps the underlying TCP socket operations, and InetAddress encapsulates endpoint information. These types feed into higher-level connection and listener components without exposing raw system calls to the rest of the stack.
Server-side connection acceptance flows through Acceptor into TcpServer. Acceptor listens on the server socket and produces new inbound connections; TcpServer owns the listening lifecycle, creates TcpConnection instances, and typically manages the connection map and connection-level callbacks. This is the main ingress path for external clients.
TcpConnection is the per-connection abstraction. It sits between the socket/channel layer and the application-facing callbacks, handling state, read/write readiness, and connection teardown. This is likely the main place where application logic attaches to network events.
Client-side outbound connections are handled separately by TcpClient. That suggests the library supports both server and client roles with a shared core, rather than being server-only.
Concurrency is split between generic utilities and I/O threading. EventLoopThreadPool distributes event loops across threads for scalable network I/O, while base/ThreadPool appears to be a more general-purpose worker pool. This implies a design where networking remains reactor-based, but auxiliary tasks can be offloaded to worker threads.
The base directory also contains infrastructure code: Log for diagnostics, MpmcQueue for concurrent producer/consumer communication, Observer for callback-style notification, and Singleton for globally shared objects. These are supporting building blocks rather than the main data path.
The primary data flow is: external TCP client/server traffic enters through the socket, Acceptor or TcpClient creates/uses a TcpConnection, the fd is registered with Channel, Epoller signals readiness, and EventLoop dispatches the corresponding callbacks back into connection logic. That loop is the key diagrammatic cycle.
The repository appears Linux-oriented because epoll is the central polling primitive. That means the runtime architecture is tied to POSIX sockets and event-driven I/O rather than a portable abstraction like select/poll or an async runtime from a higher-level framework.
main.cpp is the only top-level application source visible, so the repo likely ships as a framework/library with a minimal executable or example harness. The most important diagram boundary is therefore between the reusable networking core and whatever application logic is attached through callbacks in TcpServer/TcpClient.
For an architecture diagram, the essential subsystems are:
1) build and entry point,
2) base utilities,
3) socket/address abstractions,
4) reactor core (EventLoop/Epoller/Channel),
5) server acceptor and connection management,
6) client outbound path,
7) loop/thread pools,
8) cross-cutting logging and concurrency helpers.
Main entry points: TcpServer.h TcpServer · EventLoop.h EventLoop · TcpConnection.h TcpConnection · TcpClient.h TcpClient
Components 20
Build & entry
Top-level build files and executable entry point.
- CMake · Top-level build configuration.
CMakeLists.txt - Library CMake · Build rules for the reusable networking library.
hoshiMNet/CMakeLists.txt - Base CMake · Build rules for the base utility layer.
hoshiMNet/base/CMakeLists.txt - Net CMake · Build rules for the networking stack.
hoshiMNet/net/CMakeLists.txt - Main · Top-level executable or demo harness.
main.cpp
Base layer
Cross-cutting utilities and concurrency helpers.
- Log · Logging and diagnostics support.
hoshiMNet/base/Log.h - Queue · Concurrent multi-producer multi-consumer queue.
hoshiMNet/base/MpmcQueue.h - Observer · Callback-style notification helper.
hoshiMNet/base/Observer.h - Singleton · Shared-instance helper for global services.
hoshiMNet/base/Singleton.h - ThreadPool · General-purpose background worker pool.
hoshiMNet/base/ThreadPool.h
Networking stack
Reactor-based TCP networking components.
- InetAddress · TCP endpoint and address wrapper.
hoshiMNet/net/InetAddress.h - Socket · Thin wrapper around TCP socket operations.
hoshiMNet/net/Socket.h - Channel · File descriptor, interested events, and callbacks.
hoshiMNet/net/Channel.h - Epoller · Linux epoll polling and readiness demultiplexing.
hoshiMNet/net/Epoller.h - EventLoop · Per-thread event dispatch loop.
hoshiMNet/net/EventLoop.h - Loop Pool · Distributes event loops across threads.
hoshiMNet/net/EventLoopThreadPool.h - Acceptor · Accepts inbound TCP connections.
hoshiMNet/net/Acceptor.h - TcpConnection · Per-connection state and I/O callback boundary.
hoshiMNet/net/TcpConnection.h - TcpServer · Owns listening lifecycle and server-side connections.
hoshiMNet/net/TcpServer.h - TcpClient · Outbound TCP connection manager.
hoshiMNet/net/TcpClient.h
Connections 26
- CMake → Library CMake: builds · Top-level build includes the library module.
- Library CMake → Base CMake: includes · Library build pulls in base utilities.
- Library CMake → Net CMake: includes · Library build pulls in networking stack.
- Main → TcpServer: uses · Application entry point likely instantiates server logic.
- Main → TcpClient: uses · Application entry point may drive client logic.
- Log → TcpServer: cross-cutting · Logging supports server operations.
- Log → TcpClient: cross-cutting · Logging supports client operations.
- ThreadPool → Loop Pool: supports · General worker threads complement reactor threads.
- Queue → ThreadPool: feeds · Concurrent queue underpins worker dispatch patterns.
- Observer → TcpServer: callbacks · Notification/callback utilities support connection events.
- Singleton → Log: shares · Global helper pattern can back shared logging state.
- InetAddress → Socket: configures · Endpoint data is used to create and bind sockets.
- Socket → Channel: registered as · Socket file descriptor is monitored through a channel.
- Channel → Epoller: tracked by · Channels are registered with the epoll wrapper.
- Epoller → EventLoop: driven by · Event loop owns the poll/dispatch cycle.
- EventLoop → Channel: dispatches · Loop invokes channel callbacks on readiness events.
- Loop Pool → EventLoop: creates · Thread pool manages multiple event loops.
- Acceptor → TcpServer: accepts for · Acceptor hands inbound connections to the server.
- Acceptor → Socket: binds · Listener uses socket primitives to accept connections.
- TcpServer → TcpConnection: creates · Server creates and manages per-connection objects.
- TcpClient → TcpConnection: owns · Client side uses the same connection abstraction.
- TcpConnection → Channel: wraps · Connection couples socket state to event notifications.
- TcpConnection → EventLoop: runs on · Connection callbacks execute on an event loop.
- TcpServer → Acceptor: listens via · Server controls the listening lifecycle through the acceptor.
- TcpServer → Loop Pool: scales with · Server can distribute work across loop threads.
- TcpClient → EventLoop: connects on · Outbound connection activity is driven by the loop.