Followup updates for new epoll_instances design

design.md

@@ -19,7 +19,8 @@ WeaselDB is a high-performance write-side database component designed for system
 
 - **Ultra-fast arena allocation** (~1ns vs ~20-270ns for malloc)
 - **High-performance JSON parsing** with streaming support and SIMD optimization
-- **Multi-threaded networking** using epoll with unified I/O thread pool
+- **Multi-threaded networking** using multiple epoll instances with unified I/O thread pool
+- **Configurable epoll instances** to eliminate kernel-level contention
 - **Zero-copy design** throughout the pipeline
 - **Factory pattern safety** ensuring correct object lifecycle management
 
@@ -90,13 +91,15 @@ Ultra-fast memory allocator optimized for request/response patterns:
 #### **Networking Layer**
 
 **Server** (`src/server.{hpp,cpp}`):
-- **High-performance multi-threaded networking** using epoll with unified I/O thread pool
+- **High-performance multi-threaded networking** using multiple epoll instances with unified I/O thread pool
+- **Configurable epoll instances** to eliminate kernel-level epoll_ctl contention (default: 2, max: io_threads)
+- **Round-robin thread-to-epoll assignment** distributes I/O threads across epoll instances
+- **Connection distribution** keeps accepted connections on same epoll, returns via round-robin
 - **Factory pattern construction** via `Server::create()` ensures proper shared_ptr semantics
 - **Safe shutdown mechanism** with async-signal-safe shutdown() method
 - **Connection ownership management** with automatic cleanup on server destruction
 - **Pluggable protocol handlers** via ConnectionHandler interface
-- **Unified I/O architecture:** single thread pool handles both connection acceptance and I/O processing
-- **EPOLL_EXCLUSIVE** on listen socket prevents thundering herd across I/O threads
+- **EPOLL_EXCLUSIVE** on listen socket across all epoll instances prevents thundering herd
 
 **Connection** (`src/connection.{hpp,cpp}`):
 - **Efficient per-connection state management** with arena-based memory allocation
@@ -205,11 +208,12 @@ The system implements a RESTful API:
 ### Design Principles
 
 1. **Performance-first** - Every component optimized for high throughput
-2. **Memory efficiency** - Arena allocation eliminates fragmentation
-3. **Zero-copy** - Minimize data copying throughout pipeline
-4. **Streaming-ready** - Support incremental processing
-5. **Type safety** - Compile-time validation where possible
-6. **Resource management** - RAII and move semantics throughout
+2. **Scalable concurrency** - Multiple epoll instances eliminate kernel contention
+3. **Memory efficiency** - Arena allocation eliminates fragmentation
+4. **Zero-copy** - Minimize data copying throughout pipeline
+5. **Streaming-ready** - Support incremental processing
+6. **Type safety** - Compile-time validation where possible
+7. **Resource management** - RAII and move semantics throughout
 
 ### Future Integration Points