ESPHome 2025.7.1
Loading...
Searching...
No Matches
scheduler.cpp
Go to the documentation of this file.
1#include "scheduler.h"
2
3#include "application.h"
5#include "esphome/core/hal.h"
7#include "esphome/core/log.h"
8#include <algorithm>
9#include <cinttypes>
10#include <cstring>
11
12namespace esphome {
13
14static const char *const TAG = "scheduler";
15
16static const uint32_t MAX_LOGICALLY_DELETED_ITEMS = 10;
17
18// Uncomment to debug scheduler
19// #define ESPHOME_DEBUG_SCHEDULER
20
21#ifdef ESPHOME_DEBUG_SCHEDULER
22// Helper to validate that a pointer looks like it's in static memory
23static void validate_static_string(const char *name) {
24 if (name == nullptr)
25 return;
26
27 // This is a heuristic check - stack and heap pointers are typically
28 // much higher in memory than static data
29 uintptr_t addr = reinterpret_cast<uintptr_t>(name);
30
31 // Create a stack variable to compare against
32 int stack_var;
33 uintptr_t stack_addr = reinterpret_cast<uintptr_t>(&stack_var);
34
35 // If the string pointer is near our stack variable, it's likely on the stack
36 // Using 8KB range as ESP32 main task stack is typically 8192 bytes
37 if (addr > (stack_addr - 0x2000) && addr < (stack_addr + 0x2000)) {
38 ESP_LOGW(TAG,
39 "WARNING: Scheduler name '%s' at %p appears to be on the stack - this is unsafe!\n"
40 " Stack reference at %p",
41 name, name, &stack_var);
42 }
43
44 // Also check if it might be on the heap by seeing if it's in a very different range
45 // This is platform-specific but generally heap is allocated far from static memory
46 static const char *static_str = "test";
47 uintptr_t static_addr = reinterpret_cast<uintptr_t>(static_str);
48
49 // If the address is very far from known static memory, it might be heap
50 if (addr > static_addr + 0x100000 || (static_addr > 0x100000 && addr < static_addr - 0x100000)) {
51 ESP_LOGW(TAG, "WARNING: Scheduler name '%s' at %p might be on heap (static ref at %p)", name, name, static_str);
52 }
53}
54#endif
55
56// A note on locking: the `lock_` lock protects the `items_` and `to_add_` containers. It must be taken when writing to
57// them (i.e. when adding/removing items, but not when changing items). As items are only deleted from the loop task,
58// iterating over them from the loop task is fine; but iterating from any other context requires the lock to be held to
59// avoid the main thread modifying the list while it is being accessed.
60
61// Common implementation for both timeout and interval
62void HOT Scheduler::set_timer_common_(Component *component, SchedulerItem::Type type, bool is_static_string,
63 const void *name_ptr, uint32_t delay, std::function<void()> func) {
64 // Get the name as const char*
65 const char *name_cstr = this->get_name_cstr_(is_static_string, name_ptr);
66
67 if (delay == SCHEDULER_DONT_RUN) {
68 // Still need to cancel existing timer if name is not empty
69 LockGuard guard{this->lock_};
70 this->cancel_item_locked_(component, name_cstr, type);
71 return;
72 }
73
74 // Create and populate the scheduler item
75 auto item = make_unique<SchedulerItem>();
76 item->component = component;
77 item->set_name(name_cstr, !is_static_string);
78 item->type = type;
79 item->callback = std::move(func);
80 item->remove = false;
81
82#if !defined(USE_ESP8266) && !defined(USE_RP2040)
83 // Special handling for defer() (delay = 0, type = TIMEOUT)
84 // ESP8266 and RP2040 are excluded because they don't need thread-safe defer handling
85 if (delay == 0 && type == SchedulerItem::TIMEOUT) {
86 // Put in defer queue for guaranteed FIFO execution
87 LockGuard guard{this->lock_};
88 this->cancel_item_locked_(component, name_cstr, type);
89 this->defer_queue_.push_back(std::move(item));
90 return;
91 }
92#endif
93
94 const auto now = this->millis_();
95
96 // Type-specific setup
97 if (type == SchedulerItem::INTERVAL) {
98 item->interval = delay;
99 // Calculate random offset (0 to interval/2)
100 uint32_t offset = (delay != 0) ? (random_uint32() % delay) / 2 : 0;
101 item->next_execution_ = now + offset;
102 } else {
103 item->interval = 0;
104 item->next_execution_ = now + delay;
105 }
106
107#ifdef ESPHOME_DEBUG_SCHEDULER
108 // Validate static strings in debug mode
109 if (is_static_string && name_cstr != nullptr) {
110 validate_static_string(name_cstr);
111 }
112
113 // Debug logging
114 const char *type_str = (type == SchedulerItem::TIMEOUT) ? "timeout" : "interval";
116 ESP_LOGD(TAG, "set_%s(name='%s/%s', %s=%" PRIu32 ")", type_str, item->get_source(),
117 name_cstr ? name_cstr : "(null)", type_str, delay);
118 } else {
119 ESP_LOGD(TAG, "set_%s(name='%s/%s', %s=%" PRIu32 ", offset=%" PRIu32 ")", type_str, item->get_source(),
120 name_cstr ? name_cstr : "(null)", type_str, delay, static_cast<uint32_t>(item->next_execution_ - now));
121 }
122#endif
123
124 LockGuard guard{this->lock_};
125 // If name is provided, do atomic cancel-and-add
126 // Cancel existing items
127 this->cancel_item_locked_(component, name_cstr, type);
128 // Add new item directly to to_add_
129 // since we have the lock held
130 this->to_add_.push_back(std::move(item));
131}
132
133void HOT Scheduler::set_timeout(Component *component, const char *name, uint32_t timeout, std::function<void()> func) {
134 this->set_timer_common_(component, SchedulerItem::TIMEOUT, true, name, timeout, std::move(func));
135}
136
137void HOT Scheduler::set_timeout(Component *component, const std::string &name, uint32_t timeout,
138 std::function<void()> func) {
139 this->set_timer_common_(component, SchedulerItem::TIMEOUT, false, &name, timeout, std::move(func));
140}
141bool HOT Scheduler::cancel_timeout(Component *component, const std::string &name) {
142 return this->cancel_item_(component, false, &name, SchedulerItem::TIMEOUT);
143}
144bool HOT Scheduler::cancel_timeout(Component *component, const char *name) {
145 return this->cancel_item_(component, true, name, SchedulerItem::TIMEOUT);
146}
147void HOT Scheduler::set_interval(Component *component, const std::string &name, uint32_t interval,
148 std::function<void()> func) {
149 this->set_timer_common_(component, SchedulerItem::INTERVAL, false, &name, interval, std::move(func));
150}
151
152void HOT Scheduler::set_interval(Component *component, const char *name, uint32_t interval,
153 std::function<void()> func) {
154 this->set_timer_common_(component, SchedulerItem::INTERVAL, true, name, interval, std::move(func));
155}
156bool HOT Scheduler::cancel_interval(Component *component, const std::string &name) {
157 return this->cancel_item_(component, false, &name, SchedulerItem::INTERVAL);
158}
159bool HOT Scheduler::cancel_interval(Component *component, const char *name) {
160 return this->cancel_item_(component, true, name, SchedulerItem::INTERVAL);
161}
162
163struct RetryArgs {
164 std::function<RetryResult(uint8_t)> func;
165 uint8_t retry_countdown;
166 uint32_t current_interval;
167 Component *component;
168 std::string name; // Keep as std::string since retry uses it dynamically
169 float backoff_increase_factor;
170 Scheduler *scheduler;
171};
172
173static void retry_handler(const std::shared_ptr<RetryArgs> &args) {
174 RetryResult const retry_result = args->func(--args->retry_countdown);
175 if (retry_result == RetryResult::DONE || args->retry_countdown <= 0)
176 return;
177 // second execution of `func` happens after `initial_wait_time`
178 args->scheduler->set_timeout(args->component, args->name, args->current_interval, [args]() { retry_handler(args); });
179 // backoff_increase_factor applied to third & later executions
180 args->current_interval *= args->backoff_increase_factor;
181}
182
183void HOT Scheduler::set_retry(Component *component, const std::string &name, uint32_t initial_wait_time,
184 uint8_t max_attempts, std::function<RetryResult(uint8_t)> func,
185 float backoff_increase_factor) {
186 if (!name.empty())
187 this->cancel_retry(component, name);
188
189 if (initial_wait_time == SCHEDULER_DONT_RUN)
190 return;
191
192 ESP_LOGVV(TAG, "set_retry(name='%s', initial_wait_time=%" PRIu32 ", max_attempts=%u, backoff_factor=%0.1f)",
193 name.c_str(), initial_wait_time, max_attempts, backoff_increase_factor);
194
195 if (backoff_increase_factor < 0.0001) {
196 ESP_LOGE(TAG,
197 "set_retry(name='%s'): backoff_factor cannot be close to zero nor negative (%0.1f). Using 1.0 instead",
198 name.c_str(), backoff_increase_factor);
199 backoff_increase_factor = 1;
200 }
201
202 auto args = std::make_shared<RetryArgs>();
203 args->func = std::move(func);
204 args->retry_countdown = max_attempts;
205 args->current_interval = initial_wait_time;
206 args->component = component;
207 args->name = "retry$" + name;
208 args->backoff_increase_factor = backoff_increase_factor;
209 args->scheduler = this;
210
211 // First execution of `func` immediately
212 this->set_timeout(component, args->name, 0, [args]() { retry_handler(args); });
213}
214bool HOT Scheduler::cancel_retry(Component *component, const std::string &name) {
215 return this->cancel_timeout(component, "retry$" + name);
216}
217
219 // IMPORTANT: This method should only be called from the main thread (loop task).
220 // It calls empty_() and accesses items_[0] without holding a lock, which is only
221 // safe when called from the main thread. Other threads must not call this method.
222 if (this->empty_())
223 return {};
224 auto &item = this->items_[0];
225 const auto now = this->millis_();
226 if (item->next_execution_ < now)
227 return 0;
228 return item->next_execution_ - now;
229}
230void HOT Scheduler::call() {
231#if !defined(USE_ESP8266) && !defined(USE_RP2040)
232 // Process defer queue first to guarantee FIFO execution order for deferred items.
233 // Previously, defer() used the heap which gave undefined order for equal timestamps,
234 // causing race conditions on multi-core systems (ESP32, BK7200).
235 // With the defer queue:
236 // - Deferred items (delay=0) go directly to defer_queue_ in set_timer_common_
237 // - Items execute in exact order they were deferred (FIFO guarantee)
238 // - No deferred items exist in to_add_, so processing order doesn't affect correctness
239 // ESP8266 and RP2040 don't use this queue - they fall back to the heap-based approach
240 // (ESP8266: single-core, RP2040: empty mutex implementation).
241 //
242 // Note: Items cancelled via cancel_item_locked_() are marked with remove=true but still
243 // processed here. They are removed from the queue normally via pop_front() but skipped
244 // during execution by should_skip_item_(). This is intentional - no memory leak occurs.
245 while (!this->defer_queue_.empty()) {
246 // The outer check is done without a lock for performance. If the queue
247 // appears non-empty, we lock and process an item. We don't need to check
248 // empty() again inside the lock because only this thread can remove items.
249 std::unique_ptr<SchedulerItem> item;
250 {
251 LockGuard lock(this->lock_);
252 item = std::move(this->defer_queue_.front());
253 this->defer_queue_.pop_front();
254 }
255
256 // Execute callback without holding lock to prevent deadlocks
257 // if the callback tries to call defer() again
258 if (!this->should_skip_item_(item.get())) {
259 this->execute_item_(item.get());
260 }
261 }
262#endif
263
264 const auto now = this->millis_();
265 this->process_to_add();
266
267#ifdef ESPHOME_DEBUG_SCHEDULER
268 static uint64_t last_print = 0;
269
270 if (now - last_print > 2000) {
271 last_print = now;
272 std::vector<std::unique_ptr<SchedulerItem>> old_items;
273 ESP_LOGD(TAG, "Items: count=%zu, now=%" PRIu64 " (%u, %" PRIu32 ")", this->items_.size(), now, this->millis_major_,
274 this->last_millis_);
275 while (!this->empty_()) {
276 std::unique_ptr<SchedulerItem> item;
277 {
278 LockGuard guard{this->lock_};
279 item = std::move(this->items_[0]);
280 this->pop_raw_();
281 }
282
283 const char *name = item->get_name();
284 ESP_LOGD(TAG, " %s '%s/%s' interval=%" PRIu32 " next_execution in %" PRIu64 "ms at %" PRIu64,
285 item->get_type_str(), item->get_source(), name ? name : "(null)", item->interval,
286 item->next_execution_ - now, item->next_execution_);
287
288 old_items.push_back(std::move(item));
289 }
290 ESP_LOGD(TAG, "\n");
291
292 {
293 LockGuard guard{this->lock_};
294 this->items_ = std::move(old_items);
295 // Rebuild heap after moving items back
296 std::make_heap(this->items_.begin(), this->items_.end(), SchedulerItem::cmp);
297 }
298 }
299#endif // ESPHOME_DEBUG_SCHEDULER
300
301 // If we have too many items to remove
302 if (this->to_remove_ > MAX_LOGICALLY_DELETED_ITEMS) {
303 // We hold the lock for the entire cleanup operation because:
304 // 1. We're rebuilding the entire items_ list, so we need exclusive access throughout
305 // 2. Other threads must see either the old state or the new state, not intermediate states
306 // 3. The operation is already expensive (O(n)), so lock overhead is negligible
307 // 4. No operations inside can block or take other locks, so no deadlock risk
308 LockGuard guard{this->lock_};
309
310 std::vector<std::unique_ptr<SchedulerItem>> valid_items;
311
312 // Move all non-removed items to valid_items
313 for (auto &item : this->items_) {
314 if (!item->remove) {
315 valid_items.push_back(std::move(item));
316 }
317 }
318
319 // Replace items_ with the filtered list
320 this->items_ = std::move(valid_items);
321 // Rebuild the heap structure since items are no longer in heap order
322 std::make_heap(this->items_.begin(), this->items_.end(), SchedulerItem::cmp);
323 this->to_remove_ = 0;
324 }
325
326 while (!this->empty_()) {
327 // use scoping to indicate visibility of `item` variable
328 {
329 // Don't copy-by value yet
330 auto &item = this->items_[0];
331 if (item->next_execution_ > now) {
332 // Not reached timeout yet, done for this call
333 break;
334 }
335 // Don't run on failed components
336 if (item->component != nullptr && item->component->is_failed()) {
337 LockGuard guard{this->lock_};
338 this->pop_raw_();
339 continue;
340 }
341#ifdef ESPHOME_DEBUG_SCHEDULER
342 const char *item_name = item->get_name();
343 ESP_LOGV(TAG, "Running %s '%s/%s' with interval=%" PRIu32 " next_execution=%" PRIu64 " (now=%" PRIu64 ")",
344 item->get_type_str(), item->get_source(), item_name ? item_name : "(null)", item->interval,
345 item->next_execution_, now);
346#endif
347
348 // Warning: During callback(), a lot of stuff can happen, including:
349 // - timeouts/intervals get added, potentially invalidating vector pointers
350 // - timeouts/intervals get cancelled
351 this->execute_item_(item.get());
352 }
353
354 {
355 LockGuard guard{this->lock_};
356
357 // new scope, item from before might have been moved in the vector
358 auto item = std::move(this->items_[0]);
359 // Only pop after function call, this ensures we were reachable
360 // during the function call and know if we were cancelled.
361 this->pop_raw_();
362
363 if (item->remove) {
364 // We were removed/cancelled in the function call, stop
365 this->to_remove_--;
366 continue;
367 }
368
369 if (item->type == SchedulerItem::INTERVAL) {
370 item->next_execution_ = now + item->interval;
371 // Add new item directly to to_add_
372 // since we have the lock held
373 this->to_add_.push_back(std::move(item));
374 }
375 }
376 }
377
378 this->process_to_add();
379}
381 LockGuard guard{this->lock_};
382 for (auto &it : this->to_add_) {
383 if (it->remove) {
384 continue;
385 }
386
387 this->items_.push_back(std::move(it));
388 std::push_heap(this->items_.begin(), this->items_.end(), SchedulerItem::cmp);
389 }
390 this->to_add_.clear();
391}
393 // Fast path: if nothing to remove, just return
394 // Reading to_remove_ without lock is safe because:
395 // 1. We only call this from the main thread during call()
396 // 2. If it's 0, there's definitely nothing to cleanup
397 // 3. If it becomes non-zero after we check, cleanup will happen on the next loop iteration
398 // 4. Not all platforms support atomics, so we accept this race in favor of performance
399 // 5. The worst case is a one-loop-iteration delay in cleanup, which is harmless
400 if (this->to_remove_ == 0)
401 return;
402
403 // We must hold the lock for the entire cleanup operation because:
404 // 1. We're modifying items_ (via pop_raw_) which requires exclusive access
405 // 2. We're decrementing to_remove_ which is also modified by other threads
406 // (though all modifications are already under lock)
407 // 3. Other threads read items_ when searching for items to cancel in cancel_item_locked_()
408 // 4. We need a consistent view of items_ and to_remove_ throughout the operation
409 // Without the lock, we could access items_ while another thread is reading it,
410 // leading to race conditions
411 LockGuard guard{this->lock_};
412 while (!this->items_.empty()) {
413 auto &item = this->items_[0];
414 if (!item->remove)
415 return;
416 this->to_remove_--;
417 this->pop_raw_();
418 }
419}
421 std::pop_heap(this->items_.begin(), this->items_.end(), SchedulerItem::cmp);
422 this->items_.pop_back();
423}
424
425// Helper to execute a scheduler item
426void HOT Scheduler::execute_item_(SchedulerItem *item) {
427 App.set_current_component(item->component);
428
429 uint32_t now_ms = millis();
430 WarnIfComponentBlockingGuard guard{item->component, now_ms};
431 item->callback();
432 guard.finish();
433}
434
435// Common implementation for cancel operations
436bool HOT Scheduler::cancel_item_(Component *component, bool is_static_string, const void *name_ptr,
437 SchedulerItem::Type type) {
438 // Get the name as const char*
439 const char *name_cstr = this->get_name_cstr_(is_static_string, name_ptr);
440
441 // obtain lock because this function iterates and can be called from non-loop task context
442 LockGuard guard{this->lock_};
443 return this->cancel_item_locked_(component, name_cstr, type);
444}
445
446// Helper to cancel items by name - must be called with lock held
447bool HOT Scheduler::cancel_item_locked_(Component *component, const char *name_cstr, SchedulerItem::Type type) {
448 // Early return if name is invalid - no items to cancel
449 if (name_cstr == nullptr || name_cstr[0] == '\0') {
450 return false;
451 }
452
453 size_t total_cancelled = 0;
454
455 // Check all containers for matching items
456#if !defined(USE_ESP8266) && !defined(USE_RP2040)
457 // Only check defer queue for timeouts (intervals never go there)
459 for (auto &item : this->defer_queue_) {
460 if (this->matches_item_(item, component, name_cstr, type)) {
461 item->remove = true;
462 total_cancelled++;
463 }
464 }
465 }
466#endif
467
468 // Cancel items in the main heap
469 for (auto &item : this->items_) {
470 if (this->matches_item_(item, component, name_cstr, type)) {
471 item->remove = true;
472 total_cancelled++;
473 this->to_remove_++; // Track removals for heap items
474 }
475 }
476
477 // Cancel items in to_add_
478 for (auto &item : this->to_add_) {
479 if (this->matches_item_(item, component, name_cstr, type)) {
480 item->remove = true;
481 total_cancelled++;
482 // Don't track removals for to_add_ items
483 }
484 }
485
486 return total_cancelled > 0;
487}
488
490 // Get the current 32-bit millis value
491 const uint32_t now = millis();
492 // Check for rollover by comparing with last value
493 if (now < this->last_millis_) {
494 // Detected rollover (happens every ~49.7 days)
495 this->millis_major_++;
496 ESP_LOGD(TAG, "Incrementing scheduler major at %" PRIu64 "ms",
497 now + (static_cast<uint64_t>(this->millis_major_) << 32));
498 }
499 this->last_millis_ = now;
500 // Combine major (high 32 bits) and now (low 32 bits) into 64-bit time
501 return now + (static_cast<uint64_t>(this->millis_major_) << 32);
502}
503
504bool HOT Scheduler::SchedulerItem::cmp(const std::unique_ptr<SchedulerItem> &a,
505 const std::unique_ptr<SchedulerItem> &b) {
506 return a->next_execution_ > b->next_execution_;
507}
508
509} // namespace esphome
void set_current_component(Component *component)
Helper class that wraps a mutex with a RAII-style API.
Definition helpers.h:646
bool cancel_retry(Component *component, const std::string &name)
void set_timer_common_(Component *component, SchedulerItem::Type type, bool is_static_string, const void *name_ptr, uint32_t delay, std::function< void()> func)
Definition scheduler.cpp:62
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)
bool cancel_timeout(Component *component, const std::string &name)
bool cancel_interval(Component *component, const std::string &name)
void set_timeout(Component *component, const std::string &name, uint32_t timeout, std::function< void()> func)
void set_interval(Component *component, const std::string &name, uint32_t interval, std::function< void()> func)
optional< uint32_t > next_schedule_in()
uint8_t type
const char *const TAG
Definition spi.cpp:8
Providing packet encoding functions for exchanging data with a remote host.
Definition a01nyub.cpp:7
uint32_t random_uint32()
Return a random 32-bit unsigned integer.
Definition helpers.cpp:17
void IRAM_ATTR HOT delay(uint32_t ms)
Definition core.cpp:29
uint32_t IRAM_ATTR HOT millis()
Definition core.cpp:28
Application App
Global storage of Application pointer - only one Application can exist.
static bool cmp(const std::unique_ptr< SchedulerItem > &a, const std::unique_ptr< SchedulerItem > &b)