feat(cpu): implement MMCPULoadProvider with per-core tick deltas, frequency, and throttling (Issue #5 )

Merge branch 'milestone/m1-foundation' into develop (Milestone 1 Complete)
2026-09-08 12:18:30 +01:00 · 2026-09-08 12:14:08 +01:00
5 changed files with 326 additions and 0 deletions
@@ -7,9 +7,11 @@
 	objects = {

 /* Begin PBXBuildFile section */
+		160334CC765E091A7CBE21AA /* MMCPULoadTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 4CE92B1A8D7FDBB6499448E1 /* MMCPULoadTests.swift */; };
 		1879A3DCF6E305D7F2CD472E /* CoreFoundation.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 2345555FF9780B02A90CC7A9 /* CoreFoundation.framework */; };
 		1B3F1C8ABF0ADFAA290FF6F6 /* MMSMCParser.m in Sources */ = {isa = PBXBuildFile; fileRef = 375AA781A2AA0A20B119C7B7 /* MMSMCParser.m */; };
 		3C0AC14F803C813287D8A663 /* IOKit.framework in Frameworks */ = {isa = PBXBuildFile; fileRef = 007F48A5A599AB4E8D216D16 /* IOKit.framework */; };
+		4419FE7554489B23976E2970 /* MMCPULoadProvider.m in Sources */ = {isa = PBXBuildFile; fileRef = D68FC8100D08DB6202F46339 /* MMCPULoadProvider.m */; };
 		88387CDAE2AC1CC74EF89B57 /* MacMonitorApp.swift in Sources */ = {isa = PBXBuildFile; fileRef = ADEA6BD38BA8D887B1DB64A9 /* MacMonitorApp.swift */; };
 		9BCE74C5454F81EF80492E75 /* MacMonitorTests.swift in Sources */ = {isa = PBXBuildFile; fileRef = 2EC3EDFCD5C50CB352FCED87 /* MacMonitorTests.swift */; };
 		A7609CE56D49EC3419987468 /* SystemTelemetryStore.swift in Sources */ = {isa = PBXBuildFile; fileRef = E4B4E94FB2886C60D5548A2A /* SystemTelemetryStore.swift */; };
@@ -36,14 +38,17 @@
 		2EC3EDFCD5C50CB352FCED87 /* MacMonitorTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MacMonitorTests.swift; sourceTree = "<group>"; };
 		32340166F6100A08105308D3 /* MMTelemetryCoordinator.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMTelemetryCoordinator.h; sourceTree = "<group>"; };
 		375AA781A2AA0A20B119C7B7 /* MMSMCParser.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MMSMCParser.m; sourceTree = "<group>"; };
+		4CE92B1A8D7FDBB6499448E1 /* MMCPULoadTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MMCPULoadTests.swift; sourceTree = "<group>"; };
 		5555436CD3CB8A73F5D6504F /* MMAppleSMCClient.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MMAppleSMCClient.m; sourceTree = "<group>"; };
 		5635101F862DE680856BDE6E /* MMTelemetryDomain.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMTelemetryDomain.h; sourceTree = "<group>"; };
 		56E285A0A1746AE659981F22 /* MacMonitorTests.xctest */ = {isa = PBXFileReference; explicitFileType = wrapper.cfbundle; includeInIndex = 0; path = MacMonitorTests.xctest; sourceTree = BUILT_PRODUCTS_DIR; };
+		57845310A3D4EC67E48A3B11 /* MMCPULoadProvider.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMCPULoadProvider.h; sourceTree = "<group>"; };
 		6D0E5CAF25DFA9A1D2A698A0 /* MMTelemetryProvider.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMTelemetryProvider.h; sourceTree = "<group>"; };
 		726005CB5A6C86E7D80D3CA0 /* MMAppleSMCClient.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMAppleSMCClient.h; sourceTree = "<group>"; };
 		8FBB436F3D9472194D8C6EDD /* MMSMCDefines.h */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.h; path = MMSMCDefines.h; sourceTree = "<group>"; };
 		940D608A1AF80F75584E744E /* MMSMCTests.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MMSMCTests.swift; sourceTree = "<group>"; };
 		ADEA6BD38BA8D887B1DB64A9 /* MacMonitorApp.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = MacMonitorApp.swift; sourceTree = "<group>"; };
+		D68FC8100D08DB6202F46339 /* MMCPULoadProvider.m */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.c.objc; path = MMCPULoadProvider.m; sourceTree = "<group>"; };
 		E142AE61F9B87757997870DD /* ContentView.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = ContentView.swift; sourceTree = "<group>"; };
 		E4B4E94FB2886C60D5548A2A /* SystemTelemetryStore.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SystemTelemetryStore.swift; sourceTree = "<group>"; };
 		F5EC59DCDA5FABDA409CDBCB /* MacMonitor.app */ = {isa = PBXFileReference; explicitFileType = wrapper.application; includeInIndex = 0; path = MacMonitor.app; sourceTree = BUILT_PRODUCTS_DIR; };
