perf: cache hardware detection and optimize warm-path reuse (2/4)

[davidberenstein1957]

Summary

Part 2/4 of the tracker performance stack. Depends on #1251.

cc @inimaz — this is the hardware-cache layer of the #1246 split.

Adds process-level hardware reuse and faster detection so repeat tracker runs in the same Python process skip repeated probing:

• New hardware_cache.py with HardwareKind enum and per-process setup cache
• Reuse CPU/GPU/RAM detection across tracker instances (get_or_run_setup)
• Cache probe results via @lru_cache (Power Gadget, PowerMetrics, NVIDIA, ROCm)
• Platform-aware CPU backend order (Mac ARM prefers fast cpu_load before PowerMetrics)
• Parallel CPU/GPU setup with ThreadPoolExecutor
• Global cpu_percent prime once per process for cpu_load mode
• PowerMetrics sudo check timeout (3 s)
• FAQ note on warm hardware reuse within one process

Benchmarks (measured locally, offline Mac ARM, 2026-06-21)

Cumulative with #1251; fresh subprocess for cold metrics.

Metric	master	#1251 only	#1251 + this PR	Δ vs master
Tracker __init__ p50	190 ms	1.9 ms	1.2 ms	~99% faster
Cold lifecycle p50 (init→start→stop)	1,685 ms	1,767 ms	408 ms	~76% faster (~4×)
Warm lifecycle best (same process)	1,565 ms	1,561 ms	4.8 ms	~325× faster
CLI monitor subprocess p50	850 ms	786 ms	694 ms	~18% faster

Stack

1. perf: defer tracker initialization and slim import path (1/4) #1251 — lazy initialization & import slimming
2. This PR — hardware detection cache & warm-path reuse
3. perf: defer API run creation until first emission upload (3/4) #1253 — lazy API run creation
4. perf: speed up CLI monitor startup and fix wrapped commands (4/4) #1254 — CLI monitor startup

CI / quality

• pre-commit run on all changed files — passed
• pytest tests/test_hardware_cache.py tests/test_resource_tracker.py tests/test_cpu.py tests/test_powermetrics.py tests/test_gpu.py — 106 passed
• Full stacked suite (perf: speed up CLI monitor startup and fix wrapped commands (4/4) #1254 tip) — 535 passed locally

Test plan

• Reviewer: second tracker in same process should reuse cached hardware, not re-probe

Replaces

Split from #1246.

[codecov]

Codecov Report

❌ Patch coverage is 97.23502% with 6 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.61%. Comparing base (aea5d20) to head (c8aee4e).

Files with missing lines	Patch %	Lines
codecarbon/core/resource_tracker.py	88.00%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1252      +/-   ##
==========================================
+ Coverage   89.39%   89.61%   +0.21%     
==========================================
  Files          47       48       +1     
  Lines        4565     4757     +192     
==========================================
+ Hits         4081     4263     +182     
- Misses        484      494      +10     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[davidberenstein1957]

@inimaz — #1246 has been split into this 4-PR stack for easier review. Benchmarks in the description are measured locally (Mac ARM, 2026-06-21); pre-commit and tests pass on each branch. Please start with #1251.

[davidberenstein1957]

Rebased on #1251 + conftest hardening to reset probe lru_cache state between tests.

Verified locally: 530 passed, pre-commit clean.

[davidberenstein1957]

@inimaz — #1251 is merged. This PR has been rebased onto the updated stack. CI and local tests pass — ready for your review.

[davidberenstein1957]

Added tests to bring hardware_cache.py and resource_tracker.py to 100% patch coverage locally (537 passed). This should resolve the codecov/project gap.

[inimaz]

NIce thanks @davidberenstein1957 !