TST: Windows read_csv parallel benchmark harness (investigation only)

Manually/push-triggered GitHub Actions job that builds the perf-read_csv
parallel read_csv path on windows-2025 and reports a max_threads scaling
table.  Lives on a dedicated bench branch so it stays out of PR pandas-dev#64347's diff.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: jbrockmendel

.github/workflows/bench-read-csv-windows.yml

@@ -0,0 +1,73 @@
+# Investigation-only: manually-triggered Windows benchmark for the parallel
+# read_csv path (PR #64347).  Build recipe mirrors the `macos-windows` job in
+# unit-tests.yml (pixi env + MSVC via --vsenv).  Delete once the perf question
+# is settled.
+name: Bench read_csv parallel (Windows)
+
+on:
+  # Auto-run on every push to the dedicated bench branch.  This branch is kept
+  # separate from perf-read_csv so the tooling never lands in PR #64347's diff.
+  # A push trigger (unlike workflow_dispatch) does not require the file to live
+  # on the fork's default branch, so it "just works" when the branch is pushed.
+  push:
+    branches: [perf-read_csv-bench]
+  workflow_dispatch:
+    inputs:
+      environment:
+        description: Pixi environment (Python version)
+        type: choice
+        default: py313
+        options: [py311, py312, py313, py314]
+      n_rows:
+        description: Rows in the generated CSV (8 large-int columns)
+        default: "2000000"
+      threads:
+        description: Space-separated max_threads values to benchmark
+        default: "1 2 4"
+      n_runs:
+        description: Timed runs per thread count
+        default: "7"
+      n_warmup:
+        description: Warmup runs per thread count (discarded)
+        default: "2"
+
+permissions:
+  contents: read
+
+jobs:
+  bench:
+    runs-on: windows-2025
+    timeout-minutes: 90
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          fetch-depth: 0
+
+      - name: Create virtual environment with Pixi
+        uses: ./.github/actions/setup-pixi
+        with:
+          environment: ${{ inputs.environment }}
+
+      - name: Remove link.EXE for Windows
+        # https://github.com/Quansight-Labs/uarray/pull/310#issuecomment-3872989816
+        run: rm /c/Program\ Files/Git/usr/bin/link.EXE
+        shell: bash -euox pipefail {0}
+
+      - name: Build pandas
+        run: |
+          pixi run \
+            --environment ${{ inputs.environment }} \
+            build-pandas \
+            --editable \
+            '-Csetup-args="--vsenv"'
+        shell: bash -euox pipefail {0}
+
+      - name: Run benchmark
+        env:
+          BENCH_N_ROWS: ${{ inputs.n_rows }}
+          BENCH_THREADS: ${{ inputs.threads }}
+          BENCH_N_RUNS: ${{ inputs.n_runs }}
+          BENCH_N_WARMUP: ${{ inputs.n_warmup }}
+        run: pixi run --environment ${{ inputs.environment }} python scripts/bench_read_csv_parallel.py
+        shell: bash -euox pipefail {0}

scripts/bench_read_csv_parallel.py

