Add CLI flags to run-benchmark.sh and rename *_TASKSET to *_CPUSET for Docker-style CPU pinning

Author: franz1981

benchmark-runner/README.md

@@ -49,45 +49,45 @@ The `run-benchmark.sh` script will automatically build the JAR if missing.
 
 ## Configuration
 
-All configuration is via environment variables:
+Configuration via CLI flags (preferred) or environment variables (fallback). CLI flags take precedence.
+
+Run `./run-benchmark.sh --help` for the full list.
+
+### Server
+| CLI flag | Env var | Default | Description |
+|----------|---------|---------|-------------|
+| `--mode` | `SERVER_MODE` | NON_VIRTUAL_NETTY | Mode: NON_VIRTUAL_NETTY, REACTIVE, VIRTUAL_NETTY, NETTY_SCHEDULER |
+| `--threads` | `SERVER_THREADS` | 2 | Number of event loop threads |
+| `--mockless` | `SERVER_MOCKLESS` | false | Skip mock server; do Jackson work inline |
+| `--io` | `SERVER_IO` | epoll | I/O type: epoll, nio, io_uring |
+| `--poller-mode` | `SERVER_POLLER_MODE` | | jdk.pollerMode: 1, 2, or 3 |
+| `--fj-parallelism` | `SERVER_FJ_PARALLELISM` | | ForkJoinPool parallelism |
+| `--fj-affinity` | `SERVER_FJ_AFFINITY` | false | FJ scheduler affinity |
+| `--server-cpuset` | `SERVER_CPUSET` | 2,3 | CPU pinning |
+| `--jvm-args` | `SERVER_JVM_ARGS` | | Additional JVM arguments |
 
 ### Mock Server
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `MOCK_PORT` | 8080 | Mock server port |
-| `MOCK_THINK_TIME_MS` | 1 | Simulated processing delay (ms) |
-| `MOCK_THREADS` | auto | Number of Netty threads (empty = available processors) |
-| `MOCK_TASKSET` | 4,5,6,7 | CPU affinity (e.g., "0-1") |
-
-### Handoff Server
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `SERVER_PORT` | 8081 | Server port |
-| `SERVER_THREADS` | 2 | Number of event loop threads |
-| `SERVER_MODE` | NON_VIRTUAL_NETTY | Server mode: NON_VIRTUAL_NETTY, REACTIVE, VIRTUAL_NETTY, NETTY_SCHEDULER |
-| `SERVER_MOCKLESS` | false | Skip mock server; do Jackson work inline |
-| `SERVER_IO` | epoll | I/O type: epoll, nio, or io_uring |
-| `SERVER_TASKSET` | 2,3 | CPU affinity (e.g., "2-5") |
-| `SERVER_JVM_ARGS` | | Additional JVM arguments |
-| `SERVER_POLLER_MODE` | 3 | jdk.pollerMode value: 1, 2, or 3 |
-| `SERVER_FJ_PARALLELISM` | | ForkJoinPool parallelism (empty = JVM default) |
+| CLI flag | Env var | Default | Description |
+|----------|---------|---------|-------------|
+| `--mock-port` | `MOCK_PORT` | 8080 | Mock server port |
+| `--mock-think-time` | `MOCK_THINK_TIME_MS` | 1 | Simulated processing delay (ms) |
+| `--mock-threads` | `MOCK_THREADS` | 1 | Number of Netty threads |
+| `--mock-cpuset` | `MOCK_CPUSET` | 4,5 | CPU pinning |
 
 ### Load Generator
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `LOAD_GEN_CONNECTIONS` | 100 | Number of connections |
-| `LOAD_GEN_THREADS` | 2 | Number of threads |
-| `LOAD_GEN_RATE` | | Target rate (empty = max throughput with wrk) |
-| `LOAD_GEN_TASKSET` | 0,1 | CPU affinity (e.g., "6-7") |
-| `LOAD_GEN_URL` | http://localhost:8081/fruits | Target URL |
+| CLI flag | Env var | Default | Description |
+|----------|---------|---------|-------------|
+| `--connections` | `LOAD_GEN_CONNECTIONS` | 100 | Number of connections |
+| `--load-threads` | `LOAD_GEN_THREADS` | 2 | Number of threads |
+| `--duration` | `LOAD_GEN_DURATION` | 30s | Test duration |
+| `--rate` | `LOAD_GEN_RATE` | | Target rate for wrk2 (omit for max throughput) |
+| `--load-cpuset` | `LOAD_GEN_CPUSET` | 0,1 | CPU pinning |
 
 ### Timing
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `WARMUP_DURATION` | 10s | Warmup duration (no profiling) |
-| `TOTAL_DURATION` | 30s | Total test duration (steady-state must be >= 20s) |
-| `PROFILING_DELAY_SECONDS` | 5 | Delay before starting profiling/perf/JFR |
-| `PROFILING_DURATION_SECONDS` | 10 | Profiling/perf/JFR duration in seconds |
+| CLI flag | Env var | Default | Description |
+|----------|---------|---------|-------------|
+| `--warmup` | `WARMUP_DURATION` | 10s | Warmup duration |
+| `--total-duration` | `TOTAL_DURATION` | 30s | Total test duration (steady-state >= 20s) |
 
 ### Profiling
 | Variable | Default | Description |
