Add an API on MTRDevice to wait for attributes to reach certain values. (project-chip#36205)

* Add an API on MTRDevice to wait for attributes to reach certain values.

* Address review comments.

* Address review comments.

* Implement cancellation of attribute waiters.

* Addressing more review comments.

* Address review comments.

* Fix build failure

Author: bzbarsky-apple

src/darwin/Framework/CHIP/MTRAttributeValueWaiter.h

@@ -0,0 +1,38 @@
+/**
+ *    Copyright (c) 2024 Project CHIP Authors
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#import <Foundation/Foundation.h>
+#import <Matter/MTRDefines.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+MTR_NEWLY_AVAILABLE
+@interface MTRAttributeValueWaiter : NSObject
+- (instancetype)init NS_UNAVAILABLE;
++ (instancetype)new NS_UNAVAILABLE;
+
+/**
+ * Cancel the wait for the set of attribute path/value pairs represented by this
+ * MTRAttributeValueWaiter.  If the completion has not been called yet, it will
+ * becalled with MTRErrorCodeCancelled.
+ */
+- (void)cancel;
+
+@property (readonly, nonatomic) NSUUID * UUID;
+
+@end
+
+NS_ASSUME_NONNULL_END

src/darwin/Framework/CHIP/MTRAttributeValueWaiter.mm

@@ -0,0 +1,137 @@
+/**
+ *    Copyright (c) 2024 Project CHIP Authors
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#import <Foundation/Foundation.h>
+
+#import <Matter/MTRError.h>
+
+#import "MTRAttributeValueWaiter_Internal.h"
+#import "MTRDevice_Internal.h"
+#import "MTRLogging_Internal.h"
+
+@implementation MTRAwaitedAttributeState
+- (instancetype)initWithValue:(MTRDeviceDataValueDictionary)value
+{
+    if (self = [super init]) {
+        _valueSatisfied = NO;
+        _value = value;
+    }
+
+    return self;
+}
+@end
+
+MTR_DIRECT_MEMBERS
+@interface MTRAttributeValueWaiter ()
+@property (nonatomic, retain) NSDictionary<MTRAttributePath *, MTRAwaitedAttributeState *> * valueExpectations;
+// Protected by the MTRDevice's lock.
+@property (nonatomic, readwrite, retain) dispatch_queue_t queue;
+@property (nonatomic, readwrite, copy, nullable) MTRStatusCompletion completion;
+@property (nonatomic, readonly, retain) MTRDevice * device;
+@end
+
+@implementation MTRAttributeValueWaiter
+
+- (instancetype)initWithDevice:(MTRDevice *)device values:(NSDictionary<MTRAttributePath *, MTRDeviceDataValueDictionary> *)values queue:(dispatch_queue_t)queue completion:(MTRStatusCompletion)completion
+{
+    if (self = [super init]) {
+        auto * valueExpectations = [NSMutableDictionary dictionaryWithCapacity:values.count];
+        for (MTRAttributePath * path in values) {
+            auto * valueExpectation = [[MTRAwaitedAttributeState alloc] initWithValue:values[path]];
+            valueExpectations[path] = valueExpectation;
+        }
+        _valueExpectations = valueExpectations;
+        _queue = queue;
+        _completion = completion;
+        _device = device;
+        _UUID = [NSUUID UUID];
+    }
+
+    return self;
+}
+
+- (void)dealloc
+{
+    [self cancel];
+}
+
+- (void)cancel
+{
+    [self.device _attributeWaitCanceled:self];
+}
+
+- (BOOL)_attributeValue:(MTRDeviceDataValueDictionary)value reportedForPath:(MTRAttributePath *)path byDevice:(MTRDevice *)device
+{
+    MTRAwaitedAttributeState * valueExpectation = self.valueExpectations[path];
+    if (!valueExpectation) {
+        // We don't care about this one.
+        return NO;
+    }
+
+    MTRDeviceDataValueDictionary expectedValue = valueExpectation.value;
+    valueExpectation.valueSatisfied = [device _attributeDataValue:value satisfiesValueExpectation:expectedValue];
+    return valueExpectation.valueSatisfied;
+}
+
+- (BOOL)allValuesSatisfied
+{
+    for (MTRAwaitedAttributeState * valueExpectation in [self.valueExpectations allValues]) {
+        if (!valueExpectation.valueSatisfied) {
+            return NO;
+        }
+    }
+
+    return YES;
+}
+
+- (void)_notifyWithError:(NSError * _Nullable)error
+{
+    // This is always called with the device lock held, so checking and mutating
+    // self.completion here is atomic.
+    if (!self.completion) {
+        return;
+    }
+
+    if (self.expirationTimer != nil) {
+        dispatch_source_cancel(self.expirationTimer);
+        self.expirationTimer = nil;
+    }
+
+    if (!error) {
+        MTR_LOG("%@ %p wait for attribute values completed", self, self);
+    } else if (error.domain == MTRErrorDomain && error.code == MTRErrorCodeTimeout) {
+        MTR_LOG("%@ %p wait for attribute values timed out", self, self);
+    } else if (error.domain == MTRErrorDomain && error.code == MTRErrorCodeCancelled) {
+        MTR_LOG("%@ %p wait for attribute values canceled", self, self);
+    } else {
+        MTR_LOG("%@ %p wait for attribute values unknown error: %@", self, self, error);
+    }
+
+    auto completion = self.completion;
+    auto queue = self.queue;
+    self.completion = nil;
+    self.queue = nil;
+    dispatch_async(queue, ^{
+        completion(error);
+    });
+}
+
+- (NSString *)description
+{
+    return [NSString stringWithFormat:@"<%@: %@>", NSStringFromClass(self.class), self.UUID];
+}
+
+@end

src/darwin/Framework/CHIP/MTRAttributeValueWaiter_Internal.h

@@ -0,0 +1,51 @@
+/**
+ *    Copyright (c) 2024 Project CHIP Authors
+ *
+ *    Licensed under the Apache License, Version 2.0 (the "License");
+ *    you may not use this file except in compliance with the License.
+ *    You may obtain a copy of the License at
+ *
+ *        http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *    Unless required by applicable law or agreed to in writing, software
+ *    distributed under the License is distributed on an "AS IS" BASIS,
+ *    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *    See the License for the specific language governing permissions and
+ *    limitations under the License.
+ */
+
+#import <Matter/MTRAttributeValueWaiter.h>
+#import <Matter/MTRBaseDevice.h> // For MTRAttributePath.
+#import <Matter/MTRCluster.h>
+#import <Matter/MTRDevice.h>
+
+#import "MTRDefines_Internal.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+// Represents the state of a single attribute being waited for: has the path and
+// value being waited for in the response-value and whether the value has been
+// reached.
+MTR_DIRECT_MEMBERS
+@interface MTRAwaitedAttributeState : NSObject
+@property (nonatomic, assign, readwrite) BOOL valueSatisfied;
+@property (nonatomic, retain, readonly) MTRDeviceDataValueDictionary value;
+
+- (instancetype)initWithValue:(MTRDeviceDataValueDictionary)value;
+@end
+
+@interface MTRAttributeValueWaiter ()
+
+@property (nonatomic, readonly) BOOL allValuesSatisfied;
+@property (nonatomic, retain, readwrite, nullable) dispatch_source_t expirationTimer;
+
+- (instancetype)initWithDevice:(MTRDevice *)device values:(NSDictionary<MTRAttributePath *, MTRDeviceDataValueDictionary> *)values queue:(dispatch_queue_t)queue completion:(MTRStatusCompletion)completion;
+
+// Returns YES if after this report the waiter might be done waiting, NO otherwise.
+- (BOOL)_attributeValue:(MTRDeviceDataValueDictionary)value reportedForPath:(MTRAttributePath *)path byDevice:(MTRDevice *)device;
+
+- (void)_notifyWithError:(NSError * _Nullable)error;
+
+@end
+
+NS_ASSUME_NONNULL_END

src/darwin/Framework/CHIP/MTRDevice.h

@@ -16,6 +16,7 @@
  */
 
 #import <Foundation/Foundation.h>
+#import <Matter/MTRAttributeValueWaiter.h>
 #import <Matter/MTRBaseDevice.h>
 #import <Matter/MTRDefines.h>
 
@@ -337,6 +338,26 @@ MTR_AVAILABLE(ios(16.1), macos(13.0), watchos(9.1), tvos(16.1))
                     queue:(dispatch_queue_t)queue
                completion:(void (^)(NSURL * _Nullable url, NSError * _Nullable error))completion
     MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6));
+
+/**
+ * Sets up the provided completion to be called when any of the following
+ * happens:
+ *
+ * 1) A set of attributes reaches certain values: completion called with nil.
+ * 2) The provided timeout expires: completion called with MTRErrorCodeTimeout error.
+ * 3) The wait is canceled: completion called with MTRErrorCodeCancelled error.
+ *
+ * If the MTRAttributeValueWaiter is destroyed before the
+ * completion is called, that is treated the same as canceling the waiter.
+ *
+ * The attributes and values to wait for are represented as a dictionary which
+ * has the attribute paths as keys and the expected data-values as values.
+ */
+- (MTRAttributeValueWaiter *)waitForAttributeValues:(NSDictionary<MTRAttributePath *, NSDictionary<NSString *, id> *> *)values
+                                            timeout:(NSTimeInterval)timeout
+                                              queue:(dispatch_queue_t)queue
+                                         completion:(void (^)(NSError * _Nullable error))completion MTR_NEWLY_AVAILABLE;
+
 @end
 
 MTR_EXTERN NSString * const MTRPreviousDataKey MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6));