Line data Source code
1 : /*
2 : *
3 : * Copyright (c) 2023 Project CHIP Authors
4 : * All rights reserved.
5 : *
6 : * Licensed under the Apache License, Version 2.0 (the "License");
7 : * you may not use this file except in compliance with the License.
8 : * You may obtain a copy of the License at
9 : *
10 : * http://www.apache.org/licenses/LICENSE-2.0
11 : *
12 : * Unless required by applicable law or agreed to in writing, software
13 : * distributed under the License is distributed on an "AS IS" BASIS,
14 : * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 : * See the License for the specific language governing permissions and
16 : * limitations under the License.
17 : */
18 :
19 : #pragma once
20 :
21 : #include <app/reporting/ReportScheduler.h>
22 :
23 : namespace chip {
24 : namespace app {
25 : namespace reporting {
26 :
27 : /**
28 : * @class ReportSchedulerImpl
29 : *
30 : * @brief This class extends ReportScheduler and provides a scheduling logic for the CHIP Interaction Model Reporting Engine.
31 : *
32 : * It is responsible for implementing the ReadHandler and ICD observers callbacks so the Scheduler can take action whenever a
33 : * ReadHandler event occurs or the ICD mode change occurs.
34 : *
35 : * All ReadHandlers Observers callbacks rely on the node pool to create or find the node associated with the ReadHandler that
36 : * triggered the callback and will use the FindReadHandlerNode() method to do so.
37 : *
38 : * ## Scheduling Logic
39 : *
40 : * This class implements a scheduling logic that calculates the next report timeout based on the current system timestamp, the state
41 : * of the ReadHandlers associated with the scheduler nodes and the min and max intervals of the ReadHandlers.
42 : *
43 : * The logic is as follows:
44 : *
45 : * - When a ReadHandler is created for a subscription, the scheduler adds a node and registers it in the scheduler node pool.
46 : *
47 : * - Each node can schedule a report independently from the other nodes, and thus each node has its timer.
48 : *
49 : * - The timeout of each node timer is calculated when its associated ReadHandler becomes reportable, when a report is sent for
50 : * the ReadHandler.
51 : *
52 : * - The scheduler calculates the next report timeout of each node timer based on the current system timestamp and the state of the
53 : * ReadHandlers. If the ReadHandler is not reportable, the timeout is the difference between the next max interval and now. If the
54 : * ReadHandler is reportable, the timeout is the difference between the next min interval and now. If that min interval is in the
55 : * past, the scheduler directly calls the TimerFired() method instead of starting a timer.
56 : *
57 : *
58 :
59 : */
60 : class ReportSchedulerImpl : public ReportScheduler
61 : {
62 : public:
63 : using Timeout = System::Clock::Timeout;
64 :
65 : ReportSchedulerImpl(TimerDelegate * aTimerDelegate);
66 0 : ~ReportSchedulerImpl() override { UnregisterAllHandlers(); }
67 :
68 : // ICDStateObserver
69 :
70 : /**
71 : * @brief This implementation is not attempting any synchronization on external events as each Node is scheduled independently
72 : * solely based on its ReadHandler's state. Therefore, no synchronization action on the ICDState is needed in this
73 : * implementation.
74 : */
75 0 : void OnTransitionToIdle() override{};
76 :
77 : /**
78 : * @brief When the ICD transitions to Active mode, this implementation will trigger a report emission on each ReadHandler that
79 : * is not blocked by its min interval.
80 : *
81 : * @note Most of the actions that trigger a change to the Active mode already trigger a report emission (e.g. Event or Attribute
82 : * change), so this method is optional as it might be redundant.
83 : */
84 : void OnEnterActiveMode() override;
85 :
86 : /**
87 : * @brief Similar to the OnTransitionToIdle() method, this implementation does not attempt any synchronization on ICD events,
88 : * therefore no action is needed on the ICDModeChange() method.
89 : */
90 0 : void OnICDModeChange() override{};
91 :
92 : /**
93 : * @brief This implementation does not attempt any synchronization on this ICD event, therefore no action is needed on
94 : * ICDEnterIdleMode()
95 : */
96 0 : void OnEnterIdleMode() override{};
97 :
98 : // ReadHandlerObserver
99 :
100 : /**
101 : * @brief When a ReadHandler is created for a subscription, the scheduler adds a node and registers it in the scheduler node
102 : * pool. Scheduling the report here is unnecessary since the ReadHandler will call
103 : * MoveToState(HandlerState::CanStartReporting);, which will call OnBecameReportable() and schedule a report.
104 : *
105 : * @note This method sets a timestamp to the call time that is used as an input parameter by the ScheduleReport method.
106 : */
107 : void OnSubscriptionEstablished(ReadHandler * aReadHandler) final;
108 :
109 : /**
110 : * @brief When a ReadHandler becomes reportable, recalculate and reschedule the report.
111 : *
112 : * @note This method sets a now Timestamp that is used to calculate the next report timeout.
113 : */
114 : void OnBecameReportable(ReadHandler * aReadHandler) final;
115 :
116 : /**
117 : * @brief When a ReadHandler report is sent, recalculate and reschedule the report.
118 : *
119 : * @note This method sets a now Timestamp that is used to calculate the next report timeout.
120 : */
121 : void OnSubscriptionReportSent(ReadHandler * aReadHandler) final;
122 :
123 : /**
124 : * @brief When a ReadHandler is destroyed, remove the node from the scheduler node pool and cancel the timer associated to it.
125 : */
126 : void OnReadHandlerDestroyed(ReadHandler * aReadHandler) override;
127 :
128 : /**
129 : * @brief Checks if a report is scheduled for the ReadHandler by checking if the timer is active.
130 : *
131 : * @note If the CalculateNextReportTimeout outputs 0, the TimerFired() will be called directly instead of starting a timer,
132 : * so this method will return false.
133 : */
134 : virtual bool IsReportScheduled(ReadHandler * aReadHandler);
135 :
136 : void ReportTimerCallback() override;
137 :
138 : protected:
139 : /**
140 : * @brief Schedule a report for the ReadHandler associated with a ReadHandlerNode.
141 : *
142 : * @note If a report is already scheduled for the ReadHandler, this method will cancel it and schedule a new one.
143 : *
144 : * @param[in] timeout The timeout to schedule the report.
145 : * @param[in] node The node associated with the ReadHandler.
146 : * @param[in] now The current system timestamp.
147 : *
148 : * @return CHIP_ERROR CHIP_NO_ERROR on success, timer-related error code otherwise (This can only fail on starting the timer)
149 : */
150 : virtual CHIP_ERROR ScheduleReport(Timeout timeout, ReadHandlerNode * node, const Timestamp & now);
151 : void CancelReport(ReadHandler * aReadHandler);
152 : virtual void UnregisterAllHandlers();
153 :
154 : private:
155 : friend class chip::app::reporting::TestReportScheduler;
156 :
157 : /**
158 : * @brief Find the next timestamp when a report should be scheduled for a ReadHandler.
159 : *
160 : * @param[out] timeout The timeout calculated from the "now" timestamp provided as an input parameter.
161 : * @param[in] aNode The node associated to the ReadHandler.
162 : * @param[in] now The current system timestamp.
163 : *
164 : * @return CHIP_ERROR CHIP_NO_ERROR on success or CHIP_ERROR_INVALID_ARGUMENT if aNode is not in the pool.
165 : *
166 : */
167 : virtual CHIP_ERROR CalculateNextReportTimeout(Timeout & timeout, ReadHandlerNode * aNode, const Timestamp & now);
168 : };
169 :
170 : } // namespace reporting
171 : } // namespace app
172 : } // namespace chip
|