@@ -156,77 +156,43 @@ perf stat uses `PROFILING_DELAY_SECONDS` and `PROFILING_DURATION_SECONDS`.
 
 ```bash
 # Custom scheduler mode
-JAVA_HOME=/path/to/jdk \
-SERVER_MODE=NETTY_SCHEDULER \
-./run-benchmark.sh
+./run-benchmark.sh --mode netty_scheduler
 
-# Default split topology
-JAVA_HOME=/path/to/jdk \
-./run-benchmark.sh
+# Virtual Netty mode, mockless
+./run-benchmark.sh --mode virtual_netty --threads 2 --mockless
 ```
 
 ### With CPU pinning
 
 ```bash
-JAVA_HOME=/path/to/jdk \
-MOCK_TASKSET="0" \
-SERVER_TASKSET="1-4" \
-LOAD_GEN_TASKSET="5-7" \
-SERVER_THREADS=4 \
-SERVER_MODE=NETTY_SCHEDULER \
-./run-benchmark.sh
+./run-benchmark.sh --mode netty_scheduler --threads 4 \
+  --server-cpuset 1-4 --mock-cpuset 0 --load-cpuset 5-7
 ```
 
 ### With profiling
 
 ```bash
-JAVA_HOME=/path/to/jdk \
-ENABLE_PROFILER=true \
-ASYNC_PROFILER_PATH=/path/to/async-profiler \
-PROFILER_EVENT=cpu \
-SERVER_MODE=NETTY_SCHEDULER \
-WARMUP_DURATION=15s \
-TOTAL_DURATION=45s \
-./run-benchmark.sh
+./run-benchmark.sh --mode netty_scheduler \
+  --profiler --profiler-path /path/to/async-profiler \
+  --warmup 15s --total-duration 45s
 ```
 
 ### With JFR events enabled (subset)
 
 ```bash
-JAVA_HOME=/path/to/jdk \
-ENABLE_JFR=true \
-JFR_EVENTS=NettyRunIo,VirtualThreadTaskRuns \
-SERVER_MODE=NETTY_SCHEDULER \
-./run-benchmark.sh
+./run-benchmark.sh --mode netty_scheduler --jfr --jfr-events NettyRunIo,VirtualThreadTaskRuns
 ```
 
 ### Rate-limited test with wrk2
 
 ```bash
-JAVA_HOME=/path/to/jdk \
-LOAD_GEN_RATE=10000 \
-LOAD_GEN_CONNECTIONS=200 \
-TOTAL_DURATION=60s \
-WARMUP_DURATION=15s \
-./run-benchmark.sh
-```
-
-### Netty on ForkJoinPool mode
-
-```bash
-JAVA_HOME=/path/to/jdk \
-SERVER_MODE=VIRTUAL_NETTY \
-SERVER_THREADS=2 \
-./run-benchmark.sh
+./run-benchmark.sh --rate 10000 --connections 200 --total-duration 60s --warmup 15s
 ```
 
-### With pidstat monitoring
+### Mixed: CLI flags + env vars
 
 ```bash
-JAVA_HOME=/path/to/jdk \
-ENABLE_PIDSTAT=true \
-PIDSTAT_INTERVAL=1 \
-./run-benchmark.sh
+SERVER_JVM_ARGS="-XX:+PrintGCDetails" ./run-benchmark.sh --mode virtual_netty --threads 2
 ```
 
 ## Output