How navining/zeus works
1. What this repository is
Zeus is a C++ networking engine, not an application. Its core purpose is to provide a cross-platform TCP communication layer built directly on native socket APIs, with no third-party runtime dependencies.
2. Top-level structure
The repository is split into three meaningful areas:
- net/: the networking engine itself
- utils/: support infrastructure for performance, concurrency, config, logging, and timing
- examples/: a minimal TCP client/server pair used to demonstrate and validate the engine
3. Core networking layer
The net/ directory is the main architecture boundary. It contains the abstractions for sockets, event handling, connection management, and multiplexing backends. This is where the engine turns OS-level socket activity into higher-level connection logic.
4. I/O multiplexing backends
Zeus supports multiple event-demultiplexing models through separate backend implementations:
- Epoll.* for Linux
- Select.* for portable fallback
- IO.* and Event.h as the abstraction layer around readiness/dispatch
The README also mentions IOCP as planned, but it is not present here.
5. Connection lifecycle
The main connection-oriented classes are:
- TcpClient.*: client-side connection establishment and communication
- TcpServer.*: listening socket, accept loop, and server-side orchestration
- TcpConnection.*: per-connection state and I/O handling
- TcpSubserver.*: likely a worker/partitioned server component used to scale handling across threads or sub-loops
This suggests the architecture centers on managing many concurrent TCP sessions with per-connection state objects.
6. Data movement and framing
Buffer.*, Stream.*, and Message.h define the data path above raw sockets:
- Buffer is the byte storage used for receive/send paths
- Stream likely provides higher-level read/write helpers over buffers
- Message represents application payloads or protocol units
The engine appears to separate transport I/O from message handling, which is important for diagramming the data flow.
7. Concurrency and task execution
The utils/ layer provides the concurrency primitives that support scaling:
- Thread.* for thread abstraction
- Semaphore.* for coordination
- TaskHandler.* for deferred or background work
- Timestamp.* for timing and timeout-related logic
This indicates the engine is not purely single-threaded; it has infrastructure for threaded execution around the I/O core.
8. Memory and object reuse
Performance-oriented allocation is a first-class concern:
- Allocator.h
- MemoryPool.*
- ObjectPool.h
These are used to reduce heap churn and improve throughput under high connection counts, which matches the README’s emphasis on large-scale concurrency.
9. Configuration, logging, and observability
Operational support lives in utils/Config.*, utils/Log.*, and utils/Timestamp.*.
- Config provides runtime/environment settings
- Log gives the “complete and detailed log system” described in the README
- Timestamp supports timeout, heartbeat, and telemetry-style timing
These are supporting services rather than business logic, but they matter in the architecture because they drive runtime behavior and troubleshooting.
10. Cross-platform boundary
The portability boundary is the OS socket and event API layer. The repository targets Windows, Linux, and macOS, with the backend code selecting between platform-specific I/O models while keeping the higher-level client/server API consistent.
11. Example applications
examples/client and examples/server are small reference programs:
- the server is an echo server
- the client exercises the TCP stack
They are useful for understanding the intended call flow: configure → start server/client → send messages → receive echo → log activity.
12. Build and deployment shape
The repository is built with CMake on Unix-like systems and Visual Studio projects on Windows. The examples are the main buildable targets shown in the tree, and the README notes generated executables are placed under bin/.
13. Architectural takeaway for a diagram
A good diagram would show:
- application code at the top
- client/server APIs in net/
- a shared I/O abstraction layer selecting select or epoll
- per-connection buffers and connection objects
- support services in utils/ for pools, threads, logging, and config
- the operating system socket layer at the bottom
There are no external services or middleware dependencies; the engine is self-contained and talks directly to the OS networking stack.
Main entry points: Network.h Network · TcpServer.h TcpServer · TcpConnection.h TcpConnection · IO.h IO
Components 23
examples
Reference client/server programs
net
Core networking engine
- Network · Top-level networking API and initialization
net/Network.h - TcpClient · Client-side connection setup and messaging
net/TcpClient.h - TcpServer · Listening socket and server orchestration
net/TcpServer.h - TcpSubserver · Partitioned server or worker loop
net/TcpSubserver.h - TcpConnection · Per-connection state and I/O handling
net/TcpConnection.h - Buffer · Read/write byte storage
net/Buffer.h - IO · Readiness and event dispatch abstraction
net/IO.h - Event · Event representation used by the I/O layer
net/Event.h - Epoll · Linux epoll multiplexing backend
net/Epoll.h - Select · Portable select-based fallback backend
net/Select.h
utils
Support infrastructure
- Stream · Higher-level read/write helpers over buffers
utils/Stream.h - Message · Application message or protocol unit
utils/Message.h - Thread · Thread abstraction
utils/Thread.h - Semaphore · Coordination primitive
utils/Semaphore.h - TaskHandler · Deferred or asynchronous task execution
utils/TaskHandler.h - MemoryPool · Pooled allocation for throughput
utils/MemoryPool.h - ObjectPool · Reusable object storage
utils/ObjectPool.h - Config · Runtime and environment settings
utils/Config.h - Log · Logging and diagnostics
utils/Log.h - Timestamp · Timeout and timing support
utils/Timestamp.h
Other components
- OS sockets · Native socket and event APIs provided by the operating system
Connections 24
- Client → Network: uses · Example client enters the engine API
- Server → Network: uses · Example server starts the engine
- Network → TcpClient: exposes · Shared top-level API for client operations
- Network → TcpServer: exposes · Shared top-level API for server operations
- TcpServer → TcpSubserver: scales · Server may shard work into subservers or loops
- TcpClient → TcpConnection: creates · Client establishes a session object for I/O
- TcpServer → TcpConnection: accepts · Accepted sockets become connection state
- TcpConnection → Buffer: uses · Connection I/O moves through buffers
- Buffer → Stream: adapts to · Streams build on buffer operations
- Stream → Message: moves · Stream helpers carry message payloads
- TcpConnection → IO: dispatches via · Connection activity is driven by readiness events
- IO → Event: models · Events are normalized for dispatch
- IO → Epoll: selects · Linux backend implementation
- IO → Select: selects · Portable fallback backend
- Epoll → OS sockets: calls · Backend talks to native OS APIs
- Select → OS sockets: calls · Fallback backend talks to native OS APIs
- TcpServer → Thread: runs on · Server work can be threaded
- TcpServer → Semaphore: coordinates · Coordination between workers or loops
- TcpServer → TaskHandler: offloads · Deferred work can be scheduled
- TcpConnection → MemoryPool: allocates from · Connection objects or buffers are pooled
- TcpConnection → ObjectPool: reuses · Session-related objects are recycled
- Network → Config: configured by · Runtime settings shape engine behavior
- Network → Log: reports to · Operational logging spans the engine
- Network → Timestamp: times with · Timeouts and timing are managed centrally