ESPHome  2024.10.2
scheduler.cpp
Go to the documentation of this file.
1 #include "scheduler.h"
2 #include "esphome/core/log.h"
3 #include "esphome/core/helpers.h"
4 #include "esphome/core/hal.h"
5 #include <algorithm>
6 #include <cinttypes>
7 
8 namespace esphome {
9 
10 static const char *const TAG = "scheduler";
11 
12 static const uint32_t MAX_LOGICALLY_DELETED_ITEMS = 10;
13 
14 // Uncomment to debug scheduler
15 // #define ESPHOME_DEBUG_SCHEDULER
16 
17 // A note on locking: the `lock_` lock protects the `items_` and `to_add_` containers. It must be taken when writing to
18 // them (i.e. when adding/removing items, but not when changing items). As items are only deleted from the loop task,
19 // iterating over them from the loop task is fine; but iterating from any other context requires the lock to be held to
20 // avoid the main thread modifying the list while it is being accessed.
21 
22 void HOT Scheduler::set_timeout(Component *component, const std::string &name, uint32_t timeout,
23  std::function<void()> func) {
24  const uint32_t now = this->millis_();
25 
26  if (!name.empty())
27  this->cancel_timeout(component, name);
28 
29  if (timeout == SCHEDULER_DONT_RUN)
30  return;
31 
32  ESP_LOGVV(TAG, "set_timeout(name='%s', timeout=%" PRIu32 ")", name.c_str(), timeout);
33 
34  auto item = make_unique<SchedulerItem>();
35  item->component = component;
36  item->name = name;
37  item->type = SchedulerItem::TIMEOUT;
38  item->timeout = timeout;
39  item->last_execution = now;
40  item->last_execution_major = this->millis_major_;
41  item->callback = std::move(func);
42  item->remove = false;
43  this->push_(std::move(item));
44 }
45 bool HOT Scheduler::cancel_timeout(Component *component, const std::string &name) {
46  return this->cancel_item_(component, name, SchedulerItem::TIMEOUT);
47 }
48 void HOT Scheduler::set_interval(Component *component, const std::string &name, uint32_t interval,
49  std::function<void()> func) {
50  const uint32_t now = this->millis_();
51 
52  if (!name.empty())
53  this->cancel_interval(component, name);
54 
55  if (interval == SCHEDULER_DONT_RUN)
56  return;
57 
58  // only put offset in lower half
59  uint32_t offset = 0;
60  if (interval != 0)
61  offset = (random_uint32() % interval) / 2;
62 
63  ESP_LOGVV(TAG, "set_interval(name='%s', interval=%" PRIu32 ", offset=%" PRIu32 ")", name.c_str(), interval, offset);
64 
65  auto item = make_unique<SchedulerItem>();
66  item->component = component;
67  item->name = name;
68  item->type = SchedulerItem::INTERVAL;
69  item->interval = interval;
70  item->last_execution = now - offset - interval;
71  item->last_execution_major = this->millis_major_;
72  if (item->last_execution > now)
73  item->last_execution_major--;
74  item->callback = std::move(func);
75  item->remove = false;
76  this->push_(std::move(item));
77 }
78 bool HOT Scheduler::cancel_interval(Component *component, const std::string &name) {
79  return this->cancel_item_(component, name, SchedulerItem::INTERVAL);
80 }
81 
82 struct RetryArgs {
83  std::function<RetryResult(uint8_t)> func;
84  uint8_t retry_countdown;
85  uint32_t current_interval;
86  Component *component;
87  std::string name;
88  float backoff_increase_factor;
89  Scheduler *scheduler;
90 };
91 
92 static void retry_handler(const std::shared_ptr<RetryArgs> &args) {
93  RetryResult const retry_result = args->func(--args->retry_countdown);
94  if (retry_result == RetryResult::DONE || args->retry_countdown <= 0)
95  return;
96  // second execution of `func` happens after `initial_wait_time`
97  args->scheduler->set_timeout(args->component, args->name, args->current_interval, [args]() { retry_handler(args); });
98  // backoff_increase_factor applied to third & later executions
99  args->current_interval *= args->backoff_increase_factor;
100 }
101 
102 void HOT Scheduler::set_retry(Component *component, const std::string &name, uint32_t initial_wait_time,
103  uint8_t max_attempts, std::function<RetryResult(uint8_t)> func,
104  float backoff_increase_factor) {
105  if (!name.empty())
106  this->cancel_retry(component, name);
107 
108  if (initial_wait_time == SCHEDULER_DONT_RUN)
109  return;
110 
111  ESP_LOGVV(TAG, "set_retry(name='%s', initial_wait_time=%" PRIu32 ", max_attempts=%u, backoff_factor=%0.1f)",
112  name.c_str(), initial_wait_time, max_attempts, backoff_increase_factor);
113 
114  if (backoff_increase_factor < 0.0001) {
115  ESP_LOGE(TAG,
116  "set_retry(name='%s'): backoff_factor cannot be close to zero nor negative (%0.1f). Using 1.0 instead",
117  name.c_str(), backoff_increase_factor);
118  backoff_increase_factor = 1;
119  }
120 
121  auto args = std::make_shared<RetryArgs>();
122  args->func = std::move(func);
123  args->retry_countdown = max_attempts;
124  args->current_interval = initial_wait_time;
125  args->component = component;
126  args->name = "retry$" + name;
127  args->backoff_increase_factor = backoff_increase_factor;
128  args->scheduler = this;
129 
130  // First execution of `func` immediately
131  this->set_timeout(component, args->name, 0, [args]() { retry_handler(args); });
132 }
133 bool HOT Scheduler::cancel_retry(Component *component, const std::string &name) {
134  return this->cancel_timeout(component, "retry$" + name);
135 }
136 
138  if (this->empty_())
139  return {};
140  auto &item = this->items_[0];
141  const uint32_t now = this->millis_();
142  uint32_t next_time = item->last_execution + item->interval;
143  if (next_time < now)
144  return 0;
145  return next_time - now;
146 }
147 void HOT Scheduler::call() {
148  const uint32_t now = this->millis_();
149  this->process_to_add();
150 
151 #ifdef ESPHOME_DEBUG_SCHEDULER
152  static uint32_t last_print = 0;
153 
154  if (now - last_print > 2000) {
155  last_print = now;
156  std::vector<std::unique_ptr<SchedulerItem>> old_items;
157  ESP_LOGVV(TAG, "Items: count=%u, now=%" PRIu32, this->items_.size(), now);
158  while (!this->empty_()) {
159  this->lock_.lock();
160  auto item = std::move(this->items_[0]);
161  this->pop_raw_();
162  this->lock_.unlock();
163 
164  ESP_LOGVV(TAG, " %s '%s' interval=%" PRIu32 " last_execution=%" PRIu32 " (%u) next=%" PRIu32 " (%u)",
165  item->get_type_str(), item->name.c_str(), item->interval, item->last_execution,
166  item->last_execution_major, item->next_execution(), item->next_execution_major());
167 
168  old_items.push_back(std::move(item));
169  }
170  ESP_LOGVV(TAG, "\n");
171 
172  {
173  LockGuard guard{this->lock_};
174  this->items_ = std::move(old_items);
175  }
176  }
177 #endif // ESPHOME_DEBUG_SCHEDULER
178 
179  auto to_remove_was = to_remove_;
180  auto items_was = this->items_.size();
181  // If we have too many items to remove
182  if (to_remove_ > MAX_LOGICALLY_DELETED_ITEMS) {
183  std::vector<std::unique_ptr<SchedulerItem>> valid_items;
184  while (!this->empty_()) {
185  LockGuard guard{this->lock_};
186  auto item = std::move(this->items_[0]);
187  this->pop_raw_();
188  valid_items.push_back(std::move(item));
189  }
190 
191  {
192  LockGuard guard{this->lock_};
193  this->items_ = std::move(valid_items);
194  }
195 
196  // The following should not happen unless I'm missing something
197  if (to_remove_ != 0) {
198  ESP_LOGW(TAG, "to_remove_ was %" PRIu32 " now: %" PRIu32 " items where %zu now %zu. Please report this",
199  to_remove_was, to_remove_, items_was, items_.size());
200  to_remove_ = 0;
201  }
202  }
203 
204  while (!this->empty_()) {
205  // use scoping to indicate visibility of `item` variable
206  {
207  // Don't copy-by value yet
208  auto &item = this->items_[0];
209  if ((now - item->last_execution) < item->interval) {
210  // Not reached timeout yet, done for this call
211  break;
212  }
213  uint8_t major = item->next_execution_major();
214  if (this->millis_major_ - major > 1)
215  break;
216 
217  // Don't run on failed components
218  if (item->component != nullptr && item->component->is_failed()) {
219  LockGuard guard{this->lock_};
220  this->pop_raw_();
221  continue;
222  }
223 
224 #ifdef ESPHOME_LOG_HAS_VERY_VERBOSE
225  ESP_LOGVV(TAG, "Running %s '%s' with interval=%" PRIu32 " last_execution=%" PRIu32 " (now=%" PRIu32 ")",
226  item->get_type_str(), item->name.c_str(), item->interval, item->last_execution, now);
227 #endif
228 
229  // Warning: During callback(), a lot of stuff can happen, including:
230  // - timeouts/intervals get added, potentially invalidating vector pointers
231  // - timeouts/intervals get cancelled
232  {
233  WarnIfComponentBlockingGuard guard{item->component};
234  item->callback();
235  }
236  }
237 
238  {
239  this->lock_.lock();
240 
241  // new scope, item from before might have been moved in the vector
242  auto item = std::move(this->items_[0]);
243 
244  // Only pop after function call, this ensures we were reachable
245  // during the function call and know if we were cancelled.
246  this->pop_raw_();
247 
248  this->lock_.unlock();
249 
250  if (item->remove) {
251  // We were removed/cancelled in the function call, stop
252  to_remove_--;
253  continue;
254  }
255 
256  if (item->type == SchedulerItem::INTERVAL) {
257  if (item->interval != 0) {
258  const uint32_t before = item->last_execution;
259  const uint32_t amount = (now - item->last_execution) / item->interval;
260  item->last_execution += amount * item->interval;
261  if (item->last_execution < before)
262  item->last_execution_major++;
263  }
264  this->push_(std::move(item));
265  }
266  }
267  }
268 
269  this->process_to_add();
270 }
272  LockGuard guard{this->lock_};
273  for (auto &it : this->to_add_) {
274  if (it->remove) {
275  continue;
276  }
277 
278  this->items_.push_back(std::move(it));
279  std::push_heap(this->items_.begin(), this->items_.end(), SchedulerItem::cmp);
280  }
281  this->to_add_.clear();
282 }
284  while (!this->items_.empty()) {
285  auto &item = this->items_[0];
286  if (!item->remove)
287  return;
288 
289  to_remove_--;
290 
291  {
292  LockGuard guard{this->lock_};
293  this->pop_raw_();
294  }
295  }
296 }
298  std::pop_heap(this->items_.begin(), this->items_.end(), SchedulerItem::cmp);
299  this->items_.pop_back();
300 }
301 void HOT Scheduler::push_(std::unique_ptr<Scheduler::SchedulerItem> item) {
302  LockGuard guard{this->lock_};
303  this->to_add_.push_back(std::move(item));
304 }
305 bool HOT Scheduler::cancel_item_(Component *component, const std::string &name, Scheduler::SchedulerItem::Type type) {
306  // obtain lock because this function iterates and can be called from non-loop task context
307  LockGuard guard{this->lock_};
308  bool ret = false;
309  for (auto &it : this->items_) {
310  if (it->component == component && it->name == name && it->type == type && !it->remove) {
311  to_remove_++;
312  it->remove = true;
313  ret = true;
314  }
315  }
316  for (auto &it : this->to_add_) {
317  if (it->component == component && it->name == name && it->type == type) {
318  it->remove = true;
319  ret = true;
320  }
321  }
322 
323  return ret;
324 }
325 uint32_t Scheduler::millis_() {
326  const uint32_t now = millis();
327  if (now < this->last_millis_) {
328  ESP_LOGD(TAG, "Incrementing scheduler major");
329  this->millis_major_++;
330  }
331  this->last_millis_ = now;
332  return now;
333 }
334 
335 bool HOT Scheduler::SchedulerItem::cmp(const std::unique_ptr<SchedulerItem> &a,
336  const std::unique_ptr<SchedulerItem> &b) {
337  // min-heap
338  // return true if *a* will happen after *b*
339  uint32_t a_next_exec = a->next_execution();
340  uint8_t a_next_exec_major = a->next_execution_major();
341  uint32_t b_next_exec = b->next_execution();
342  uint8_t b_next_exec_major = b->next_execution_major();
343 
344  if (a_next_exec_major != b_next_exec_major) {
345  // The "major" calculation is quite complicated.
346  // Basically, we need to check if the major value lies in the future or
347  //
348 
349  // Here are some cases to think about:
350  // Format: a_major,b_major -> expected result (a-b, b-a)
351  // a=255,b=0 -> false (255, 1)
352  // a=0,b=1 -> false (255, 1)
353  // a=1,b=0 -> true (1, 255)
354  // a=0,b=255 -> true (1, 255)
355 
356  uint8_t diff1 = a_next_exec_major - b_next_exec_major;
357  uint8_t diff2 = b_next_exec_major - a_next_exec_major;
358  return diff1 < diff2;
359  }
360 
361  return a_next_exec > b_next_exec;
362 }
363 
364 } // namespace esphome
uint32_t to_remove_
Definition: scheduler.h:81
const char * name
Definition: stm32flash.h:78
RetryResult
Definition: component.h:66
void push_(std::unique_ptr< SchedulerItem > item)
Definition: scheduler.cpp:301
uint32_t random_uint32()
Return a random 32-bit unsigned integer.
Definition: helpers.cpp:191
bool cancel_timeout(Component *component, const std::string &name)
Definition: scheduler.cpp:45
optional< uint32_t > next_schedule_in()
Definition: scheduler.cpp:137
uint32_t IRAM_ATTR HOT millis()
Definition: core.cpp:25
uint8_t millis_major_
Definition: scheduler.h:80
const char *const TAG
Definition: spi.cpp:8
void set_retry(Component *component, const std::string &name, uint32_t initial_wait_time, uint8_t max_attempts, std::function< RetryResult(uint8_t)> func, float backoff_increase_factor=1.0f)
Definition: scheduler.cpp:102
uint32_t millis_()
Definition: scheduler.cpp:325
std::vector< std::unique_ptr< SchedulerItem > > to_add_
Definition: scheduler.h:78
uint8_t type
bool cancel_retry(Component *component, const std::string &name)
Definition: scheduler.cpp:133
uint32_t last_millis_
Definition: scheduler.h:79
bool cancel_item_(Component *component, const std::string &name, SchedulerItem::Type type)
Definition: scheduler.cpp:305
static bool cmp(const std::unique_ptr< SchedulerItem > &a, const std::unique_ptr< SchedulerItem > &b)
Definition: scheduler.cpp:335
bool cancel_interval(Component *component, const std::string &name)
Definition: scheduler.cpp:78
void set_timeout(Component *component, const std::string &name, uint32_t timeout, std::function< void()> func)
Definition: scheduler.cpp:22
Implementation of SPI Controller mode.
Definition: a01nyub.cpp:7
void unlock()
Definition: helpers.cpp:624
std::vector< std::unique_ptr< SchedulerItem > > items_
Definition: scheduler.h:77
Helper class that wraps a mutex with a RAII-style API.
Definition: helpers.h:564
void set_interval(Component *component, const std::string &name, uint32_t interval, std::function< void()> func)
Definition: scheduler.cpp:48