[Darwin] MTRDeviceController accessor for in-memory devices (#37770)

* [Darwin] MTRDeviceController accessor for in-memory devices

* Remove test log

* Update src/darwin/Framework/CHIP/MTRDeviceController.mm

Co-authored-by: Justin Wood <woody@apple.com>

---------

Co-authored-by: Justin Wood <woody@apple.com>

Author: jtung-apple

src/darwin/Framework/CHIP/MTRDevice.mm

@@ -133,6 +133,8 @@ - (void)dealloc
     // TODO: retain cycle and clean up https://github.com/project-chip/connectedhomeip/issues/34267
     MTR_LOG("MTRDevice dealloc: %p", self);
 
+    [_deviceController deviceDeallocated];
+
     // Locking because _cancelAllAttributeValueWaiters has os_unfair_lock_assert_owner(&_lock)
     std::lock_guard lock(_lock);
     [self _cancelAllAttributeValueWaiters];

src/darwin/Framework/CHIP/MTRDeviceController.h

@@ -22,6 +22,7 @@
 #import <Matter/MTROperationalCertificateIssuer.h>
 
 @class MTRBaseDevice;
+@class MTRDevice;
 @class MTRServerEndpoint; // Defined in MTRServerEndpoint.h, which imports MTRAccessGrant.h, which imports MTRBaseClusters.h, which imports this file, so we can't import it.
 
 @class MTRDeviceControllerAbstractParameters;
@@ -82,6 +83,12 @@ MTR_AVAILABLE(ios(16.1), macos(13.0), watchos(9.1), tvos(16.1))
 @property (readonly, nonatomic, nullable)
     NSNumber * controllerNodeID MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4));
 
+/**
+ * Returns the list of MTRDevice instances that this controller has loaded
+ * into memory. Returns an empty array if no devices are in memory.
+ */
+@property (readonly, nonatomic) NSArray<MTRDevice *> * devices MTR_AVAILABLE(ios(18.4), macos(15.4), watchos(11.4), tvos(18.4));
+
 /**
  * Set up a commissioning session for a device, using the provided setup payload
  * to discover it and connect to it.

src/darwin/Framework/CHIP/MTRDeviceController.mm

@@ -381,6 +381,11 @@ - (MTRDevice * _Nullable)_deviceForNodeID:(NSNumber *)nodeID createIfNeeded:(BOO
     MTRDevice * deviceToReturn = [_nodeIDToDeviceMap objectForKey:nodeID];
     if (!deviceToReturn && createIfNeeded) {
         deviceToReturn = [self _setupDeviceForNodeID:nodeID prefetchedClusterData:nil];
+        [self _callDelegatesWithBlock:^(id<MTRDeviceControllerDelegate> delegate) {
+            if ([delegate respondsToSelector:@selector(devicesChangedForController:)]) {
+                [delegate devicesChangedForController:self];
+            }
+        } logString:__PRETTY_FUNCTION__];
     }
 
     return deviceToReturn;
@@ -416,6 +421,27 @@ - (void)removeDevice:(MTRDevice *)device
     }
 }
 
+- (NSArray<MTRDevice *> *)devices
+{
+    std::lock_guard lock(*self.deviceMapLock);
+    NSMutableArray * devicesToReturn = [NSMutableArray array];
+
+    for (MTRDevice * device in _nodeIDToDeviceMap.objectEnumerator) {
+        [devicesToReturn addObject:device];
+    }
+
+    return devicesToReturn;
+}
+
+- (void)deviceDeallocated
+{
+    [self _callDelegatesWithBlock:^(id<MTRDeviceControllerDelegate> delegate) {
+        if ([delegate respondsToSelector:@selector(devicesChangedForController:)]) {
+            [delegate devicesChangedForController:self];
+        }
+    } logString:__PRETTY_FUNCTION__];
+}
+
 - (BOOL)setOperationalCertificateIssuer:(nullable id<MTROperationalCertificateIssuer>)operationalCertificateIssuer
                                   queue:(nullable dispatch_queue_t)queue
 {

src/darwin/Framework/CHIP/MTRDeviceControllerDelegate.h

@@ -106,6 +106,12 @@ MTR_AVAILABLE(ios(16.4), macos(13.3), watchos(9.4), tvos(16.4))
  */
 - (void)controller:(MTRDeviceController *)controller
     suspendedChangedTo:(BOOL)suspended MTR_AVAILABLE(ios(18.2), macos(15.2), watchos(11.2), tvos(18.2));
