Project 11: Thread Pool TCP Server

Combine epoll event loop with a thread pool: the main thread handles I/O multiplexing, worker threads process requests. This is how production servers handle CPU-intensive work without blocking the event loop.

Quick Reference

Attribute Value
Primary Language C++
Alternative Languages Rust, Go
Difficulty Level 3: Advanced
Time Estimate 2 weeks
Knowledge Area Concurrency, Thread Pool, Work Distribution
Tooling Application server pattern
Prerequisites Projects 9, familiarity with std::thread

What You Will Build

Combine epoll event loop with a thread pool: the main thread handles I/O multiplexing, worker threads process requests. This is how production servers handle CPU-intensive work without blocking the event loop.

Why It Matters

This project builds core skills that appear repeatedly in real-world systems and tooling.

Core Challenges

  • Thread-safe work queue → maps to mutex + condition variable
  • Distributing work to threads → maps to producer-consumer pattern
  • Returning results to event loop → maps to eventfd for thread wakeup
  • Graceful shutdown → maps to poison pills, joining threads

Key Concepts

  • Thread Pools: “C++ Concurrency in Action” Chapter 9 - Williams
  • Condition Variables: “C++ Concurrency in Action” Chapter 4 - Williams
  • eventfd for Thread Wakeup: “The Linux Programming Interface” Section 22.11 - Kerrisk
  • Producer-Consumer: Classic concurrency pattern

Real-World Outcome

$ ./threadpool_server -p 8080 -t 8
Starting server on port 8080 with 8 worker threads

# Simulating CPU-intensive work (e.g., JSON parsing, crypto):
$ ./benchmark_client localhost 8080 --requests 10000
Results:
  Throughput: 15,000 req/s
  Latency p99: 8.2ms

# Compare to single-threaded:
$ ./single_thread_server -p 8080
$ ./benchmark_client localhost 8080 --requests 10000
Results:
  Throughput: 2,000 req/s  # 7.5x slower!
  Latency p99: 45ms

Implementation Guide

  1. Reproduce the simplest happy-path scenario.
  2. Build the smallest working version of the core feature.
  3. Add input validation and error handling.
  4. Add instrumentation/logging to confirm behavior.
  5. Refactor into clean modules with tests.

Milestones

  • Milestone 1: Minimal working program that runs end-to-end.
  • Milestone 2: Correct outputs for typical inputs.
  • Milestone 3: Robust handling of edge cases.
  • Milestone 4: Clean structure and documented usage.

Validation Checklist

  • Output matches the real-world outcome example
  • Handles invalid inputs safely
  • Provides clear errors and exit codes
  • Repeatable results across runs

References

  • Main guide: LEARN_CPP_NETWORK_PROGRAMMING.md
  • “C++ Concurrency in Action” by Anthony Williams