docs

src/performance_monitor.py

@@ -1,3 +1,57 @@
+"""
+Performance Monitor - Real-time FPS, frame time, and CPU usage tracking.
+
+This module provides the PerformanceMonitor singleton class for tracking
+application performance metrics with efficient O(1) moving averages.
+
+Key Features:
+ - FPS and frame time tracking with rolling history
+ - CPU percentage monitoring via background thread
+ - Per-component timing with start_component() / end_component()
+ - Efficient moving average using deque + running sum
+ - Thread-safe metric collection
+
+Usage:
+ perf = get_monitor()
+ perf.enabled = True
+ 
+ # In render loop:
+ perf.start_frame()
+ perf.start_component('panel_a')
+ # ... render panel A ...
+ perf.end_component('panel_a')
+ perf.end_frame()
+ 
+ # Get metrics:
+ metrics = perf.get_metrics()
+ fps = metrics['fps']
+ avg_frame_time = metrics['frame_time_ms_avg']
+
+Metrics Available:
+ - fps: Instantaneous frames per second
+ - fps_avg: Rolling average FPS
+ - last_frame_time_ms: Last frame duration in milliseconds
+ - frame_time_ms_avg: Rolling average frame time
+ - cpu_percent: Current CPU usage
+ - cpu_percent_avg: Rolling average CPU usage
+ - input_lag_ms: Input latency estimate
+ - time_<component>_ms: Per-component timing
+ - time_<component>_ms_avg: Per-component rolling average
+
+Thread Safety:
+ - All public methods are thread-safe
+ - Uses threading.Lock for state mutations
+ - Background CPU thread polls every 1 second
+
+Configuration:
+ - history_size: Number of samples for rolling averages (default: 300)
+ - sample_interval: Minimum time between history samples (default: 100ms)
+
+Integration:
+ - Instantiated as singleton via get_monitor()
+ - Used by gui_2.py for Diagnostics Panel
+ - Exposed via Hook API at /api/performance
+"""
 from __future__ import annotations
 import time
 import psutil
@@ -7,6 +61,7 @@ from collections import deque
 
 _instance: Optional[PerformanceMonitor] = None
 
+
 def get_monitor() -> PerformanceMonitor:
  global _instance
  if _instance is None: