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
"""macOS backend. Fixtures follow ioreg/footprint output measured on an M4 Mac mini (macOS 26.3.1)."""
from __future__ import annotations
import json
import plistlib
import unittest
from unittest.mock import patch
from gputaskman import macos
from gputaskman.collector import ProcRow, Snapshot
from gputaskman.pdh import ProcGpu
from gputaskman.procinfo import ProcDetail, _lib_name, _match_runtimes
from gputaskman.report import to_dict, to_text
GiB = 1 << 30
ME, ROOT = 501, 0
def accel(util=28, alloc=2202157056):
return [{"IOClass": "AGXAcceleratorG16G", "model": "Apple M4", "gpu-core-count": 10,
"PerformanceStatistics": {"Device Utilization %": util, "Renderer Utilization %": util,
"Tiler Utilization %": util, "Alloc system memory": alloc,
"In use system memory": 13598720}}]
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 __init__(self, sizes=None):
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, targets):
self.targets = targets
def get(self, pid, identity=None):
return self.sizes.get(pid) if identity == "same" else None
def close(self):
pass
class ParseTests(unittest.TestCase):
def test_ioreg_plist_round_trip(self):
entries = plistlib.loads(plistlib.dumps(accel(99, 5494423552)))
dev = macos.parse_accelerator(entries)
self.assertEqual((dev.model, dev.cores, dev.utilization, dev.allocated), ("Apple M4", 10, 99, 5494423552))
self.assertIsNone(macos.parse_accelerator([{"model": "x"}]))
self.assertIsNone(macos.parse_accelerator(None))
def test_missing_device_allocation_is_unknown_not_zero(self):
stats = accel()[0]["PerformanceStatistics"]
del stats["Alloc system memory"]
dev = macos.parse_accelerator([{"model": "Apple M4", "PerformanceStatistics": stats}])
self.assertIsNone(dev.allocated)
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, cid=11),
client(167, "WindowServer", 262833, cid=12), client(176, "runningboardd", cid=13),
{"IOUserClientCreator": "garbage"}])
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": {
"Owned physical footprint (unmapped) (graphics)": {"dirty": 2162163712, "swapped": 0},
"IOAccelerator (graphics)": {"dirty": 8880128, "swapped": 0},
"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, root=False, identities=None):
poller = FakePoller(sizes)
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, 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)
self.assertTrue(per[79379].attributed)
self.assertFalse(per[486].attributed) # own process, not measured yet: unknown, not 0
self.assertFalse(per[167].attributed) # root's WindowServer: GPU% only
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, "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_a_closed_client_does_not_hide_work_on_the_others(self):
c, _ = self.counters({}, {1: ME})
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_unknown_process_identity_disables_rate_and_footprint_attribution(self):
c, poller = self.counters({1: 3 * GiB}, {1: ME})
self.sample(c, accel(), [client(1, "a", 5 * 10**9, cid=7)], now=1.0)
self.identities[1] = None
procs, _ = self.sample(c, accel(), [client(1, "a", 6 * 10**9, cid=7)], now=2.0)
g = procs[macos.ADAPTER_KEY][1]
self.assertNotIn("engine", g.available)
self.assertFalse(g.attributed)
self.assertEqual(poller.targets, [])
self.identities[1] = "same"
procs, _ = self.sample(c, accel(), [client(1, "a", 20 * 10**9, cid=7)], now=3.0)
g = procs[macos.ADAPTER_KEY][1]
self.assertNotIn("engine", g.available) # establish a fresh baseline without a fabricated spike
procs, _ = self.sample(c, accel(), [client(1, "a", 21 * 10**9, cid=7)], now=4.0)
self.assertAlmostEqual(procs[macos.ADAPTER_KEY][1].gpu_pct, 100.0)
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)
def test_missing_device_allocation_is_unknown_not_zero(self):
stats = accel()[0]["PerformanceStatistics"]
del stats["Alloc system memory"]
entries = [{"model": "Apple M4", "PerformanceStatistics": stats}]
c, _ = self.counters({}, {})
_, adapters = self.sample(c, entries, [], now=1.0)
self.assertIsNone(c.device.mem_used)
self.assertIsNone(adapters[macos.ADAPTER_KEY].dedicated)
def test_failed_client_read_preserves_baseline_and_footprint_targets(self):
c, poller = self.counters({1: GiB}, {1: ME})
first = [client(1, "python", 10 * 10**9, cid=7)]
self.sample(c, accel(), first, now=100.0)
previous = c._prev.copy()
targets = poller.targets.copy()
with patch.object(macos, "_ioreg", return_value=None):
_, adapters = self.sample(c, accel(), None, now=101.0)
self.assertEqual(c._prev, previous)
self.assertEqual(c._last, 100.0)
self.assertEqual(poller.targets, targets)
self.assertEqual(adapters[macos.ADAPTER_KEY].dedicated, accel()[0]["PerformanceStatistics"]["Alloc system memory"])
later = [client(1, "python", 11 * 10**9, cid=7)]
procs, _ = self.sample(c, accel(), later, now=102.0)
self.assertAlmostEqual(procs[macos.ADAPTER_KEY][1].gpu_pct, 50.0)
class PollerTests(unittest.TestCase):
def footprint(self, sizes, calls):
def run(args, **kw):
pid = int(args[-1])
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": 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])
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()
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_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 measure(pid):
p.set_targets([]) # the process exits while footprint runs
return 2 * GiB
p.measure = measure
p.poll_once()
p.set_targets([(812, "a", True)])
self.assertIsNone(p.get(812, "a"))
class ProcInfoTests(unittest.TestCase):
def test_macos_libraries_and_metal_driver(self):
names = {_lib_name(b) for b in ("libggml-metal.dylib", "libllama.dylib", "libmlx.dylib",
"agxmetalg16g_b0", "libtorch_cpu.dylib", "assets.car")}
self.assertNotIn("assets.car", names)
self.assertEqual(_match_runtimes(names - {None}), ["llama.cpp", "ggml", "PyTorch", "MLX", "Metal"])
class SkipPathTests(unittest.TestCase):
def test_protected_containers_and_system_files_are_never_opened(self):
from gputaskman import procinfo
with patch.object(procinfo.sys, "platform", "darwin"):
self.assertTrue(procinfo._skip_path(
"/Users/me/Library/Containers/com.apple.mediaanalysisd/Data/Library/Caches/PFSceneGeographyData.index"))
self.assertTrue(procinfo._skip_path("/Users/me/Library/Group Containers/group.x/db"))
self.assertTrue(procinfo._skip_path("/System/Library/Fonts/SFNS.ttf"))
self.assertFalse(procinfo._skip_path("/Users/me/.ollama/models/blobs/sha256-abc"))
with patch.object(procinfo.sys, "platform", "linux"):
self.assertFalse(procinfo._skip_path("/usr/lib/x86_64-linux-gnu/libcuda.so.1"))
class ReportTests(unittest.TestCase):
def test_metal_header_and_json(self):
rows = [ProcRow(79379, "python3.13", "AI", ProcGpu(dedicated=2 * GiB, engines={"gpu": 98.4}),
ProcDetail(79379, "python3.13")),
ProcRow(167, "WindowServer", "compositor", ProcGpu(attributed=False, engines={"gpu": 2.0}),
ProcDetail(167, "WindowServer"))]
snap = Snapshot(taken=1, adapter=None, adapters=[], nv=None, driver="macOS 26.3.1", cuda="",
vram_total=16 * GiB, vram_used=5 * GiB, shared_used=0, backend="metal", procs=rows)
text = to_text(snap)
self.assertIn("unified", text)
self.assertNotIn("CUDA", text)
ws = next(line for line in text.splitlines() if line.lstrip().startswith("167"))
self.assertIn("n/a", ws)
data = to_dict(snap)["processes"]
self.assertEqual((data[0]["vram_bytes"], data[1]["vram_bytes"], data[1]["gpu_pct"]), (2 * GiB, None, 2.0))
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()