| /** |
| * 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 |
| |
| /** |
| * Class that configures how MTRDevice objects persist their attributes to storage, so as to not |
| * overwhelm the underlying storage system. |
| */ |
| MTR_AVAILABLE(ios(17.6), macos(14.6), watchos(10.6), tvos(17.6)) |
| @interface MTRDeviceStorageBehaviorConfiguration : NSObject <NSCopying> |
| |
| /** |
| * Create configuration with a default set of values. See description below for details. |
| */ |
| + (instancetype)configurationWithDefaultStorageBehavior; |
| |
| /** |
| * Create configuration that disables storage behavior optimizations. |
| */ |
| + (instancetype)configurationWithStorageBehaviorOptimizationDisabled; |
| |
| /** |
| * Create configuration with specified values. See description below for details, and the list of |
| * properties below for valid ranges of these values. |
| */ |
| + (instancetype)configurationWithReportToPersistenceDelayTime:(NSTimeInterval)reportToPersistenceDelayTime |
| reportToPersistenceDelayTimeMax:(NSTimeInterval)reportToPersistenceDelayTimeMax |
| recentReportTimesMaxCount:(NSUInteger)recentReportTimesMaxCount |
| timeBetweenReportsTooShortThreshold:(NSTimeInterval)timeBetweenReportsTooShortThreshold |
| timeBetweenReportsTooShortMinThreshold:(NSTimeInterval)timeBetweenReportsTooShortMinThreshold |
| reportToPersistenceDelayMaxMultiplier:(double)reportToPersistenceDelayMaxMultiplier |
| deviceReportingExcessivelyIntervalThreshold:(NSTimeInterval)deviceReportingExcessivelyIntervalThreshold; |
| |
| /** |
| * Storage behavior with values in the allowed range: |
| * |
| * Each time a report comes in, MTRDevice will wait reportToPersistDelayTime before persisting the |
| * changes to storage. If another report comes in during this internal, MTRDevice will wait another |
| * reportToPersistDelayTime interval, until reportToPersistDelayTimeMax is reached, at which |
| * point all the changes so far will be written to storage. |
| * |
| * MTRDevice will also track recentReportTimesMaxCount number of report times. If the running |
| * average time between reports dips below timeBetweenReportsTooShortThreshold, a portion of the |
| * reportToPersistenceDelayMaxMultiplier will be applied to both the reportToPersistenceDelayTime |
| * and reportToPersistenceDelayTimeMax. The multiplier will reach the max when the average time |
| * between reports reach timeBetweenReportsTooShortMinThreshold. |
| * |
| * When the running average time between reports dips below timeBetweenReportsTooShortMinThreshold |
| * for the first time, the time will be noted. If the device remains in this state for longer than |
| * deviceReportingExcessivelyIntervalThreshold, persistence will stop until the average time between |
| * reports go back above timeBetweenReportsTooShortMinThreshold. |
| */ |
| |
| /** |
| * If disableStorageBehaviorOptimization is set to YES, then all the waiting mechanism as described above |
| * is disabled. |
| */ |
| @property (nonatomic, assign) BOOL disableStorageBehaviorOptimization; |
| |
| /** |
| * If any of these properties are set to be out of the documented limits, these default values will |
| * be used to replace all of them: |
| * |
| * reportToPersistenceDelayTimeDefault (15) |
| * reportToPersistenceDelayTimeMaxDefault (20 * 15) |
| * recentReportTimesMaxCountDefault (12) |
| * timeBetweenReportsTooShortThresholdDefault (15) |
| * timeBetweenReportsTooShortMinThresholdDefault (5) |
| * reportToPersistenceDelayMaxMultiplierDefault (10) |
| * deviceReportingExcessivelyIntervalThresholdDefault (5 * 60) |
| */ |
| @property (nonatomic, assign) NSTimeInterval reportToPersistenceDelayTime; /* must be > 0 */ |
| @property (nonatomic, assign) NSTimeInterval reportToPersistenceDelayTimeMax; /* must be larger than reportToPersistenceDelayTime */ |
| @property (nonatomic, assign) NSUInteger recentReportTimesMaxCount; /* must be >= 2 */ |
| @property (nonatomic, assign) NSTimeInterval timeBetweenReportsTooShortThreshold; /* must be > 0 */ |
| @property (nonatomic, assign) NSTimeInterval timeBetweenReportsTooShortMinThreshold; /* must be > 0 and smaller than timeBetweenReportsTooShortThreshold */ |
| @property (nonatomic, assign) double reportToPersistenceDelayMaxMultiplier; /* must be > 1 */ |
| @property (nonatomic, assign) NSTimeInterval deviceReportingExcessivelyIntervalThreshold; /* must be > 0 */ |
| @end |
| |
| NS_ASSUME_NONNULL_END |