weaseldb/threading_performance_report.md

WeaselDB Threading Performance Analysis Report

Summary

WeaselDB achieved 1.3M requests/second throughput using a two-stage ThreadPipeline, with 396ns serial CPU time per request. Higher serial CPU time means more CPU budget available for serial processing.

Performance Metrics

Throughput

• Non-blocking: 1.3M requests/second over unix socket
• Blocking: 1.1M requests/second over unix socket
• 8 I/O threads with 8 epoll instances
• Load tester used 12 network threads
• Max latency: 4ms out of 90M requests

Threading Architecture

• Two-stage pipeline: Stage-0 (noop) → Stage-1 (connection return)
• Lock-free coordination using atomic ring buffer
• Each request "processed" serially on single thread

Non-blocking vs Blocking Acquisition

Non-blocking acquisition (mayBlock=false):

• Throughput: 1.3M requests/second (maintained with up to 1200 loop iterations)
• Stage-0 CPU: 100% (10% futex wake, 90% other)
• Serial CPU time per request: 396ns (1200 iterations, validated with nanobench)
• 100% CPU usage when idle

Blocking acquisition (mayBlock=true):

• Throughput: 1.1M requests/second (800 loop iterations)
• Stage-0 CPU: 100% total (18% sched_yield, 8% futex wait, 7% futex wake, 67% other)
• Serial CPU time per request: 266ns (800 iterations, validated with nanobench)
• 0% CPU usage when idle

Request Flow

I/O Threads (8) → HttpHandler::on_batch_complete() → ThreadPipeline
                                                          ↓
                                                   Stage 0: Noop thread
                                                   (396ns serial CPU per request)
                                                          ↓
                                                   Stage 1: Connection return
                                                          ↓
                                             Server::release_back_to_server()

Pipeline Configuration

• Stage 0: 1 noop thread
• Stage 1: 2 worker threads for connection return
• Atomic counters with shared ring buffer

Memory Management

• Transfer ownership of the connection along the pipeline

Test Configuration

• Server: test_config.toml with 8 io_threads, 8 epoll_instances
• Load tester: ./load_tester --network-threads 12
• Build: ninja
• Command: ./weaseldb --config test_config.toml