Skip to content

A GPU task manager for Windows, Linux, and WSL: per-process VRAM, GPU activity, and LLM model/KV-cache insights (Windows AMD and NVIDIA).

Python

Fix macOS review findings from Claude and Codex

Sameh Khamis020745de1f2e
diff --git a/README.md b/README.md
index 78c485d..120403f 100644
--- a/README.md
+++ b/README.md
@@ -210,15 +210,23 @@ macOS exposes without root:
|---|---|---|
| GPU memory (header) | IOAccelerator `PerformanceStatistics`: `Alloc system memory` (all GPU allocations) out of physical RAM | device |
| GPU% (header) | `Device Utilization %` | device |
-| GPU% | Each Metal client (`AGXDeviceUserClient`) names its creator PID and keeps a cumulative `accumulatedGPUTime`; the rate between samples | every process |
+| GPU% | Each Metal client (`AGXDeviceUserClient`) names its creator PID and keeps a cumulative `accumulatedGPUTime`; the rate between samples, per client (a closed client never hides the others' work) | every process |
| VRAM | `footprint`: the process's memory macOS charges to graphics (the `(graphics)` categories: Metal buffers, textures) | your own processes |
| Runtime, model files | Mapped files from `proc_pidinfo` region walks (psutil has no memory maps on macOS): `libggml*.dylib`, `libllama*.dylib`, `libmlx*.dylib`, `libtorch_cpu.dylib`, the Metal driver bundle | your own processes |
Other users' processes (WindowServer, system daemons) show GPU% with memory `n/a`: `footprint` needs
-root for them. Idle ones are left out of the table, except WindowServer. `footprint` takes ~70 ms per
-process, so it runs in a background thread, busiest process first; a new process shows `n/a` for a
-second or two until its first measurement. Spill, paged, clocks, power, and temperature are not
-available.
+root for them. Idle ones are left out of the table, except WindowServer. Run with `sudo` to measure
+every process's memory. `footprint` takes ~70 ms per process, so it runs in a background thread:
+busy processes and new ones every pass (~2 s), idle ones every 30 s. A new process shows `n/a` for a
+second or two until its first measurement; a single failed measurement keeps the last size, and three
+in a row back off for a minute. Measurements are tied to the process's start time, so a reused PID
+never shows the previous process's numbers.
+
+Metal reports one GPU time per process, with no 3D/compute/copy/video split, so those columns show
+`n/a`; a Metal process above 10% GPU is classified `3D/game` unless something more specific applies
+(AI runtime, browser, compositor). Spill, paged, clocks, power, and temperature are not available, so
+the chart picker offers only GPU and GPU memory. Handy's log is read from
+`~/Library/Logs/com.pais.handy/handy.log`.
Live check on an M4 Mac mini (macOS 26.3.1): a PyTorch MPS job with a 2 GiB buffer and a matmul loop
showed `Python AI PyTorch+Metal 3.06 GB 99%`, with device utilization at 99% and allocated GPU
diff --git a/src/gputaskman/app.py b/src/gputaskman/app.py
index 570d103..934224a 100644
--- a/src/gputaskman/app.py
+++ b/src/gputaskman/app.py
@@ -17,7 +17,7 @@ from textual.screen import ModalScreen
from textual.widgets import DataTable, Footer, Markdown, Select, Static
from textual.worker import get_current_worker
-from .collector import Collector, ProcRow, Snapshot
+from .collector import BACKEND, Collector, ProcRow, Snapshot
from .llm import gb
from .nvml import NvDevice, format_metric
from .report import METAL_NOTE, WSL_EMPTY, has_engine_counters, has_wddm_counters, inferred_note, vram_label, wsl_note
@@ -232,7 +232,7 @@ class GpuTaskManager(App):
with Horizontal(id="chart-controls"):
yield Static("Charts", id="chart-label")
yield Select(
- [("All charts", -1), *((name, index) for index, name in enumerate(self.CHARTS))],
+ [("All charts", -1), *((self.CHARTS[index], index) for index in self.available_charts)],
value=-1, allow_blank=False, compact=True, id="chart-mode",
)
yield Static("Click to choose · c cycles", id="chart-hint")
@@ -390,9 +390,7 @@ class GpuTaskManager(App):
widget = self.query_one("#charts", Static)
# Reserve the border, padding, and scrollbar even before child resize events arrive.
width = max(1, self.size.width - 6)
- indices = list(range(len(self.CHARTS))) if self.chart_idx == -1 else [self.chart_idx]
- if self.snap.backend == "metal" and self.chart_idx == -1:
- indices = [i for i in indices if self.CHARTS[i] in METAL_CHARTS] # IOKit has no clocks/power/temp
+ indices = list(self.available_charts) if self.chart_idx == -1 else [self.chart_idx]
columns = min(len(indices), 3, max(1, (width + 2) // 46))
cell_width = max(1, (width - 2 * (columns - 1)) // columns)
grid = Table.grid(padding=(0, 2), pad_edge=False, expand=True)
@@ -452,6 +450,7 @@ class GpuTaskManager(App):
e = r.gpu.engines
wddm = has_wddm_counters(s, r)
engines = has_engine_counters(s, r)
+ split = engines and s.backend != "metal" # Metal reports one GPU time, no per-engine split
spill = Text(gb(r.gpu.shared) if wddm and r.gpu.shared >= 1 << 20 else "", justify="right",
style="bold red" if r.gpu.shared >= 256 << 20 and r.kind in ("LLM", "AI") else "yellow")
paged = Text(gb(r.gpu.paged_out) if wddm and r.gpu.paged_out >= 1 << 20 else "", justify="right", style="grey62")
@@ -462,9 +461,9 @@ class GpuTaskManager(App):
Text(" ".join(r.detail.runtimes[:3]), style="grey70"),
Text(vram_label(r.gpu), justify="right", style="bold" if r.gpu.attributed else "grey62"), spill, paged,
pct(r.gpu.gpu_pct if engines else None),
- pct(e.get("3d", 0) + e.get("compute", 0) if engines else None),
- pct(e.get("copy", 0) if engines else None),
- pct(e.get("decode", 0) + e.get("encode", 0) if engines else None),
+ pct(e.get("3d", 0) + e.get("compute", 0) if split else None),
+ pct(e.get("copy", 0) if split else None),
+ pct(e.get("decode", 0) + e.get("encode", 0) if split else None),
Text(r.inside, style="magenta" if r.llm else "grey62", overflow="ellipsis", no_wrap=True),
key=r.key,
)
@@ -597,8 +596,17 @@ class GpuTaskManager(App):
if self.snap:
self.render_table(self.snap)
+ @property
+ def available_charts(self) -> list[int]:
+ """Chart indices this backend has data for: IOKit (macOS) has no clocks, power, temperature or codecs."""
+ if BACKEND == "metal":
+ return [i for i, name in enumerate(self.CHARTS) if name in METAL_CHARTS]
+ return list(range(len(self.CHARTS)))
+
def action_cycle_chart(self) -> None:
- self.query_one("#chart-mode", Select).value = (self.chart_idx + 2) % (len(self.CHARTS) + 1) - 1
+ order = [-1, *self.available_charts]
+ nxt = order[(order.index(self.chart_idx) + 1) % len(order)] if self.chart_idx in order else -1
+ self.query_one("#chart-mode", Select).value = nxt
def on_select_changed(self, event: Select.Changed) -> None:
if event.select.id == "chart-mode" and isinstance(event.value, int):
diff --git a/src/gputaskman/collector.py b/src/gputaskman/collector.py
index 7589e89..b9a39d9 100644
--- a/src/gputaskman/collector.py
+++ b/src/gputaskman/collector.py
@@ -152,6 +152,7 @@ def select_nv_device(adapter: Adapter | None, devices: list[NvDevice], gpu_index
class Collector:
DEEP_TOP_N = 25 # memory-map candidates: the top N VRAM users plus anything busy
+ _mac_driver = "" # "macOS 26.3.1" on the metal backend, read once at startup
SCAN_BUDGET = 0.15 # seconds of memory-map scanning per sample; leftovers wait for the next sample
def __init__(self, gpu_index: int = 0, scan_budget: float | None = SCAN_BUDGET, host: bool = True) -> None:
@@ -159,6 +160,7 @@ class Collector:
self.adapter = select_adapter(self.adapters, gpu_index)
self.counters = GpuCounters()
self.nvml = Nvml()
+ self._mac_driver = f"macOS {macos_version()}".strip() if BACKEND == "metal" else ""
self.inspector = ProcInspector()
self.prober = ServerProber()
self.scan_budget = scan_budget # None = scan every candidate now (one-shot output)
@@ -178,13 +180,6 @@ class Collector:
self._own_start = time.time() # our NVML context is created now, not when the process started
self._host_restarted = time.time()
- def _driver(self) -> str:
- if BACKEND == "metal":
- if not hasattr(self, "_macos"):
- self._macos = f"macOS {macos_version()}".strip()
- return self._macos
- return self.nvml.driver
-
def _parent_ports(self, pid: int, depth: int = 2) -> list[int]:
d = self.inspector.get(pid)
if d.parents is None:
@@ -205,15 +200,16 @@ class Collector:
luid = self.adapter.luid if self.adapter else (next(iter(per_luid), 0))
procs = per_luid.get(luid, {})
a = adapters.get(luid)
- nvs = self.nvml.sample() if self.nvml.ok else []
- nv = select_nv_device(self.adapter, nvs, self.gpu_index)
if BACKEND == "metal":
- nv = self.counters.device # IOKit's device stats in the shape the header renders
+ nv = self.counters.device # IOKit's device stats in the shape the header renders (no NVML on macOS)
+ else:
+ nvs = self.nvml.sample() if self.nvml.ok else []
+ nv = select_nv_device(self.adapter, nvs, self.gpu_index)
total = (nv.mem_total if nv else 0) or (self.adapter.dedicated_vram if self.adapter else 0)
snap = Snapshot(
taken=time.time(), adapter=self.adapter, adapters=self.adapters, nv=nv,
- driver=self._driver(), cuda=self.nvml.cuda_version, vram_total=total,
+ driver=self._mac_driver or self.nvml.driver, cuda=self.nvml.cuda_version, vram_total=total,
vram_used=int(a.dedicated) if a else (nv.mem_used if nv else 0),
shared_used=int(a.shared) if a else 0, backend=BACKEND,
)
diff --git a/src/gputaskman/handy.py b/src/gputaskman/handy.py
index 737d902..8c6c52b 100644
--- a/src/gputaskman/handy.py
+++ b/src/gputaskman/handy.py
@@ -122,7 +122,7 @@ def inspect_handy(
if sys.platform == "win32":
default_data = os.environ.get("APPDATA", "")
default_local = os.environ.get("LOCALAPPDATA", "")
- elif sys.platform == "darwin": # Tauri's app data dir on macOS (logs/ location unverified)
+ elif sys.platform == "darwin": # Tauri: app data in Application Support, logs in ~/Library/Logs/<identifier>
default_data = default_local = os.path.join(os.path.expanduser("~"), "Library", "Application Support")
else: # Tauri keeps both the settings store and logs/ under the XDG data dir on Linux
default_data = default_local = os.environ.get("XDG_DATA_HOME") or os.path.join(
@@ -130,7 +130,10 @@ def inspect_handy(
appdata = default_data if appdata is None else appdata
localappdata = default_local if localappdata is None else localappdata
settings_path = os.path.join(appdata, "com.pais.handy", "settings_store.json")
- log_path = os.path.join(localappdata, "com.pais.handy", "logs", "handy.log")
+ if sys.platform == "darwin" and localappdata == default_local:
+ log_path = os.path.join(os.path.expanduser("~"), "Library", "Logs", "com.pais.handy", "handy.log")
+ else:
+ log_path = os.path.join(localappdata, "com.pais.handy", "logs", "handy.log")
selected = _selected_model(settings_path)
event = _last_model_event(log_path, process_started)
if not selected and not event:
diff --git a/src/gputaskman/macos.py b/src/gputaskman/macos.py
index 99f63e1..8c93d56 100644
--- a/src/gputaskman/macos.py
+++ b/src/gputaskman/macos.py
@@ -70,15 +70,17 @@ def parse_accelerator(entries: list | None) -> DeviceStats | None:
return None
-def parse_clients(entries: list | None) -> dict[int, int]:
- """{pid: accumulated GPU ns} summed over that process's Metal clients."""
- out: dict[int, int] = defaultdict(int)
- for e in entries or []:
+def parse_clients(entries: list | None) -> dict[int, dict[int, int]]:
+ """{pid: {client id: accumulated GPU ns}}. Rates are taken per client: a closed client takes its
+ accumulated time with it, so per-process sums would drop and hide real work."""
+ out: dict[int, dict[int, int]] = defaultdict(dict)
+ for i, e in enumerate(entries or []):
m = _CREATOR.match(str(e.get("IOUserClientCreator", "")))
if not m:
continue
- pid = int(m[1])
- out[pid] += sum(int(u.get("accumulatedGPUTime", 0)) for u in e.get("AppUsage") or [] if isinstance(u, dict))
+ cid = e.get("IORegistryEntryID", -1 - i)
+ out[int(m[1])][cid] = sum(int(u.get("accumulatedGPUTime", 0))
+ for u in e.get("AppUsage") or [] if isinstance(u, dict))
return dict(out)
@@ -90,7 +92,7 @@ def graphics_bytes(process: dict) -> int:
def physical_memory() -> int:
try:
return os.sysconf("SC_PHYS_PAGES") * os.sysconf("SC_PAGE_SIZE")
- except (ValueError, OSError):
+ except (ValueError, OSError, AttributeError): # no os.sysconf on Windows
return 0
@@ -117,18 +119,33 @@ def _owner(pid: int) -> int | None:
return None
+def _identity(pid: int) -> float | None:
+ """Process start time: tells a reused PID from the process that had it before."""
+ try:
+ import psutil
+ return psutil.Process(pid).create_time()
+ except Exception:
+ return None
+
+
class FootprintPoller:
- """footprint(1) takes ~70 ms per process, too slow for the refresh loop: poll the own-user GPU clients in
- a background thread, busiest first, and keep the latest graphics size per PID."""
+ """footprint(1) takes ~70 ms per process, too slow for the refresh loop, so a background thread measures
+ the targets: busy or not-yet-measured processes every pass (~2 s), idle ones every 30 s. Results are tied
+ to a process identity (PID + start time), so a measurement never lands on a reused PID."""
CYCLE = 2.0 # seconds between passes
- DENIED_RETRY = 60.0
+ IDLE_EVERY = 30.0 # re-measure idle processes this often
+ FAIL_LIMIT = 3 # consecutive failures before backing off (one timeout under load is not "denied")
+ FAIL_RETRY = 60.0
- def __init__(self, run=subprocess.run) -> None:
+ def __init__(self, run=subprocess.run, clock=time.monotonic) -> None:
self._run = run
- self._targets: list[int] = []
- self._sizes: dict[int, tuple[int, float]] = {}
- self._denied: dict[int, float] = {}
+ self._clock = clock
+ self._targets: dict[int, tuple[object, bool]] = {} # pid -> (identity, busy), busiest first
+ self._sizes: dict[int, tuple[object, int]] = {} # pid -> (identity, graphics bytes)
+ self._due: dict[int, float] = {}
+ self._fails: dict[int, int] = {}
+ self._retry: dict[int, float] = {}
self._lock = threading.Lock()
self._wake = threading.Event()
self._passed = threading.Event() # set after each completed pass
@@ -140,16 +157,24 @@ class FootprintPoller:
self._thread = threading.Thread(target=self._loop, name="macos-footprint", daemon=True)
self._thread.start()
- def set_targets(self, pids: list[int]) -> None:
+ def set_targets(self, targets: list[tuple[int, object, bool]]) -> None:
+ """[(pid, identity, busy)], busiest first. Anything else, or a PID whose identity changed, is forgotten."""
with self._lock:
- self._targets = list(pids)
- self._sizes = {p: v for p, v in self._sizes.items() if p in pids}
+ self._targets = {pid: (ident, busy) for pid, ident, busy in targets}
+ for store in (self._sizes, self._due, self._fails, self._retry):
+ for pid in list(store):
+ if pid not in self._targets:
+ del store[pid]
+ for pid, (ident, _) in self._targets.items():
+ if pid in self._sizes and self._sizes[pid][0] != ident: # reused PID
+ for store in (self._sizes, self._due, self._fails, self._retry):
+ store.pop(pid, None)
self._wake.set()
- def get(self, pid: int) -> int | None:
+ def get(self, pid: int, identity: object = None) -> int | None:
with self._lock:
hit = self._sizes.get(pid)
- return hit[0] if hit else None
+ return hit[1] if hit and hit[0] == identity else None
def measure(self, pid: int) -> int | None:
with tempfile.TemporaryDirectory() as d:
@@ -168,20 +193,29 @@ class FootprintPoller:
def poll_once(self) -> None:
with self._lock:
- targets = list(self._targets)
- now = time.time()
- for pid in targets:
+ targets = list(self._targets.items())
+ for pid, (ident, busy) in targets:
if self._stop:
return
- if now - self._denied.get(pid, -1e9) < self.DENIED_RETRY:
- continue
+ now = self._clock()
+ with self._lock:
+ if self._retry.get(pid, 0) > now:
+ continue
+ if not busy and pid in self._sizes and self._due.get(pid, 0) > now:
+ continue
size = self.measure(pid)
with self._lock:
+ if self._targets.get(pid, (None,))[0] != ident:
+ continue # exited or reused while footprint ran: don't resurrect it
if size is None:
- self._denied[pid] = now
- self._sizes.pop(pid, None)
+ self._fails[pid] = self._fails.get(pid, 0) + 1
+ if self._fails[pid] >= self.FAIL_LIMIT: # other user's process, or footprint keeps failing
+ self._retry[pid] = now + self.FAIL_RETRY
+ self._sizes.pop(pid, None)
else:
- self._sizes[pid] = (size, time.time())
+ self._sizes[pid] = (ident, size)
+ self._fails.pop(pid, None)
+ self._due[pid] = now + self.IDLE_EVERY
def wait_pass(self, timeout: float) -> bool:
self._passed.clear()
@@ -189,10 +223,10 @@ class FootprintPoller:
def _loop(self) -> None:
while not self._stop:
- start = time.time()
+ start = self._clock()
self.poll_once()
self._passed.set()
- self._wake.wait(max(self.CYCLE - (time.time() - start), 0.2))
+ self._wake.wait(max(self.CYCLE - (self._clock() - start), 0.2))
self._wake.clear()
def close(self) -> None:
@@ -204,14 +238,19 @@ class MacCounters:
"""Same interface as pdh.GpuCounters: sample() -> ({adapter key: {pid: ProcGpu}}, {adapter key: AdapterGpu}).
`device` carries the device-wide stats in the NvDevice shape the header already renders."""
- def __init__(self, poller: FootprintPoller | None = None, uid: int | None = None) -> None:
+ def __init__(self, poller: FootprintPoller | None = None, uid: int | None = None, root: bool | None = None,
+ identity=_identity, owner=_owner) -> None:
self.ok = True
self.device: NvDevice | None = None
- self._prev: dict[int, tuple[int, float]] = {} # pid -> (gpu ns, wall time)
self._uid = os.getuid() if uid is None else uid
+ # As root footprint can read every process, so every process is measurable (not only uid 0's).
+ self._root = (os.geteuid() == 0) if root is None else root
+ self._identity, self._owner = identity, owner
+ self._prev: dict[int, tuple[object, dict[int, int]]] = {} # pid -> (identity, {client id: ns})
+ self._last: float | None = None # monotonic time of the previous sample
self._owners: dict[int, int | None] = {}
- self.poller = poller or FootprintPoller()
self._names: dict[int, str] = {}
+ self.poller = poller or FootprintPoller()
self.poller.start()
self.sample() # baseline: GPU% is a rate, like the WDDM counters' first collection
@@ -230,32 +269,46 @@ class MacCounters:
def sample(self, accel: list | None = None, clients: list | None = None,
now: float | None = None) -> tuple[dict[int, dict[int, ProcGpu]], dict[int, AdapterGpu]]:
- now = time.time() if now is None else now
+ now = time.monotonic() if now is None else now # a rate: immune to wall-clock adjustments
accel = _ioreg("-d", "1", "-c", "IOAccelerator") if accel is None else accel
clients = _ioreg("-l", "-c", "AGXDeviceUserClient") if clients is None else clients
procs: dict[int, dict[int, ProcGpu]] = defaultdict(dict)
adapters: dict[int, AdapterGpu] = defaultdict(AdapterGpu)
dev = parse_accelerator(accel)
- if dev is not None:
+ if dev is None:
+ self.device = None # no reading this time: never keep showing the last one as current
+ else:
adapters[ADAPTER_KEY].dedicated = float(dev.allocated)
self.device = NvDevice(index=0, name=dev.model, driver_model="Metal", mem_total=physical_memory(),
mem_used=dev.allocated, util_gpu=dev.utilization)
- times = parse_clients(clients)
- own: list[tuple[float, int]] = []
- for pid, ns in times.items():
+ per_pid = parse_clients(clients)
+ elapsed = now - self._last if self._last is not None else None
+ targets: list[tuple[float, int, object]] = []
+ current: dict[int, tuple[object, dict[int, int]]] = {}
+ for pid, times in per_pid.items():
+ ident = self._identity(pid)
prev = self._prev.get(pid)
+ if prev is None or prev[0] != ident:
+ prev_times = {}
+ self._owners.pop(pid, None) # new or reused PID: re-read its owner and name
+ self._names.pop(pid, None)
+ else:
+ prev_times = prev[1]
+ current[pid] = (ident, times)
pct = 0.0
- if prev is not None and now > prev[1] and ns >= prev[0]:
- pct = min((ns - prev[0]) / 1e9 / (now - prev[1]) * 100.0, 100.0)
+ if elapsed and elapsed > 0:
+ # A client that appeared since the last sample did all of its work in this interval.
+ busy_ns = sum(max(ns - prev_times.get(cid, 0), 0) for cid, ns in times.items())
+ pct = min(busy_ns / 1e9 / elapsed * 100.0, 100.0)
if pid not in self._owners:
- self._owners[pid] = _owner(pid)
- mine = self._owners[pid] == self._uid
+ self._owners[pid] = self._owner(pid)
+ mine = self._root or self._owners[pid] == self._uid
g = ProcGpu()
if pct:
g.engines["gpu"] = pct
if mine:
- own.append((pct, pid))
- size = self.poller.get(pid)
+ targets.append((pct, pid, ident))
+ size = self.poller.get(pid, ident)
if size is None:
g.attributed = False # not measured yet (or footprint failed): unknown, not zero
else:
@@ -265,10 +318,11 @@ class MacCounters:
if pct < 0.5 and self._name(pid).lower() not in ALWAYS_SHOWN:
continue
procs[ADAPTER_KEY][pid] = g
- self._prev = {pid: (ns, now) for pid, ns in times.items()}
- self._owners = {p: o for p, o in self._owners.items() if p in times}
- self._names = {p: n for p, n in self._names.items() if p in times}
- self.poller.set_targets([pid for _, pid in sorted(own, reverse=True)])
+ self._prev, self._last = current, now
+ self._owners = {p: o for p, o in self._owners.items() if p in per_pid}
+ self._names = {p: n for p, n in self._names.items() if p in per_pid}
+ targets.sort(key=lambda t: -t[0])
+ self.poller.set_targets([(pid, ident, pct >= 0.5) for pct, pid, ident in targets])
return procs, adapters
def close(self) -> None:
@@ -314,7 +368,7 @@ def memory_maps(pid: int, max_regions: int = 200_000) -> list[MappedFile]:
for processes this user can't inspect."""
lib = _load_libproc()
info, buf = _RegionInfo(), ctypes.create_string_buffer(4096)
- page = os.sysconf("SC_PAGE_SIZE")
+ page = os.sysconf("SC_PAGE_SIZE") # macOS only
files: dict[str, int] = {}
addr, n = 0, 0
while n < max_regions:
diff --git a/src/gputaskman/procinfo.py b/src/gputaskman/procinfo.py
index 902bc45..72b6f41 100644
--- a/src/gputaskman/procinfo.py
+++ b/src/gputaskman/procinfo.py
@@ -218,7 +218,7 @@ def _is_system_path(exe: str) -> bool:
if sys.platform == "win32":
return exe.startswith(os.path.normcase(os.environ.get("SystemRoot", r"C:\Windows")))
# /usr/bin/python3 is shared by every Python app: walking /usr/bin finds nothing about the process.
- return exe.startswith(_LINUX_SYSTEM_DIRS) or (sys.platform == "darwin" and exe.startswith(("/system/", "/System/")))
+ return exe.startswith(_LINUX_SYSTEM_DIRS) or (sys.platform == "darwin" and exe.startswith("/System/"))
def _data_dirs() -> list[str]:
@@ -442,4 +442,6 @@ def classify(d: ProcDetail, engines: dict[str, float]) -> str:
return "compute"
if ("D3D12" in d.runtimes or "Vulkan" in d.runtimes) and engines.get("3d", 0) > 10:
return "3D/game"
+ if "Metal" in d.runtimes and engines.get("gpu", 0) > 10 and n not in COMPOSITORS:
+ return "3D/game" # macOS: Metal reports one GPU time, no 3D/compute split
return "app"
diff --git a/tests/test_core.py b/tests/test_core.py
index f2eba50..1efdfa4 100644
--- a/tests/test_core.py
+++ b/tests/test_core.py
@@ -675,6 +675,12 @@ class ChartTests(unittest.TestCase):
class UiTests(unittest.IsolatedAsyncioTestCase):
+ def setUp(self):
+ # These snapshots are NVIDIA/WDDM ones: render them with that backend's charts on every OS (macOS too).
+ backend = patch("gputaskman.app.BACKEND", "wddm")
+ backend.start()
+ self.addCleanup(backend.stop)
+
def chart_text(self, app):
widget = app.query_one("#charts", Static)
output = io.StringIO()
diff --git a/tests/test_macos.py b/tests/test_macos.py
index 8562e8e..e4b7f28 100644
--- a/tests/test_macos.py
+++ b/tests/test_macos.py
@@ -24,27 +24,30 @@ def accel(util=28, alloc=2202157056):
"In use system memory": 13598720}}]
-def client(pid, name, *times):
- return {"IOUserClientCreator": f"pid {pid}, {name}",
- "AppUsage": [{"API": "Metal", "accumulatedGPUTime": t} for t in times]}
+def client(pid, name, *times, cid=None):
+ entry = {"IOUserClientCreator": f"pid {pid}, {name}",
+ "AppUsage": [{"API": "Metal", "accumulatedGPUTime": t} for t in times]}
+ if cid is not None:
+ entry["IORegistryEntryID"] = cid
+ return entry
class FakePoller:
- def wait_pass(self, timeout):
- return True
-
def __init__(self, sizes=None):
- self.sizes = sizes or {}
+ self.sizes = sizes or {} # pid -> bytes, for identity "same"
self.targets = []
+ def wait_pass(self, timeout):
+ return True
+
def start(self):
pass
- def set_targets(self, pids):
- self.targets = pids
+ def set_targets(self, targets):
+ self.targets = targets
- def get(self, pid):
- return self.sizes.get(pid)
+ def get(self, pid, identity=None):
+ return self.sizes.get(pid) if identity == "same" else None
def close(self):
pass
@@ -58,12 +61,12 @@ class ParseTests(unittest.TestCase):
self.assertIsNone(macos.parse_accelerator([{"model": "x"}]))
self.assertIsNone(macos.parse_accelerator(None))
- def test_gpu_time_is_summed_per_process(self):
+ def test_gpu_time_is_kept_per_client(self):
# WindowServer has several Metal clients; runningboardd has one with no usage yet
- times = macos.parse_clients([client(167, "WindowServer", 53012153708, 17704333),
- client(167, "WindowServer", 262833), client(176, "runningboardd"),
+ times = macos.parse_clients([client(167, "WindowServer", 53012153708, 17704333, cid=11),
+ client(167, "WindowServer", 262833, cid=12), client(176, "runningboardd", cid=13),
{"IOUserClientCreator": "garbage"}])
- self.assertEqual(times, {167: 53012153708 + 17704333 + 262833, 176: 0})
+ self.assertEqual(times, {167: {11: 53012153708 + 17704333, 12: 262833}, 176: {13: 0}})
def test_graphics_footprint_counts_only_graphics_categories(self):
process = {"pid": 79379, "categories": {
@@ -72,28 +75,39 @@ class ParseTests(unittest.TestCase):
"IOAccelerator": {"dirty": 65536}, "MALLOC_SMALL": {"dirty": 58 << 20}}}
self.assertEqual(macos.graphics_bytes(process), 2162163712 + 8880128)
+ def test_physical_memory_without_sysconf(self):
+ with patch.object(macos.os, "sysconf", side_effect=AttributeError, create=True):
+ self.assertEqual(macos.physical_memory(), 0) # Windows has no os.sysconf
+
class CountersTests(unittest.TestCase):
- def counters(self, sizes, owners):
+ def counters(self, sizes, owners, root=False, identities=None):
poller = FakePoller(sizes)
- with patch.object(macos, "_owner", side_effect=lambda pid: owners.get(pid)), \
- patch.object(macos, "_ioreg", return_value=[]): # the constructor's baseline sees nothing
- c = macos.MacCounters(poller=poller, uid=ME)
- c._owners = dict(owners)
+ self.identities = identities if identities is not None else {}
+ with patch.object(macos, "_ioreg", return_value=[]), \
+ patch.object(macos, "physical_memory", return_value=16 * GiB): # baseline sees nothing
+ c = macos.MacCounters(poller=poller, uid=ME, root=root,
+ identity=lambda pid: self.identities.get(pid, "same"),
+ owner=lambda pid: owners.get(pid))
c._names = {167: "WindowServer", 176: "runningboardd", 900: "backupd"}
return c, poller
+ def sample(self, c, *args, **kw):
+ with patch.object(macos, "physical_memory", return_value=16 * GiB):
+ return c.sample(*args, **kw)
+
def test_gpu_percent_memory_and_honest_unknowns(self):
owners = {79379: ME, 486: ME, 167: ROOT, 176: ROOT, 900: ROOT}
c, poller = self.counters({79379: 2162163712 + 8880128}, owners)
- first = [client(79379, "python3.13", 10 * 10**9), client(486, "wezterm-gui", 4 * 10**9),
- client(167, "WindowServer", 50 * 10**9), client(176, "runningboardd", 0),
- client(900, "backupd", 7 * 10**9)]
- c.sample(accel(), first, now=100.0)
- second = [client(79379, "python3.13", 10 * 10**9 + 1_968_000_000), client(486, "wezterm-gui", 4 * 10**9),
- client(167, "WindowServer", 50 * 10**9 + 40_000_000), client(176, "runningboardd", 0),
- client(900, "backupd", 7 * 10**9)]
- procs, adapters = c.sample(accel(99, 5494423552), second, now=102.0)
+ first = [client(79379, "python3.13", 10 * 10**9, cid=1), client(486, "wezterm-gui", 4 * 10**9, cid=2),
+ client(167, "WindowServer", 50 * 10**9, cid=3), client(176, "runningboardd", 0, cid=4),
+ client(900, "backupd", 7 * 10**9, cid=5)]
+ self.sample(c, accel(), first, now=100.0)
+ second = [client(79379, "python3.13", 10 * 10**9 + 1_968_000_000, cid=1),
+ client(486, "wezterm-gui", 4 * 10**9, cid=2),
+ client(167, "WindowServer", 50 * 10**9 + 40_000_000, cid=3), client(176, "runningboardd", 0, cid=4),
+ client(900, "backupd", 7 * 10**9, cid=5)]
+ procs, adapters = self.sample(c, accel(99, 5494423552), second, now=102.0)
per = procs[macos.ADAPTER_KEY]
self.assertAlmostEqual(per[79379].gpu_pct, 98.4) # measured: 98.4% vs Device Utilization 99%
self.assertEqual(per[79379].dedicated, 2162163712 + 8880128)
@@ -103,43 +117,102 @@ class CountersTests(unittest.TestCase):
self.assertAlmostEqual(per[167].gpu_pct, 2.0)
self.assertNotIn(176, per) # idle daemons of other users stay out of the table
self.assertNotIn(900, per)
- self.assertEqual(poller.targets, [79379, 486]) # busiest own process measured first
+ self.assertEqual(poller.targets, [(79379, "same", True), (486, "same", False)]) # busiest first
self.assertEqual(adapters[macos.ADAPTER_KEY].dedicated, 5494423552)
self.assertEqual((c.device.name, c.device.util_gpu, c.device.driver_model), ("Apple M4", 99, "Metal"))
- def test_counter_reset_is_not_negative(self):
+ def test_a_closed_client_does_not_hide_work_on_the_others(self):
c, _ = self.counters({}, {1: ME})
- c.sample(accel(), [client(1, "a", 5 * 10**9)], now=1.0)
- procs, _ = c.sample(accel(), [client(1, "a", 1 * 10**9)], now=2.0) # PID reused
- self.assertEqual(procs[macos.ADAPTER_KEY][1].gpu_pct, 0.0)
+ self.sample(c, accel(), [client(1, "a", 10 * 10**9, cid=7), client(1, "a", 1 * 10**9, cid=8)], now=1.0)
+ procs, _ = self.sample(c, accel(), [client(1, "a", 2 * 10**9, cid=8)], now=2.0) # 7 closed; 8 ran 1 s
+ self.assertAlmostEqual(procs[macos.ADAPTER_KEY][1].gpu_pct, 100.0)
+
+ def test_a_reused_pid_starts_over(self):
+ c, poller = self.counters({1: 3 * GiB}, {1: ROOT}, identities={1: "old"})
+ self.sample(c, accel(), [client(1, "a", 5 * 10**9, cid=7)], now=1.0)
+ self.identities[1] = "same" # PID 1 now belongs to a new process of this user
+ c._owner = lambda pid: ME
+ procs, _ = self.sample(c, accel(), [client(1, "a", 1 * 10**9, cid=9)], now=2.0)
+ g = procs[macos.ADAPTER_KEY][1]
+ self.assertAlmostEqual(g.gpu_pct, 100.0) # its new client's 1 s, not a negative delta from the old one
+ self.assertTrue(g.attributed) # owner re-read: now measurable
+ self.assertEqual(poller.targets, [(1, "same", True)])
+
+ def test_root_measures_every_process(self):
+ c, poller = self.counters({}, {167: ROOT, 486: ME}, root=True)
+ self.sample(c, accel(), [client(167, "WindowServer", 0, cid=1), client(486, "wezterm-gui", 0, cid=2)], now=1.0)
+ self.assertEqual({pid for pid, _, _ in poller.targets}, {167, 486})
+
+ def test_a_failed_device_read_is_not_kept_as_current(self):
+ c, _ = self.counters({}, {})
+ self.sample(c, accel(90), [], now=1.0)
+ self.assertEqual(c.device.util_gpu, 90)
+ _, adapters = self.sample(c, [], [], now=2.0) # ioreg failed or returned nothing
+ self.assertIsNone(c.device)
+ self.assertNotIn(macos.ADAPTER_KEY, adapters)
class PollerTests(unittest.TestCase):
- def test_footprint_json_is_read_per_pid(self):
+ def footprint(self, sizes, calls):
def run(args, **kw):
- path = args[args.index("-j") + 1]
pid = int(args[-1])
- with open(path, "w", encoding="utf-8") as f:
+ calls.append(pid)
+ if sizes.get(pid) is None:
+ return # writes nothing, like footprint on a process it can't read
+ with open(args[args.index("-j") + 1], "w", encoding="utf-8") as f:
json.dump({"processes": [{"pid": pid, "categories": {
- "IOAccelerator (graphics)": {"dirty": 3 * GiB}}}]}, f)
+ "IOAccelerator (graphics)": {"dirty": sizes[pid]}}}]}, f)
+ return run
+
+ def test_footprint_json_is_read_per_pid_and_tied_to_identity(self):
+ calls = []
+ p = macos.FootprintPoller(run=self.footprint({42: 3 * GiB}, calls), clock=lambda: 0.0)
+ p.set_targets([(42, "a", True)])
+ p.poll_once()
+ self.assertEqual(p.get(42, "a"), 3 * GiB)
+ self.assertIsNone(p.get(42, "b"))
+ p.set_targets([(42, "b", True)]) # reused PID: the old size is gone
+ self.assertIsNone(p.get(42, "a"))
+
+ def test_idle_processes_are_measured_less_often(self):
+ calls, clock = [], [0.0]
+ p = macos.FootprintPoller(run=self.footprint({1: GiB, 2: GiB}, calls), clock=lambda: clock[0])
+ p.set_targets([(1, "a", True), (2, "a", False)])
+ p.poll_once()
+ clock[0] = 2.0
+ p.poll_once()
+ self.assertEqual(calls, [1, 2, 1]) # idle 2 waits IDLE_EVERY seconds
+ clock[0] = 2.0 + p.IDLE_EVERY
+ p.poll_once()
+ self.assertEqual(calls[-2:], [1, 2])
- p = macos.FootprintPoller(run=run)
- p.set_targets([42])
+ def test_one_failure_keeps_the_last_size_and_repeated_failures_back_off(self):
+ calls, sizes = [], {5: GiB}
+ p = macos.FootprintPoller(run=self.footprint(sizes, calls), clock=lambda: 0.0)
+ p.set_targets([(5, "a", True)])
p.poll_once()
- self.assertEqual(p.get(42), 3 * GiB)
+ sizes[5] = None # footprint times out once
+ p.poll_once()
+ self.assertEqual(p.get(5, "a"), GiB)
+ for _ in range(p.FAIL_LIMIT):
+ p.poll_once()
+ n = len(calls)
+ p.poll_once()
+ self.assertEqual(len(calls), n) # backing off
+ self.assertIsNone(p.get(5, "a"))
- def test_denied_processes_are_retried_later_not_every_pass(self):
- calls = []
+ def test_a_result_for_a_dropped_pid_is_discarded(self):
+ p = macos.FootprintPoller(run=lambda *a, **k: None, clock=lambda: 0.0)
+ p.set_targets([(812, "a", True)])
- def run(args, **kw):
- calls.append(args) # writes nothing, like footprint on a root process
+ def measure(pid):
+ p.set_targets([]) # the process exits while footprint runs
+ return 2 * GiB
- p = macos.FootprintPoller(run=run)
- p.set_targets([170])
- p.poll_once()
+ p.measure = measure
p.poll_once()
- self.assertEqual(len(calls), 1)
- self.assertIsNone(p.get(170))
+ p.set_targets([(812, "a", True)])
+ self.assertIsNone(p.get(812, "a"))
class ProcInfoTests(unittest.TestCase):
@@ -181,5 +254,60 @@ class ReportTests(unittest.TestCase):
self.assertIsNone(data[0]["shared_bytes"])
+class DisplayTests(unittest.IsolatedAsyncioTestCase):
+ async def test_charts_and_engine_columns_on_metal(self):
+ from gputaskman import app as app_mod
+ from gputaskman.app import GpuTaskManager
+ from textual.widgets import Select
+ row = ProcRow(42, "Game", "3D/game", ProcGpu(dedicated=GiB, engines={"gpu": 80.0}), ProcDetail(42, "Game"))
+ snap = Snapshot(taken=1, adapter=None, adapters=[], nv=None, driver="macOS 26.3.1", cuda="",
+ vram_total=16 * GiB, vram_used=3 * GiB, shared_used=0, backend="metal", procs=[row])
+ with patch.object(app_mod, "BACKEND", "metal"), patch.object(GpuTaskManager, "poll"):
+ app = GpuTaskManager()
+ async with app.run_test(size=(180, 42)) as pilot:
+ app.apply(snap)
+ await pilot.pause()
+ self.assertEqual([app.CHARTS[i] for i in app.available_charts], ["GPU", "VRAM"])
+ seen = []
+ for _ in range(3):
+ await pilot.press("c")
+ await pilot.pause()
+ seen.append(app.chart_idx)
+ self.assertEqual([app.CHARTS[i] if i >= 0 else "all" for i in seen], ["GPU", "VRAM", "all"])
+ options = [v for _, v in app.query_one("#chart-mode", Select)._options]
+ self.assertEqual(len(options), 3)
+ table = app.query_one("#procs")
+ self.assertEqual(table.get_cell("42", "GPU%").plain, "80")
+ for column in ("3D", "Copy", "Video"):
+ self.assertEqual(table.get_cell("42", column).plain, "n/a")
+
+
+class ClassifyTests(unittest.TestCase):
+ def test_busy_metal_app_is_3d_but_the_compositor_is_not(self):
+ from gputaskman.procinfo import classify
+ game = ProcDetail(42, "Game")
+ game.runtimes = ["Metal"]
+ self.assertEqual(classify(game, {"gpu": 80.0}), "3D/game")
+ self.assertEqual(classify(game, {"gpu": 3.0}), "app")
+ ws = ProcDetail(167, "WindowServer")
+ ws.runtimes = ["Metal"]
+ self.assertEqual(classify(ws, {"gpu": 80.0}), "compositor")
+
+ def test_handy_log_lives_in_library_logs_on_macos(self):
+ import tempfile
+ from pathlib import Path
+ from gputaskman import handy
+ with tempfile.TemporaryDirectory() as home:
+ logs = Path(home) / "Library" / "Logs" / "com.pais.handy"
+ logs.mkdir(parents=True)
+ seen = []
+ real = handy._last_model_event
+ with patch.object(handy.sys, "platform", "darwin"), \
+ patch.object(handy.os.path, "expanduser", side_effect=lambda p: p.replace("~", home)), \
+ patch.object(handy, "_last_model_event", side_effect=lambda path, t: seen.append(path) or real(path, t)):
+ handy.inspect_handy(0.0)
+ self.assertEqual(seen, [str(logs / "handy.log")])
+
+
if __name__ == "__main__":
unittest.main()