High-Performance Epoll Echo Server

A lightweight, non-blocking I/O server implementation for Linux, designed to demonstrate O(1) scalability and resource efficiency using the epoll API.

Unlike traditional thread-per-client models, this project utilizes a single-threaded event loop to handle high concurrency with minimal memory footprint and zero context-switching overhead, making it suitable for resource-constrained and energy-sensitive environments.

Core Architecture

Event-Driven Design

The system is built on a level-triggered epoll loop (sys/epoll.h) that drives all I/O operations asynchronously:

• Zero Blocking: All sockets are configured with SOCK_NONBLOCK. Reads/writes drain buffers until EAGAIN to ensure no head-of-line blocking.
• O(1) Complexity: Uses the Linux kernel's Red-Black tree (internal to epoll) for socket monitoring, allowing the server to scale to thousands of idle connections without performance degradation (unlike $O(N)$ poll/select).
• Signal Handling: Integration of signalfd allows strictly synchronous signal handling within the main loop, preventing race conditions common in asynchronous signal handlers.

Networking & Protocol

• Dual-Stack Support: Handles IPv4 and IPv6 transparently via IPV6_V6ONLY=0, falling back to separate sockets if kernel policies restrict binding.
• UDP & TCP Unification: Manages connection-oriented (TCP) and datagram (UDP) streams within the same event loop.
• Load Shedding: Implements strict backlog and connection caps (--max-tcp) to reject excess load deterministically ("Server Busy") rather than degrading service quality.

Performance Characteristics

This architecture is chosen specifically to optimize Energy Efficiency:

1. CPU Conservation: Eliminating thread contention and context switches reduces CPU wakeups.
2. Memory Locality: Single-process architecture improves instruction cache (L1/L2) locality compared to multi-process prefork models.
3. Telemetry: Built-in timerfd provides low-overhead, strictly periodic statistics aggregation (/stats command) without "stop-the-world" locking.

Build & Usage

Compilation

Requires a C11 compliant compiler and Linux 2.6.27+ (for epoll).

# Standard Build
make

# Build with Systemd Socket Activation support
make ENABLE_SYSTEMD=1

Running the Server

The daemon defaults to port 12345 but offers granular control for benchmarking scenarios:

# Run with high connection cap for load testing
ulimit -n 65536
./epoll-echo --port 8080 --max-tcp 10000 --backlog 1024 -vv

Telemetry Commands

The TCP protocol accepts administrative commands for monitoring:

• /stats: Returns real-time metrics (Total Clients, Active UDP Peers, Connected TCP).
• /time: Returns high-precision server time.
• /shutdown <token>: Graceful termination sequence (guarded by token).

Testing & Validation

The tests/ suite validates strictly defined behaviors, ensuring robustness against common network edge cases:

• TCP Framing: Handling logic for split packets and partial reads.
• Overflow Protection: Enforcement of 4KiB line limits to prevent memory exhaustion attacks.
• UDP Truncation: Detection of MSG_TRUNC to handle MTU violations safely.

System Integration

Includes full support for systemd integration, including:

• Socket Activation: Adoption of pre-bound file descriptors (zero-downtime restarts).
• Journald Logging: Structured logging output.
• Credential Management: Secure passing of administrative tokens via $CREDENTIALS_DIRECTORY.

---

Implementation uses standard Linux APIs (epoll_wait, timerfd_create, signalfd) without external library dependencies to ensure a minimal binary size.