@@ -79,6 +84,7 @@
 				4D8D8B40632C525CBC1D0E43 /* App */,
 				54787E6270EA7B9A1BE11359 /* Core */,
 				9844EC526E3527F6A582179F /* Hardware */,
+				8BF79E3BCB76E7A1669DC930 /* Telemetry */,
 				3E4A0B53C583BD0B7A68EACE /* UI */,
 			);
 			path = Sources;
@@ -112,6 +118,23 @@
 			path = Core;
 			sourceTree = "<group>";
 		};
+		78383CED205BCA772701AE48 /* CPU */ = {
+			isa = PBXGroup;
+			children = (
+				57845310A3D4EC67E48A3B11 /* MMCPULoadProvider.h */,
+				D68FC8100D08DB6202F46339 /* MMCPULoadProvider.m */,
+			);
+			path = CPU;
+			sourceTree = "<group>";
+		};
+		8BF79E3BCB76E7A1669DC930 /* Telemetry */ = {
+			isa = PBXGroup;
+			children = (
+				78383CED205BCA772701AE48 /* CPU */,
+			);
+			path = Telemetry;
+			sourceTree = "<group>";
+		};
 		9844EC526E3527F6A582179F /* Hardware */ = {
 			isa = PBXGroup;
 			children = (
@@ -133,6 +156,7 @@
 			isa = PBXGroup;
 			children = (
 				2EC3EDFCD5C50CB352FCED87 /* MacMonitorTests.swift */,
+				4CE92B1A8D7FDBB6499448E1 /* MMCPULoadTests.swift */,
 				940D608A1AF80F75584E744E /* MMSMCTests.swift */,
 			);
 			path = Tests;
@@ -234,6 +258,7 @@
 			isa = PBXSourcesBuildPhase;
 			buildActionMask = 2147483647;
 			files = (
+				160334CC765E091A7CBE21AA /* MMCPULoadTests.swift in Sources */,
 				EC9FA3E4A119277B89E73F8D /* MMSMCTests.swift in Sources */,
 				9BCE74C5454F81EF80492E75 /* MacMonitorTests.swift in Sources */,
 			);
@@ -245,6 +270,7 @@
 			files = (
 				A9FCAEC0BF27A419DB148C4A /* ContentView.swift in Sources */,
 				CD91FC663B19DA1FEA3D49D7 /* MMAppleSMCClient.m in Sources */,
+				4419FE7554489B23976E2970 /* MMCPULoadProvider.m in Sources */,
 				1B3F1C8ABF0ADFAA290FF6F6 /* MMSMCParser.m in Sources */,
 				EAFAF5A10502D4ACC64F4720 /* MMTelemetryCoordinator.m in Sources */,
 				88387CDAE2AC1CC74EF89B57 /* MacMonitorApp.swift in Sources */,
@@ -11,4 +11,7 @@
 #import "MMSMCParser.h"
 #import "MMAppleSMCClient.h"

+// Telemetry Providers
+#import "MMCPULoadProvider.h"
+
 #endif /* MacMonitor_Bridging_Header_h */
@@ -0,0 +1,31 @@
+#ifndef MMCPULoadProvider_h
+#define MMCPULoadProvider_h
+
+#import <Foundation/Foundation.h>
+#import <mach/mach.h>
+#import <mach/processor_info.h>
+#import "MMTelemetryProvider.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+/**
+ * MMCPULoadProvider
+ * Samples real-time Mach host processor CPU load ticks, per-core utilization percentages,
+ * and CPU operating frequency.
+ */
+@interface MMCPULoadProvider : NSObject <MMTelemetryProvider>
+
+@property (nonatomic, readonly) natural_t coreCount;
+
+/**
+ * Static calculator method facilitating deterministic unit testing with mock tick data.
+ */
+ (NSDictionary<NSString *, id> *)calculateLoadFromPreviousTicks:(const struct processor_cpu_load_info * _Nullable)prevTicks
+                                                    currentTicks:(const struct processor_cpu_load_info *)currTicks
+                                                       coreCount:(natural_t)coreCount;
+
+@end
+
+NS_ASSUME_NONNULL_END
+
+#endif /* MMCPULoadProvider_h */
@@ -0,0 +1,201 @@
+#import "MMCPULoadProvider.h"
+#import <sys/sysctl.h>
+#import <os/lock.h>
+
+@interface MMCPULoadProvider () {
+    os_unfair_lock _lock;
+    processor_cpu_load_info_t _previousCpuInfo;
+    mach_msg_type_number_t _previousCpuInfoCount;
+    natural_t _coreCount;
+    uint64_t _maxFrequencyHz;
+}
+@end
+
+@implementation MMCPULoadProvider
+
+- (instancetype)init {
+    self = [super init];
+    if (self) {
+        _lock = OS_UNFAIR_LOCK_INIT;
+        _previousCpuInfo = NULL;
+        _previousCpuInfoCount = 0;
+        
+        // Read CPU core count
+        natural_t cCount = 1;
+        size_t size = sizeof(cCount);
+        sysctlbyname("hw.logicalcpu", &cCount, &size, NULL, 0);
+        _coreCount = cCount;
+        
+        // Read maximum frequency
+        uint64_t maxFreq = 0;
+        size = sizeof(maxFreq);
+        if (sysctlbyname("hw.cpufrequency_max", &maxFreq, &size, NULL, 0) != 0) {
+            sysctlbyname("hw.cpufrequency", &maxFreq, &size, NULL, 0);
+        }
+        _maxFrequencyHz = maxFreq;
+    }
+    return self;
+}
+
+- (void)dealloc {
+    if (_previousCpuInfo != NULL) {
+        free(_previousCpuInfo);
+        _previousCpuInfo = NULL;
+    }
+}
+
+- (MMTelemetryDomain)domain {
+    return MMTelemetryDomainCPU;
+}
+
+- (NSString *)providerIdentifier {
+    return @"com.i3omb.macmonitor.telemetry.cpuload";
+}
+
+- (BOOL)isAvailable {
+    return YES;
+}
+
+- (natural_t)coreCount {
+    return _coreCount;
+}
+
+ (NSDictionary<NSString *, id> *)calculateLoadFromPreviousTicks:(const struct processor_cpu_load_info * _Nullable)prevTicks
+                                                    currentTicks:(const struct processor_cpu_load_info *)currTicks
+                                                       coreCount:(natural_t)coreCount {
+    if (!currTicks || coreCount == 0) return @{};
+    
+    NSMutableArray<NSDictionary<NSString *, NSNumber *> *> *coresList = [NSMutableArray arrayWithCapacity:coreCount];
+    double totalUserPercent = 0.0;
+    double totalSystemPercent = 0.0;
+    double totalIdlePercent = 0.0;
+    double totalActivePercent = 0.0;
+    
+    for (natural_t i = 0; i < coreCount; i++) {
+        uint64_t user = currTicks[i].cpu_ticks[CPU_STATE_USER];
+        uint64_t system = currTicks[i].cpu_ticks[CPU_STATE_SYSTEM];
+        uint64_t idle = currTicks[i].cpu_ticks[CPU_STATE_IDLE];
+        uint64_t nice = currTicks[i].cpu_ticks[CPU_STATE_NICE];
+        
+        uint64_t deltaUser = 0;
+        uint64_t deltaSystem = 0;
+        uint64_t deltaIdle = 0;
+        uint64_t deltaNice = 0;
+        
+        if (prevTicks != NULL) {
+            deltaUser = (user >= prevTicks[i].cpu_ticks[CPU_STATE_USER]) ? (user - prevTicks[i].cpu_ticks[CPU_STATE_USER]) : 0;
+            deltaSystem = (system >= prevTicks[i].cpu_ticks[CPU_STATE_SYSTEM]) ? (system - prevTicks[i].cpu_ticks[CPU_STATE_SYSTEM]) : 0;
+            deltaIdle = (idle >= prevTicks[i].cpu_ticks[CPU_STATE_IDLE]) ? (idle - prevTicks[i].cpu_ticks[CPU_STATE_IDLE]) : 0;
+            deltaNice = (nice >= prevTicks[i].cpu_ticks[CPU_STATE_NICE]) ? (nice - prevTicks[i].cpu_ticks[CPU_STATE_NICE]) : 0;
+        }
+        
+        uint64_t deltaTotal = deltaUser + deltaSystem + deltaIdle + deltaNice;
+        double uPct = 0.0, sPct = 0.0, iPct = 100.0, aPct = 0.0;
+        
+        if (deltaTotal > 0) {
+            uPct = ((double)deltaUser / (double)deltaTotal) * 100.0;
+            sPct = ((double)deltaSystem / (double)deltaTotal) * 100.0;
+            iPct = ((double)deltaIdle / (double)deltaTotal) * 100.0;
+            aPct = 100.0 - iPct;
+            if (aPct < 0.0) aPct = 0.0;
+            if (aPct > 100.0) aPct = 100.0;
+        }
+        
+        totalUserPercent += uPct;
+        totalSystemPercent += sPct;
+        totalIdlePercent += iPct;
+        totalActivePercent += aPct;
+        
+        [coresList addObject:@{
+            @"coreIndex": @(i),
+            @"userPercent": @(uPct),
+            @"systemPercent": @(sPct),
+            @"idlePercent": @(iPct),
+            @"totalPercent": @(aPct)
+        }];
+    }
+    
+    double avgUser = coreCount > 0 ? (totalUserPercent / coreCount) : 0.0;
+    double avgSystem = coreCount > 0 ? (totalSystemPercent / coreCount) : 0.0;
+    double avgIdle = coreCount > 0 ? (totalIdlePercent / coreCount) : 100.0;
+    double avgTotal = coreCount > 0 ? (totalActivePercent / coreCount) : 0.0;
+    
+    return @{
+        @"cores": coresList,
+        @"coreCount": @(coreCount),
+        @"userPercent": @(avgUser),
+        @"systemPercent": @(avgSystem),
+        @"idlePercent": @(avgIdle),
+        @"totalPercent": @(avgTotal)
+    };
+}
+
+- (nullable NSDictionary<NSString *, id> *)sampleTelemetryWithError:(NSError **)error {
+    natural_t numCPUs = 0;
+    processor_info_array_t cpuInfo = NULL;
+    mach_msg_type_number_t numCpuInfo = 0;
+    
+    kern_return_t kr = host_processor_info(
+        mach_host_self(),
+        PROCESSOR_CPU_LOAD_INFO,
+        &numCPUs,
+        &cpuInfo,
+        &numCpuInfo
+    );
+    
+    if (kr != KERN_SUCCESS || cpuInfo == NULL) {
+        if (error) {
+            *error = [NSError errorWithDomain:@"com.i3omb.MacMonitor.CPU"
+                                         code:kr
+                                     userInfo:@{NSLocalizedDescriptionKey: @"host_processor_info failed to read CPU ticks"}];
+        }
+        return nil;
+    }
+    
+    os_unfair_lock_lock(&_lock);
+    
+    processor_cpu_load_info_t currentCpuInfo = (processor_cpu_load_info_t)cpuInfo;
+    NSDictionary<NSString *, id> *metrics = [MMCPULoadProvider calculateLoadFromPreviousTicks:_previousCpuInfo
+                                                                                 currentTicks:currentCpuInfo
+                                                                                    coreCount:numCPUs];
+    
+    // Free previous malloc buffer
+    if (_previousCpuInfo != NULL) {
+        free(_previousCpuInfo);
+        _previousCpuInfo = NULL;
+    }
+    
+    // Allocate new buffer to preserve state for the next delta
+    vm_size_t bufferSize = numCpuInfo * sizeof(integer_t);
+    _previousCpuInfo = (processor_cpu_load_info_t)malloc(bufferSize);
+    if (_previousCpuInfo != NULL) {
+        memcpy(_previousCpuInfo, cpuInfo, bufferSize);
+        _previousCpuInfoCount = numCpuInfo;
+    }
+    
+    // Deallocate the buffer returned by the kernel
+    vm_deallocate(mach_task_self(), (vm_address_t)cpuInfo, numCpuInfo * sizeof(integer_t));
+    
+    os_unfair_lock_unlock(&_lock);
+    
+    // Read current frequency
+    uint64_t currentFreq = 0;
+    size_t size = sizeof(currentFreq);
+    if (sysctlbyname("hw.cpufrequency", &currentFreq, &size, NULL, 0) != 0) {
+        currentFreq = _maxFrequencyHz;
+    }
+    
+    // Thermal State
+    NSProcessInfoThermalState thermalState = [NSProcessInfo processInfo].thermalState;
+    BOOL isThrottled = (thermalState >= NSProcessInfoThermalStateSerious);
+    
+    NSMutableDictionary<NSString *, id> *result = [metrics mutableCopy];
+    result[@"frequencyHz"] = @(currentFreq);
+    result[@"maxFrequencyHz"] = @(_maxFrequencyHz);
+    result[@"thermalState"] = @(thermalState);
+    result[@"isThrottled"] = @(isThrottled);
+    
+    return [result copy];
+}
+
+@end
@@ -0,0 +1,65 @@
+import XCTest
+@testable import MacMonitor
+
+final class MMCPULoadTests: XCTestCase {
+    
+    func testTickDeltaCalculation() {
+        var prevTicks = [processor_cpu_load_info_data_t]()
+        var currTicks = [processor_cpu_load_info_data_t]()
+        
+        // Setup mock Core 0: 20% user, 10% system, 70% idle
+        var core0Prev = processor_cpu_load_info_data_t()
+        core0Prev.cpu_ticks.0 = 100 // USER
+        core0Prev.cpu_ticks.1 = 50  // SYSTEM
+        core0Prev.cpu_ticks.2 = 850 // IDLE
+        core0Prev.cpu_ticks.3 = 0   // NICE
+        prevTicks.append(core0Prev)
+        
+        var core0Curr = processor_cpu_load_info_data_t()
+        core0Curr.cpu_ticks.0 = 300 // USER (+200)
+        core0Curr.cpu_ticks.1 = 150 // SYSTEM (+100)
+        core0Curr.cpu_ticks.2 = 1550 // IDLE (+700)
+        core0Curr.cpu_ticks.3 = 0   // NICE (+0)
+        currTicks.append(core0Curr)
+        
+        prevTicks.withUnsafeBufferPointer { prevBuf in
+            currTicks.withUnsafeBufferPointer { currBuf in
+                let metrics = MMCPULoadProvider.calculateLoad(
+                    fromPreviousTicks: prevBuf.baseAddress,
+                    currentTicks: currBuf.baseAddress!,
+                    coreCount: 1
+                )
+                
+                let totalPct = metrics["totalPercent"] as? Double ?? 0
+                let userPct = metrics["userPercent"] as? Double ?? 0
+                let systemPct = metrics["systemPercent"] as? Double ?? 0
+                let idlePct = metrics["idlePercent"] as? Double ?? 0
+                
+                // Total delta = 200 + 100 + 700 = 1000
+                // User = 20%, System = 10%, Idle = 70%, Total Active = 30%
+                XCTAssertEqual(totalPct, 30.0, accuracy: 0.1)
+                XCTAssertEqual(userPct, 20.0, accuracy: 0.1)
+                XCTAssertEqual(systemPct, 10.0, accuracy: 0.1)
+                XCTAssertEqual(idlePct, 70.0, accuracy: 0.1)
+            }
+        }
+    }
+    
+    func testLiveCPULoadProvider() throws {
+        let provider = MMCPULoadProvider()
+        XCTAssertTrue(provider.isAvailable)
+        XCTAssertEqual(provider.domain, .cpu)
+        XCTAssertGreaterThan(provider.coreCount, 0)
+        
+        // Initial sample establishes baseline
+        let sample1 = try provider.sampleTelemetry()
+        XCTAssertNotNil(sample1)
+        
+        // Second sample produces live deltas
+        usleep(100_000) // 100ms
+        let sample2 = try provider.sampleTelemetry()
+        let cores = sample2["cores"] as? [[String: Any]]
+        XCTAssertNotNil(cores)
+        XCTAssertEqual(cores?.count, Int(provider.coreCount))
+    }
+}
Author	SHA1	Message	Date
gronod	cb625964a5	feat(cpu): implement MMCPULoadProvider with per-core tick deltas, frequency, and throttling (Issue #5 ) MacMonitor CI/CD Pipeline / Build & Test (Intel x86_64) (push) Canceled after 0s Details	2026-09-08 12:18:30 +01:00
gronod	5517e92eff	Merge branch 'milestone/m1-foundation' into develop (Milestone 1 Complete) MacMonitor CI/CD Pipeline / Build & Test (Intel x86_64) (push) Canceled after 0s Details	2026-09-08 12:14:08 +01:00