Skip to content

documentation.md

Latest commit

 

History

History
62 lines (47 loc) · 3.79 KB

documentation.md

File metadata and controls

62 lines (47 loc) · 3.79 KB

Eaze WebSocket: Comprehensive Documentation & Performance Report

This document serves as the definitive technical reference and performance validation report for the Eaze WebSocket Java Project.

1. System Architecture

Eaze WebSocket is a high-performance networking library designed for massive scale. It utilizes a distributed NIO approach combined with Java's modern concurrency primitives.

1.1 Components

  • NioWebSocketServer: The entry point. Manages the lifecycle of acceptor threads and sub-pollers.
  • SubPoller: An isolated event loop (Selector) that handles I/O readiness for a subset of connections.
  • NioWebSocketSession: Encapsulates the state of a single connection, including its channel, handshake status, and "sticky" buffers for fragmented data.
  • FrameCodec: A stateless utility for encoding/decoding WebSocket frames according to RFC 6455.
  • BufferPool: A thread-safe pool of direct byte buffers used to reduce allocation overhead.

2. Performance & Benchmarking Report

2.1 Test Environment

  • Hardware: Intel Core i7-14700K (20 Cores, 28 Threads).
  • RAM: 32GB System RAM.
  • OS: Ubuntu 24.04 LTS.
  • Runtime: OpenJDK 21 (with ZGC).

2.2 Benchmark Results

The system was subjected to a ramp-up test where concurrent connections were increased until failure.

Connection Count Stability Memory Usage CPU Load Observations
100,000 Rock Solid ~2.1 GB ~5% Negligible impact on system responsiveness.
200,000 Rock Solid ~4.2 GB ~10% Consistent latency under message load.
250,000 Stable ~5.0 GB ~15% Target benchmark achieved. No dropped connections.
300,000 Marginal ~6.2 GB ~25% Approaching OS-level file descriptor limits.
320,000+ Failure - - OS refused new socket allocations (EMFILE/ENFILE).

2.3 Analysis of Failure Points (300K+)

At the 300,000+ connection threshold, the following bottlenecks were identified:

  1. OS File Descriptors: Even with ulimit increased, the kernel's fs.file-max and fs.nr_open limits require significant tuning to allow more than 300k sockets for a single process.
  2. TCP Memory (tcp_mem): The kernel began throttling new connections as the memory allocated to the TCP stack reached its configured pressure limits.
  3. Ephemeral Port Exhaustion: On the client-side, simulating 300k+ connections required a large pool of virtual IP addresses to avoid port exhaustion.

2.4 Resource Efficiency

A key finding of the benchmark is the extreme memory efficiency. With only 5GB of RAM used for 250,000 connections, the per-connection overhead is approximately 20KB. This includes the TCP stack overhead, JVM object overhead, and buffered data.

3. API Reference

WebSocketSession

  • void send(String text): Sends a text frame.
  • void send(byte[] data): Sends a binary frame.
  • void close(int code, String reason): Closes the connection gracefully.
  • boolean isOpen(): Checks connection status.
  • String getRemoteAddress(): Returns the remote IP and port.

Configuration

The NioWebSocketServer can be configured with:

  • pollerThreads: Number of threads accepting new connections (default: 2).
  • selectorThreads: Number of sub-pollers (default: CPU core count).

4. Best Practices for High Concurrency

  • Avoid Blocking: Never perform blocking I/O or long-running computations inside the onMessage callback. While they run in Virtual Threads, excessive blocking can still lead to resource exhaustion (pinning).
  • Message Size: Keep messages small. Large messages increase memory pressure on the BufferPool.
  • Monitoring: Use JMX or a custom metrics exporter to monitor the number of active sessions and SubPoller load.