# Vorssaint-utils System Monitor APIs for CPU, GPU, and Memory Statistics > Discover how Vorssaint-utils system monitor APIs access CPU, GPU, and memory stats on macOS using Mach and IOKit interfaces. Get detailed hardware insights. - Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils) - Tags: api-reference - Published: 2026-09-12 --- **The Vorssaint-utils system monitor reads hardware statistics using native macOS kernel interfaces—Mach `host_statistics` for CPU metrics, IOKit service matching for GPU utilization, and Mach VM statistics combined with `sysctlbyname` for memory data.** Vorssaint-utils is a macOS utility library that provides real-time hardware monitoring capabilities through its **SystemMonitor** component. The implementation avoids third-party dependencies by calling directly into macOS kernel frameworks, delivering accurate CPU, GPU, and memory statistics for menu-bar widgets and system panels. ## CPU Monitoring via Mach host_statistics The CPU monitoring implementation in [`Sources/Vorssaint/Services/SystemMonitor/SystemMonitor.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/SystemMonitor/SystemMonitor.swift) utilizes the Mach kernel's `host_statistics` function to retrieve raw tick counters. The `readCPUUsage()` method (lines 85-100) queries the `HOST_CPU_LOAD_INFO` flavor to obtain user, system, idle, and nice tick counts from `host_cpu_load_info`. The function computes utilization by comparing busy ticks (user + system + nice) against total ticks since the previous sample, yielding a normalized `Double` between 0 and 1. ```swift private func readCPUUsage() -> Double? { var info = host_cpu_load_info() var count = mach_msg_type_number_t( MemoryLayout.stride / MemoryLayout.stride ) let host = mach_host_self() defer { mach_port_deallocate(mach_task_self_, host) } let kr = withUnsafeMutablePointer(to: &info) { $0.withMemoryRebound(to: integer_t.self, capacity: Int(count)) { host_statistics(host, HOST_CPU_LOAD_INFO, $0, &count) } } guard kr == KERN_SUCCESS else { return nil } let user = UInt64(info.cpu_ticks.0) let system = UInt64(info.cpu_ticks.1) let idle = UInt64(info.cpu_ticks.2) let nice = UInt64(info.cpu_ticks.3) let busy = user + system + nice let total = busy + idle defer { previousCPUTicks = (busy, total) } guard let previous = previousCPUTicks, total > previous.total else { return nil } return Double(busy - previous.busy) / Double(total - previous.total) } ``` This delta calculation ensures accurate utilization percentages across sampling intervals by tracking the previous tick counts in `previousCPUTicks`. ## GPU Monitoring via IOKit PerformanceStatistics For GPU metrics, the system monitor interfaces with IOKit to query graphics accelerator services. The `readGPUUsage()` method (lines 111-140) searches for services matching "IOAccelerator" using `IOServiceGetMatchingServices`, then extracts the "Device Utilization %" field from the **PerformanceStatistics** dictionary. The implementation iterates through accelerator entries via `IOIteratorNext`, reading properties with `IORegistryEntryCreateCFProperty` and converting the integer percentage to a floating-point value between 0 and 1. ```swift private static func readGPUUsage() -> Double? { var iterator = io_iterator_t() guard IOServiceGetMatchingServices(kIOMainPortDefault, IOServiceMatching("IOAccelerator"), &iterator) == kIOReturnSuccess else { return nil } defer { IOObjectRelease(iterator) } while case let entry = IOIteratorNext(iterator), entry != 0 { defer { IOObjectRelease(entry) } guard let ref = IORegistryEntryCreateCFProperty(entry, "PerformanceStatistics" as CFString, kCFAllocatorDefault, 0), let stats = ref.takeRetainedValue() as? [String: Any], let utilization = stats["Device Utilization %"] as? Int else { continue } return Double(utilization) / 100.0 } return nil } ``` As implemented in Vorssaint-utils, this approach provides hardware-level GPU utilization without requiring proprietary graphics SDKs or driver-specific implementations. ## Memory Monitoring via Mach VM Statistics and sysctl Memory statistics rely on two distinct kernel interfaces. The `SystemInfo.memoryUsage()` helper (defined in [`Sources/Vorssaint/Support/SystemInfo.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Support/SystemInfo.swift)) queries `host_statistics64` with the `HOST_VM_INFO64` flavor to retrieve VM statistics including active, inactive, wired, and compressed page counts. These raw page counts convert to byte values stored as `UInt64` in the snapshot struct (lines 34-49). Memory pressure detection uses the `readMemoryPressure()` method (lines 45-52), which calls `sysctlbyname` with the `"kern.memorystatus_vm_pressure_level"` parameter: ```swift private static func readMemoryPressure() -> MemoryPressure { var level: Int32 = 0 var size = MemoryLayout.size guard sysctlbyname("kern.memorystatus_vm_pressure_level", &level, &size, nil, 0) == 0 else { return .unknown } return MemoryPressure(kernelLevel: level) } ``` The snapshot struct caches these values alongside CPU and GPU data, enabling efficient UI updates without redundant kernel calls during each refresh cycle. ## Implementation Architecture and Feature Flags The monitoring capabilities are gated by feature flags defined in [`Sources/Vorssaint/Core/FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/FeatureCatalog.swift). The `monitorCPU`, `monitorGPU`, and `monitorMemory` boolean flags control whether the respective kernel APIs initialize during `SystemMonitor` startup, allowing conditional compilation of hardware monitoring features. Key files in the Vorssaint-utils monitoring subsystem: - **[`Sources/Vorssaint/Services/SystemMonitor/SystemMonitor.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Services/SystemMonitor/SystemMonitor.swift)**: Core implementation containing `readCPUUsage()`, `readGPUUsage()`, and `readMemoryPressure()` methods - **[`Sources/Vorssaint/Support/SystemInfo.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Support/SystemInfo.swift)**: Provides the `memoryUsage()` wrapper for Mach VM statistics via `host_statistics64` - **[`Sources/Vorssaint/Core/FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/Core/FeatureCatalog.swift)**: Declares feature flags that gate API initialization for different hardware metrics These low-level macOS APIs provide Vorssaint-utils with zero-dependency hardware monitoring suitable for menu-bar applications requiring minimal resource overhead. ## Summary - **CPU metrics**: `host_statistics` with `HOST_CPU_LOAD_INFO` flavor reads Mach tick counters; utilization calculated from user, system, nice, and idle ticks in `readCPUUsage()` - **GPU metrics**: IOKit `IOServiceGetMatchingServices` locates "IOAccelerator" services; `PerformanceStatistics` dictionary provides "Device Utilization %" parsed by `readGPUUsage()` - **Memory metrics**: `host_statistics64` with `HOST_VM_INFO64` captures VM page statistics via `SystemInfo.memoryUsage()`; `sysctlbyname` retrieves pressure levels in `readMemoryPressure()` - **Architecture**: Feature flags in [`FeatureCatalog.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/FeatureCatalog.swift) control initialization; [`SystemMonitor.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/SystemMonitor.swift) orchestrates sampling and snapshot generation for UI consumption ## Frequently Asked Questions ### Do these Vorssaint-utils system monitor APIs work on Apple Silicon Macs? Yes. The Mach kernel APIs (`host_statistics`, `host_statistics64`) and IOKit interfaces are architecture-agnostic and function identically on both Intel and Apple Silicon (M1/M2/M3) Macs. The "IOAccelerator" service matching correctly identifies the integrated GPU on Apple Silicon as well as discrete GPUs on Intel models, making the Vorssaint-utils system monitor APIs portable across all modern macOS hardware. ### What is the performance overhead of calling these kernel APIs? The overhead is negligible for menu-bar applications. Each API call completes in microseconds: `host_statistics` retrieves pre-accumulated kernel counters, IOKit property reads access cached registry entries, and `sysctlbyname` queries static kernel variables. The Vorssaint-utils implementation caches results between UI updates to prevent redundant system calls during high-frequency refreshes. ### Why does Vorssaint-utils use Mach APIs instead of higher-level Foundation frameworks? Mach kernel interfaces provide the lowest latency and most accurate hardware metrics available on macOS. Higher-level frameworks like `ProcessInfo` lack GPU utilization data and provide only coarse memory statistics. Direct kernel access ensures Vorssaint-utils displays real-time CPU, GPU, and memory pressure data without polling delays or abstraction overhead introduced by intermediate layers. ### Can these APIs be used in sandboxed Mac App Store applications? No. The `host_statistics` Mach API and IOKit registry access require entitlements such as `com.apple.security.temporary-exception.mach-lookup.host-special-port` or specific IOKit client permissions, which Apple does not grant to App Store applications. Vorssaint-utils targets distributed (non-App Store) macOS apps where these entitlements are permissible through standard code signing outside the App Store sandbox.