@@ -0,0 +1,126 @@
+"""Benchmark the parallel read_csv path (PR #64347) across max_threads values.
+
+Investigation-only helper for the Windows perf discussion.  Generates a CSV of
+large integers (mirroring the bench_csv file used in the PR thread), then times
+``pd.read_csv`` at each requested ``mode.max_threads`` value.
+
+IMPORTANT METHODOLOGY NOTE
+--------------------------
+These are **warm-cache** numbers: the file is read straight after being
+written, so it is resident in the OS page cache, and there is no portable way
+to drop the page cache on Windows.  That means this script isolates the
+**CPU / lock** behaviour, not disk I/O:
+
+* If T=2 is still *slower* than T=1 here (warm cache), the regression is a
+  genuine in-process contention point (the shared-mmap working-set lock
+  hypothesis), and a code change is warranted.
+* If T=2 is *not* slower warm, then the inversion seen on a laptop is disk
+  bound, and the fix is to gate/document rather than rewrite the tokenizer
+  path.  Settling the disk question needs the AWS storage-tier run, not this.
+
+Run via the ``bench-read-csv-windows.yml`` workflow, or locally:
+
+    BENCH_N_ROWS=2000000 BENCH_THREADS="1 2 4" python scripts/bench_read_csv_parallel.py
+"""
+
+from __future__ import annotations
+
+import os
+import statistics
+import time
+
+import numpy as np
+
+import pandas as pd
+
+# The parallel read_csv path only engages above a size threshold (currently
+# 50 MB; see _PARALLEL_READ_MIN_BYTES in pandas/io/parsers/readers.py).  Every
+# other eligibility gate (C engine, uncompressed local path, integer header) is
+# satisfied by this benchmark's call, so a plain size check is a sufficient
+# guard against silently measuring the serial fallback -- and avoids importing
+# a private pandas helper.
+PARALLEL_MIN_BYTES = 50 * 1024 * 1024
+
+N_COLS = 8
+N_ROWS = int(os.environ.get("BENCH_N_ROWS", "2000000"))
+N_RUNS = int(os.environ.get("BENCH_N_RUNS", "7"))
+N_WARMUP = int(os.environ.get("BENCH_N_WARMUP", "2"))
+THREADS = [int(tok) for tok in os.environ.get("BENCH_THREADS", "1 2 4").split()]
+PATH = os.environ.get("BENCH_PATH", "bench_data.csv")
+
+
+def generate_file() -> float:
+    """Write an 8-column large-integer CSV; return its size in MB."""
+    rng = np.random.default_rng(0)
+    data = rng.integers(10**15, 10**18, size=(N_ROWS, N_COLS), dtype=np.int64)
+    pd.DataFrame(data).to_csv(PATH, index=False, header=False)
+    return os.path.getsize(PATH) / 1e6
+
+
+def time_read(max_threads: int) -> list[float]:
+    """Return per-run wall times (ms) for read_csv at *max_threads*."""
+    pd.options.mode.max_threads = max_threads
+
+    def one_read() -> float:
+        start = time.perf_counter()
+        pd.read_csv(PATH, header=None)
+        return (time.perf_counter() - start) * 1000
+
+    for _ in range(N_WARMUP):
+        one_read()
+    return [one_read() for _ in range(N_RUNS)]
+
+
+def main() -> None:
+    print(f"os.cpu_count() = {os.cpu_count()}")
+    size_mb = generate_file()
+    print(f"generated {PATH}: {size_mb:.1f} MB, {N_ROWS:,} rows x {N_COLS} cols")
+
+    # Guard against silently benchmarking the serial fallback path.
+    if os.path.getsize(PATH) < PARALLEL_MIN_BYTES:
+        raise SystemExit(
+            "ERROR: generated file is below the parallel-path size threshold -- "
+            "the benchmark would measure the serial path.  Increase BENCH_N_ROWS."
+        )
+    print("parallel path eligible: OK\n")
+
+    results = []
+    baseline = None
+    for n_threads in THREADS:
+        times = time_read(n_threads)
+        best = min(times)
+        median = statistics.median(times)
+        if baseline is None:
+            baseline = best
+        speedup = baseline / best
+        results.append((n_threads, best, median, speedup))
+        print(
+            f"T={n_threads:>2}  best={best:7.1f}ms  "
+            f"median={median:7.1f}ms  speedup={speedup:.2f}x"
+        )
+
+    table = [
+        "| Threads | best (ms) | median (ms) | speedup vs T=1 |",
+        "|--:|--:|--:|--:|",
+    ]
+    for n_threads, best, median, speedup in results:
+        table.append(f"| {n_threads} | {best:.1f} | {median:.1f} | {speedup:.2f}x |")
+    markdown = "\n".join(table)
+
+    summary_path = os.environ.get("GITHUB_STEP_SUMMARY")
+    if summary_path:
+        with open(summary_path, "a", encoding="utf-8") as handle:
+            handle.write("## read_csv parallel benchmark (warm cache)\n\n")
+            handle.write(f"- runner cores: `{os.cpu_count()}`\n")
+            handle.write(f"- file: {size_mb:.1f} MB, {N_ROWS:,} rows x {N_COLS} cols\n")
+            handle.write(f"- Python env: `{os.environ.get('BENCH_ENV', 'n/a')}`\n\n")
+            handle.write(markdown + "\n\n")
+            handle.write(
+                "_Warm-cache numbers: isolates CPU/lock behaviour, not disk I/O. "
+                "A T=2 inversion here points to in-process contention; no "
+                "inversion means the laptop result is disk bound._\n"
+            )
+
+
+if __name__ == "__main__":
+    main()