+
+/**
+ * Notify the delegate when the list of MTRDevice objects in memory has changed.
+ */
+- (void)devicesChangedForController:(MTRDeviceController *)controller MTR_AVAILABLE(ios(18.4), macos(15.4), watchos(11.4), tvos(18.4));
+
 @end
 
 typedef NS_ENUM(NSUInteger, MTRPairingStatus) {

src/darwin/Framework/CHIP/MTRDeviceController_Internal.h

@@ -116,6 +116,11 @@ NS_ASSUME_NONNULL_BEGIN
 - (MTRDevice *)_setupDeviceForNodeID:(NSNumber *)nodeID prefetchedClusterData:(nullable NSDictionary<MTRClusterPath *, MTRDeviceClusterData *> *)prefetchedClusterData;
 - (void)removeDevice:(MTRDevice *)device;
 
+/**
+ * Called by MTRDevice object when their dealloc is called, so the controller can notify interested delegate that active devices have changed
+ */
+- (void)deviceDeallocated;
+
 @end
 
 /**

src/darwin/Framework/CHIPTests/MTRPerControllerStorageTests.m

@@ -103,6 +103,19 @@ - (void)controller:(MTRDeviceController *)controller
 }
 @end
 
+@interface MTRPerControllerStorageTestsDeallocDelegate : NSObject <MTRDeviceControllerDelegate>
+@property (nonatomic, nullable) dispatch_block_t onDevicesChanged;
+@end
+
+@implementation MTRPerControllerStorageTestsDeallocDelegate
+- (void)devicesChangedForController:(MTRDeviceController *)controller
+{
+    if (self.onDevicesChanged) {
+        self.onDevicesChanged();
+    }
+}
+@end
+
 @interface MTRPerControllerStorageTestsCertificateIssuer : NSObject <MTROperationalCertificateIssuer>
 - (instancetype)initWithRootCertificate:(MTRCertificateDERBytes)rootCertificate
                 intermediateCertificate:(MTRCertificateDERBytes _Nullable)intermediateCertificate
@@ -3652,9 +3665,31 @@ - (void)testMTRDeviceDealloc
     // We should have established CASE using our operational key.
     XCTAssertEqual(operationalKeys.signatureCount, 1);
 
+    // Before the test, clear the device controller in-memory MapTable
+    [controller forgetDeviceWithNodeID:deviceID];
+
     __block BOOL subscriptionReportEnd1 = NO;
     XCTestExpectation * subscriptionCallbackDeleted = [self expectationWithDescription:@"Subscription callback deleted"];
+    XCTestExpectation * controllerAddedDevice = [self expectationWithDescription:@"Controller added device"];
+    XCTestExpectation * controllerRemovedDevice = [self expectationWithDescription:@"Controller removed device"];
     @autoreleasepool {
+        // Expected the test device was added and removed
+        MTRPerControllerStorageTestsDeallocDelegate * controllerDelegate = [[MTRPerControllerStorageTestsDeallocDelegate alloc] init];
+        __block NSUInteger lastDeviceCount = controller.devices.count;
+        controllerDelegate.onDevicesChanged = ^{
+            // Use self as lock for lastDeviceCount access, so sanitizer doesn't complain
+            @synchronized(self) {
+                NSArray<MTRDevice *> * devices = controller.devices;
+                if (devices.count > lastDeviceCount) {
+                    [controllerAddedDevice fulfill];
+                } else if (devices.count < lastDeviceCount) {
+                    [controllerRemovedDevice fulfill];
+                }
+                lastDeviceCount = devices.count;
+            }
+        };
+        [controller addDeviceControllerDelegate:controllerDelegate queue:queue];
+
         __auto_type * device = [MTRDevice deviceWithNodeID:deviceID controller:controller];
         __auto_type * delegate = [[MTRDeviceTestDelegate alloc] init];
 
@@ -3675,13 +3710,16 @@ - (void)testMTRDeviceDealloc
         [device setDelegate:delegate queue:queue];
 
         [self waitForExpectations:@[ subscriptionReportBegin ] timeout:60];
+
+        XCTAssertEqual(controller.devices.count, 1);
     }
 
     // report should still be ongoing
     XCTAssertFalse(subscriptionReportEnd1);
+    XCTAssertEqual(controller.devices.count, 0);
 
     // dealloc -> delete should be called soon after the autoreleasepool reaps
-    [self waitForExpectations:@[ subscriptionCallbackDeleted ] timeout:60];
+    [self waitForExpectations:@[ subscriptionCallbackDeleted, controllerAddedDevice, controllerRemovedDevice ] timeout:60];
 
     // Reset our commissionee.
     __auto_type * baseDevice = [MTRBaseDevice deviceWithNodeID:deviceID controller:controller];