cuda.core.system: Add ProcessInfo APIs (#1917)

* cuda.core.system: Add ProcessInfo APIs

* Add API docs

* Fix test

Author: mdboom

cuda_core/cuda/core/system/_device.pyx

@@ -36,6 +36,7 @@ include "_mig.pxi"
 include "_nvlink.pxi"
 include "_pci_info.pxi"
 include "_performance.pxi"
+include "_process.pxi"
 include "_repair_status.pxi"
 include "_temperature.pxi"
 include "_utilization.pxi"
@@ -765,6 +766,33 @@ cdef class Device:
         """
         return [Pstates(x) for x in nvml.device_get_supported_performance_states(self._handle)]
 
+    ##########################################################################
+    # PROCESS
+    # See external class definitions in _process.pxi
+
+    @property
+    def compute_running_processes(self) -> list[ProcessInfo]:
+        """
+        Get information about processes with a compute context on a device
+
+        For Fermi™ or newer fully supported devices.
+
+        This function returns information only about compute running processes
+        (e.g. CUDA application which have active context). Any graphics
+        applications (e.g. using OpenGL, DirectX) won't be listed by this
+        function.
+
+        Keep in mind that information returned by this call is dynamic and the
+        number of elements might change in time.
+
+        In MIG mode, if device handle is provided, the API returns aggregate
+        information, only if the caller has appropriate privileges. Per-instance
+        information can be queried by using specific MIG device handles.
+        Querying per-instance information using MIG device handles is not
+        supported if the device is in vGPU Host virtualization mode.
+        """
+        return [ProcessInfo(self, proc) for proc in nvml.device_get_compute_running_processes_v3(self._handle)]
+
     ##########################################################################
     # REPAIR STATUS
     # See external class definitions in _repair_status.pxi

cuda_core/cuda/core/system/_process.pxi

@@ -0,0 +1,48 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+
+class ProcessInfo:
+    """
+    Information about running compute processes on the GPU.
+    """
+    def __init__(self, device: "Device", process_info: nvml.ProcessInfo):
+        self._device = device
+        self._process_info = process_info
+
+    @property
+    def pid(self) -> int:
+        """
+        The PID of the process.
+        """
+        return self._process_info.pid
+
+    @property
+    def used_gpu_memory(self) -> int:
+        """
+        The amount of GPU memory (in bytes) used by the process.
+        """
+        return self._process_info.used_gpu_memory
+
+    @property
+    def gpu_instance_id(self) -> int:
+        """
+        The GPU instance ID for MIG devices.
+
+        Only valid for processes running on MIG devices.
+        """
+        if not self._device.mig.is_mig_device:
+            raise nvml.NotSupportedError(nvml.Return.ERROR_NOT_SUPPORTED)
+        return self._process_info.gpu_instance_id
+
+    @property
+    def compute_instance_id(self) -> int:
+        """
+        The Compute instance ID for MIG devices.
+
+        Only valid for processes running on MIG devices.
+        """
+        if not self._device.mig.is_mig_device:
+            raise nvml.NotSupportedError(nvml.Return.ERROR_NOT_SUPPORTED)
+        return self._process_info.compute_instance_id

cuda_core/docs/source/api_private.rst

@@ -79,6 +79,7 @@ NVML
    system._device.MigInfo
    system._device.NvlinkInfo
    system._device.PciInfo
+   system._device.ProcessInfo
    system._device.RepairStatus
    system._device.Temperature
    system._device.ThermalSensor

cuda_core/tests/system/test_system_device.py

@@ -731,6 +731,25 @@ def test_pstates():
             assert isinstance(utilization.dec_threshold, int)
 
 
+def test_compute_running_processes():
+    for device in system.Device.get_all_devices():
+        with unsupported_before(device, "FERMI"):
+            processes = device.compute_running_processes
+        assert isinstance(processes, list)
+        for proc in processes:
+            assert isinstance(proc, _device.ProcessInfo)
+            assert isinstance(proc.pid, int)
+            assert isinstance(proc.used_gpu_memory, int)
+            if device.mig.is_mig_device:
+                assert isinstance(proc.gpu_instance_id, int)
+                assert isinstance(proc.compute_instance_id, int)
+            else:
+                with pytest.raises(nvml.NotSupportedError):
+                    proc.gpu_instance_id  # noqa: B018
+                with pytest.raises(nvml.NotSupportedError):
+                    proc.compute_instance_id  # noqa: B018
+
+
 def test_nvlink():
     for device in system.Device.get_all_devices():
         max_links = _device.NvlinkInfo.max_links