ESPHome 2026.11.0b6
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"
9#include <algorithm>
10#include <cinttypes>
11#include <cstring>
12#if defined(USE_RP2) && (defined(USE_WIFI) || defined(USE_ETHERNET))
13#include <hardware/sync.h>
14#endif
15
16namespace esphome {
17
18ESPHOME_LOG_TAG(TAG, "scheduler");
19
20#if defined(USE_RP2) && (defined(USE_WIFI) || defined(USE_ETHERNET))
21// lwIP callbacks add and cancel items from a low-priority IRQ on RP2, where lock_ is an empty Mutex: hold interrupts
22// off instead. Not the lwIP lock: each release re-arms arduino-pico's 20 ms Ethernet poll, starving reception.
23class SchedulerLockGuard {
24 public:
25 explicit SchedulerLockGuard(Mutex & /*mutex*/) : state_(save_and_disable_interrupts()) {}
26 ~SchedulerLockGuard() { restore_interrupts(this->state_); }
27
28 private:
29 uint32_t state_;
30};
31#else
32using SchedulerLockGuard = LockGuard;
33#endif
34
35// Maximum number of logically deleted (cancelled) items before forcing cleanup.
36// Empirically chosen to balance cleanup overhead against tombstone accumulation in items_.
37static constexpr uint32_t MAX_LOGICALLY_DELETED_ITEMS = 5;
38// max delay to start an interval sequence
39static constexpr uint32_t MAX_INTERVAL_DELAY = 5000;
40
41#if defined(ESPHOME_LOG_HAS_VERBOSE) || defined(ESPHOME_DEBUG_SCHEDULER)
42// Helper struct for formatting scheduler item names consistently in logs
43// Uses a stack buffer to avoid heap allocation
44// Uses ESPHOME_snprintf_P/ESPHOME_PSTR for ESP8266 to keep format strings in flash
45struct SchedulerNameLog {
46 // Sized for the widest formatted output: "self:0x" + 16 hex digits (64-bit pointer) + nul.
47 // Also covers "id:4294967295", "hash:0xFFFFFFFF", "iid:4294967295", "(null)".
48 char buffer[28];
49
50 // Format a scheduler item name for logging
51 // Returns pointer to formatted string (either static_name or internal buffer)
52 const char *format(Scheduler::NameType name_type, const char *static_name, uint32_t hash_or_id) {
53 using NameType = Scheduler::NameType;
54 if (name_type == NameType::STATIC_STRING) {
55 if (static_name)
56 return static_name;
57 // Copy "(null)" to buffer to keep it in flash on ESP8266
58 ESPHOME_strncpy_P(buffer, ESPHOME_PSTR("(null)"), sizeof(buffer));
59 return buffer;
60 } else if (name_type == NameType::HASHED_STRING) {
61 ESPHOME_snprintf_P(buffer, sizeof(buffer), ESPHOME_PSTR("hash:0x%08" PRIX32), hash_or_id);
62 return buffer;
63 } else if (name_type == NameType::NUMERIC_ID) {
64 ESPHOME_snprintf_P(buffer, sizeof(buffer), ESPHOME_PSTR("id:%" PRIu32), hash_or_id);
65 return buffer;
66 } else if (name_type == NameType::NUMERIC_ID_INTERNAL) {
67 ESPHOME_snprintf_P(buffer, sizeof(buffer), ESPHOME_PSTR("iid:%" PRIu32), hash_or_id);
68 return buffer;
69 } else { // SELF_POINTER
70 // static_name carries the void* key for SELF_POINTER (pointer-width union slot).
71 // %p is specified as void* (not const void*), so strip const for the varargs call.
72 ESPHOME_snprintf_P(buffer, sizeof(buffer), ESPHOME_PSTR("self:%p"),
73 const_cast<void *>(static_cast<const void *>(static_name)));
74 return buffer;
75 }
76 }
77};
78#endif
79
80// Uncomment to debug scheduler
81// #define ESPHOME_DEBUG_SCHEDULER
82
83#ifdef ESPHOME_DEBUG_SCHEDULER
84// Helper to validate that a pointer looks like it's in static memory
85static void validate_static_string(const char *name) {
86 if (name == nullptr)
87 return;
88
89 // This is a heuristic check - stack and heap pointers are typically
90 // much higher in memory than static data
91 uintptr_t addr = reinterpret_cast<uintptr_t>(name);
92
93 // Create a stack variable to compare against
94 int stack_var;
95 uintptr_t stack_addr = reinterpret_cast<uintptr_t>(&stack_var);
96
97 // If the string pointer is near our stack variable, it's likely on the stack
98 // Using 8KB range as ESP32 main task stack is typically 8192 bytes
99 if (addr > (stack_addr - 0x2000) && addr < (stack_addr + 0x2000)) {
100 ESP_LOGW(TAG,
101 "WARNING: Scheduler name '%s' at %p appears to be on the stack - this is unsafe!\n"
102 " Stack reference at %p",
103 name, name, &stack_var);
104 }
105
106 // Also check if it might be on the heap by seeing if it's in a very different range
107 // This is platform-specific but generally heap is allocated far from static memory
108 static const char *static_str = "test";
109 uintptr_t static_addr = reinterpret_cast<uintptr_t>(static_str);
110
111 // If the address is very far from known static memory, it might be heap
112 if (addr > static_addr + 0x100000 || (static_addr > 0x100000 && addr < static_addr - 0x100000)) {
113 ESP_LOGW(TAG, "WARNING: Scheduler name '%s' at %p might be on heap (static ref at %p)", name, name, static_str);
114 }
115}
116#endif /* ESPHOME_DEBUG_SCHEDULER */
117
118// A note on locking: the `lock_` lock protects the `items_` and `to_add_` containers. It must be taken when writing to
119// them (i.e. when adding/removing items, but not when changing items). As items are only deleted from the loop task,
120// iterating over them from the loop task is fine; but iterating from any other context requires the lock to be held to
121// avoid the main thread modifying the list while it is being accessed.
122
123// Calculate random offset for interval timers
124// Extracted from set_timer_common_ to reduce code size - only needed for intervals, not timeouts
125uint32_t Scheduler::calculate_interval_offset_(uint32_t delay) {
126 uint32_t max_offset = std::min(delay / 2, MAX_INTERVAL_DELAY);
127 // Multiply-and-shift: uniform random in [0, max_offset) without floating point
128 return static_cast<uint32_t>((static_cast<uint64_t>(random_uint32()) * max_offset) >> 32);
129}
130
131// Common implementation for both timeout and interval
132// name_type determines storage type: STATIC_STRING uses static_name, others use hash_or_id
133void HOT Scheduler::set_timer_common_(Component *component, SchedulerItem::Type type, NameType name_type,
134 const char *static_name, uint32_t hash_or_id, uint32_t delay,
135 std::function<void()> &&func, bool skip_cancel, const LogString *source) {
136 if (delay == SCHEDULER_DONT_RUN) {
137 // Still need to cancel existing timer if we have a name/id
138 if (!skip_cancel) {
139 SchedulerLockGuard guard{this->lock_};
140 this->cancel_item_locked_(component, name_type, static_name, hash_or_id, type, /* find_first= */ true);
141 }
142 return;
143 }
144
145 // An interval of 0 means "fire every tick forever," which is misuse: the
146 // item would always be due, causing Scheduler::call() to spin and starve
147 // the main loop (WDT reset in the field). Coerce to 1ms so existing code
148 // using update_interval=0ms as a pseudo-loop() continues to work at ~1kHz,
149 // and warn so authors can migrate to HighFrequencyLoopRequester which is
150 // the intended mechanism for running fast in the main loop. Zero-delay
151 // timeouts (defer) remain legitimate one-shots and are not affected.
152 if (type == SchedulerItem::INTERVAL && delay == 0) [[unlikely]] {
153 ESP_LOGE(TAG, "[%s] set_interval(0) would spin main loop - coercing to 1ms (use HighFrequencyLoopRequester)",
154 component ? LOG_STR_ARG(component->get_component_log_str()) : LOG_STR_LITERAL("?"));
155 delay = 1;
156 }
157
158 uint32_t offset = 0;
159 // Take lock early to protect scheduler_item_pool_head_ access
160 {
161 SchedulerLockGuard guard{this->lock_};
162
163 // Create and populate the scheduler item
164 SchedulerItem *item = this->get_item_from_pool_locked_();
165 // SELF_POINTER items store the source name (owning script) in the union slot instead of a component.
166 if (name_type == NameType::SELF_POINTER) {
167 item->source_name = source;
168 } else {
169 item->component = component;
170 }
171 item->set_name(name_type, static_name, hash_or_id);
172 item->type = type;
173 // Use destroy + placement-new instead of move-assignment.
174 // GCC's std::function::operator=(function&&) does a full swap dance even when the
175 // target is empty. Since recycled/new items always have an empty callback, we can
176 // destroy the empty one (no-op) and move-construct directly, saving ~40 bytes of
177 // swap/destructor code on Xtensa.
178 item->callback.~function();
179 new (&item->callback) std::function<void()>(std::move(func));
180 // Reset remove flag - recycled items may have been cancelled (remove=true) in previous use
181 this->set_item_removed_(item, false);
182
183 // Determine target container: defer_queue_ for deferred items, to_add_ for everything else.
184 // Using a pointer lets both paths share the cancel + push_back epilogue.
185 auto *target = &this->to_add_;
186
187#ifndef ESPHOME_THREAD_SINGLE
188 // Special handling for defer() (delay = 0, type = TIMEOUT)
189 // Single-core platforms don't need thread-safe defer handling
190 if (delay == 0 && type == SchedulerItem::TIMEOUT) {
191 // Put in defer queue for guaranteed FIFO execution
192 target = &this->defer_queue_;
193 } else
194#endif /* not ESPHOME_THREAD_SINGLE */
195 {
196 // Only non-defer items need a timestamp for scheduling
197 const uint64_t now_64 = millis_64();
198
199 // Type-specific setup
200 if (type == SchedulerItem::INTERVAL) {
201 item->interval = delay;
202 // first execution happens immediately after a random smallish offset
203 offset = this->calculate_interval_offset_(delay);
204 item->set_next_execution(now_64 + offset);
205 } else {
206 item->interval = 0;
207 item->set_next_execution(now_64 + delay);
208 }
209
210#ifdef ESPHOME_DEBUG_SCHEDULER
211 this->debug_log_timer_(item, name_type, static_name, hash_or_id, delay, now_64);
212#endif /* ESPHOME_DEBUG_SCHEDULER */
213 }
214
215 // Common epilogue: atomic cancel-and-add (unless skip_cancel is true or anonymous)
216 // Anonymous items (STATIC_STRING with nullptr) can never match anything, so skip the scan.
217 if (!skip_cancel && (name_type != NameType::STATIC_STRING || static_name != nullptr)) {
218 this->cancel_item_locked_(component, name_type, static_name, hash_or_id, type, /* find_first= */ true);
219 }
220 target->push_back(item);
221 if (target == &this->to_add_) {
222 this->to_add_count_increment_locked_();
223 }
224#ifndef ESPHOME_THREAD_SINGLE
225 else {
226 this->defer_count_increment_locked_();
227 }
228#endif
229 }
230#ifdef ESPHOME_LOG_HAS_VERBOSE
231 // Logged after releasing the lock: a logger on_message automation can call back into the scheduler.
232 if (type == SchedulerItem::INTERVAL) {
233 SchedulerNameLog name_log;
234 ESP_LOGV(TAG, "Scheduler interval for %s is %" PRIu32 "ms, offset %" PRIu32 "ms",
235 name_log.format(name_type, static_name, hash_or_id), delay, offset);
236 }
237#endif
238 // A background insertion may shorten a sleep whose deadline was already computed.
239 if (!is_main_loop_thread()) [[unlikely]]
241}
242
243void HOT Scheduler::set_timeout(Component *component, const char *name, uint32_t timeout,
244 std::function<void()> &&func) {
245 this->set_timer_common_(component, SchedulerItem::TIMEOUT, NameType::STATIC_STRING, name, 0, timeout,
246 std::move(func));
247}
248
249void HOT Scheduler::set_timeout(Component *component, uint32_t id, uint32_t timeout, std::function<void()> &&func) {
250 this->set_timer_common_(component, SchedulerItem::TIMEOUT, NameType::NUMERIC_ID, nullptr, id, timeout,
251 std::move(func));
252}
253bool HOT Scheduler::cancel_timeout(Component *component, const char *name) {
254 return this->cancel_item_(component, NameType::STATIC_STRING, name, 0, SchedulerItem::TIMEOUT);
255}
256bool HOT Scheduler::cancel_timeout(Component *component, uint32_t id) {
257 return this->cancel_item_(component, NameType::NUMERIC_ID, nullptr, id, SchedulerItem::TIMEOUT);
258}
259void HOT Scheduler::set_interval(Component *component, const char *name, uint32_t interval,
260 std::function<void()> &&func) {
261 this->set_timer_common_(component, SchedulerItem::INTERVAL, NameType::STATIC_STRING, name, 0, interval,
262 std::move(func));
263}
264void HOT Scheduler::set_interval(Component *component, uint32_t id, uint32_t interval, std::function<void()> &&func) {
265 this->set_timer_common_(component, SchedulerItem::INTERVAL, NameType::NUMERIC_ID, nullptr, id, interval,
266 std::move(func));
267}
268bool HOT Scheduler::cancel_interval(Component *component, const char *name) {
269 return this->cancel_item_(component, NameType::STATIC_STRING, name, 0, SchedulerItem::INTERVAL);
270}
271bool HOT Scheduler::cancel_interval(Component *component, uint32_t id) {
272 return this->cancel_item_(component, NameType::NUMERIC_ID, nullptr, id, SchedulerItem::INTERVAL);
273}
274
275// Self-keyed scheduler API. The cancellation key is `self` (typically the caller's `this`),
276// passed through the existing static_name pointer slot. Matching is by raw pointer equality
277// (see matches_item_locked_'s SELF_POINTER branch). No Component pointer is stored, so
278// is_failed() skip and component-based log attribution don't apply.
279void HOT Scheduler::set_timeout(const void *self, uint32_t timeout, std::function<void()> &&func) {
280 this->set_timer_common_(nullptr, SchedulerItem::TIMEOUT, NameType::SELF_POINTER, static_cast<const char *>(self), 0,
281 timeout, std::move(func));
282}
283void HOT Scheduler::set_interval(const void *self, uint32_t interval, std::function<void()> &&func) {
284 this->set_timer_common_(nullptr, SchedulerItem::INTERVAL, NameType::SELF_POINTER, static_cast<const char *>(self), 0,
285 interval, std::move(func));
286}
287bool HOT Scheduler::cancel_timeout(const void *self) {
288 return this->cancel_item_(nullptr, NameType::SELF_POINTER, static_cast<const char *>(self), 0,
289 SchedulerItem::TIMEOUT);
290}
291bool HOT Scheduler::cancel_interval(const void *self) {
292 return this->cancel_item_(nullptr, NameType::SELF_POINTER, static_cast<const char *>(self), 0,
293 SchedulerItem::INTERVAL);
294}
295
296optional<uint32_t> HOT Scheduler::next_schedule_in(uint32_t now) {
297 // IMPORTANT: This method should only be called from the main thread (loop task).
298 // Accesses items_[0] and the fast-path empty checks without holding a lock, which
299 // is only safe from the main thread. Other threads must not call this method.
300 //
301 // Note: cleanup_() is only invoked on the items_[0] path below. The early returns
302 // skip it because they don't read items_[0], and Scheduler::call() at the top of
303 // every loop iteration already performs its own cleanup before the next sleep-
304 // duration computation happens.
305
306#ifndef ESPHOME_THREAD_SINGLE
307 // defer() items live in a separate queue that is drained at the top of every
308 // loop tick via process_defer_queue_(). If any are pending, the next loop
309 // iteration has work to do right now -- don't let the caller sleep.
310 if (!this->defer_empty_())
311 return 0;
312#else
313 // On single-threaded builds, defer() routes through set_timeout(..., 0) which
314 // stages in to_add_. process_to_add() runs at the top of every scheduler.call(),
315 // so anything in to_add_ becomes runnable on the next iteration; don't sleep.
316 if (!this->to_add_empty_())
317 return 0;
318#endif
319
320 // If no items, return empty optional
321 if (!this->cleanup_())
322 return {};
323
324 SchedulerItem *item = this->items_[0];
325 const auto now_64 = this->millis_64_from_(now);
326 const uint64_t next_exec = item->get_next_execution();
327 if (next_exec < now_64)
328 return 0;
329 return next_exec - now_64;
330}
331
332void Scheduler::full_cleanup_removed_items_() {
333 // We hold the lock for the entire cleanup operation because:
334 // 1. We're rebuilding the entire items_ list, so we need exclusive access throughout
335 // 2. Other threads must see either the old state or the new state, not intermediate states
336 // 3. The operation is already expensive (O(n)), so lock overhead is negligible
337 // 4. No operations inside can block or take other locks, so no deadlock risk
338 SchedulerLockGuard guard{this->lock_};
339
340 // Compact in-place: move valid items forward, recycle removed ones
341 size_t write = 0;
342 for (size_t read = 0; read < this->items_.size(); ++read) {
343 if (!is_item_removed_locked_(this->items_[read])) {
344 if (write != read) {
345 this->items_[write] = this->items_[read];
346 }
347 ++write;
348 } else {
349 this->recycle_item_main_loop_(this->items_[read]);
350 }
351 }
352 this->items_.erase(this->items_.begin() + write, this->items_.end());
353 // Rebuild the heap structure since items are no longer in heap order
354 std::make_heap(this->items_.begin(), this->items_.end(), SchedulerItem::cmp);
355 this->to_remove_clear_locked_();
356}
357
358#ifndef ESPHOME_THREAD_SINGLE
359void Scheduler::compact_defer_queue_locked_() {
360 // Rare case: new items were added during processing - compact the vector
361 // This only happens when:
362 // 1. A deferred callback calls defer() again, or
363 // 2. Another thread calls defer() while we're processing
364 //
365 // Move unprocessed items (added during this loop) to the front for next iteration
366 //
367 // SAFETY: Compacted items may include cancelled items (marked for removal via
368 // cancel_item_locked_() during execution). This is safe because should_skip_item_()
369 // checks is_item_removed_() before executing, so cancelled items will be skipped
370 // and recycled on the next loop iteration.
371 size_t remaining = this->defer_queue_.size() - this->defer_queue_front_;
372 for (size_t i = 0; i < remaining; i++) {
373 this->defer_queue_[i] = this->defer_queue_[this->defer_queue_front_ + i];
374 }
375 // Use erase() instead of resize() to avoid instantiating _M_default_append
376 // (saves ~156 bytes flash). Erasing from the end is O(1) - no shifting needed.
377 this->defer_queue_.erase(this->defer_queue_.begin() + remaining, this->defer_queue_.end());
378}
379void HOT Scheduler::process_defer_queue_slow_path_(uint32_t &now) {
380 // Process defer queue to guarantee FIFO execution order for deferred items.
381 // Previously, defer() used the heap which gave undefined order for equal timestamps,
382 // causing race conditions on multi-core systems (ESP32, BK7200).
383 // With the defer queue:
384 // - Deferred items (delay=0) go directly to defer_queue_ in set_timer_common_
385 // - Items execute in exact order they were deferred (FIFO guarantee)
386 // - No deferred items exist in to_add_, so processing order doesn't affect correctness
387 // Single-core platforms don't use this queue and fall back to the heap-based approach.
388 //
389 // Note: Items cancelled via cancel_item_locked_() are marked with remove=true but still
390 // processed here. They are skipped during execution by should_skip_item_().
391 // This is intentional - no memory leak occurs.
392 //
393 // We use an index (defer_queue_front_) to track the read position instead of calling
394 // erase() on every pop, which would be O(n). The queue is processed once per loop -
395 // any items added during processing are left for the next loop iteration.
396
397 // Merge lock acquisitions: instead of separate locks for move-out and recycle (2N+1 total),
398 // recycle each item after re-acquiring the lock for the next iteration (N+1 total).
399 // The lock is held across: recycle → loop condition → move-out, then released for execution.
400 SchedulerItem *item;
401
402 this->lock_.lock();
403 // Reset counter and snapshot queue end under lock
404 this->defer_count_clear_locked_();
405 size_t defer_queue_end = this->defer_queue_.size();
406 if (this->defer_queue_front_ >= defer_queue_end) {
407 this->lock_.unlock();
408 return;
409 }
410 while (this->defer_queue_front_ < defer_queue_end) {
411 // Take ownership of the item, leaving nullptr in the vector slot.
412 // This is safe because:
413 // 1. The vector is only cleaned up by cleanup_defer_queue_locked_() at the end of this function
414 // 2. Any code iterating defer_queue_ MUST check for nullptr items (see mark_matching_items_removed_locked_)
415 // 3. The lock protects concurrent access, but the nullptr remains until cleanup
416 item = this->defer_queue_[this->defer_queue_front_];
417 this->defer_queue_[this->defer_queue_front_] = nullptr;
418 this->defer_queue_front_++;
419 this->lock_.unlock();
420
421 // Execute callback without holding lock to prevent deadlocks
422 // if the callback tries to call defer() again
423 if (!this->should_skip_item_(item)) {
424 now = this->execute_item_(item, now);
425 }
426
427 this->lock_.lock();
428 this->recycle_item_main_loop_(item);
429 }
430 // Clean up the queue (lock already held from last recycle or initial acquisition)
431 this->cleanup_defer_queue_locked_();
432 this->lock_.unlock();
433}
434#endif /* not ESPHOME_THREAD_SINGLE */
435
436uint32_t HOT Scheduler::call(uint32_t now) {
437#ifndef ESPHOME_THREAD_SINGLE
438 this->process_defer_queue_(now);
439#endif /* not ESPHOME_THREAD_SINGLE */
440
441 // Extend the caller's 32-bit timestamp to 64-bit for scheduler operations
442 const auto now_64 = this->millis_64_from_(now);
443 this->process_to_add();
444
445 // Track if any items were added to to_add_ during callbacks
446 bool has_added_items = false;
447
448#ifdef ESPHOME_DEBUG_SCHEDULER
449 static uint64_t last_print = 0;
450
451 if (now_64 - last_print > 2000) {
452 last_print = now_64;
453 std::vector<SchedulerItem *> old_items;
454 ESP_LOGD(TAG, "Items: count=%zu, pool=%zu, now=%" PRIu64, this->items_.size(), this->scheduler_item_pool_size_,
455 now_64);
456 // Cleanup before debug output
457 this->cleanup_();
458 while (!this->items_.empty()) {
459 SchedulerItem *item;
460 {
461 SchedulerLockGuard guard{this->lock_};
462 item = this->pop_raw_locked_();
463 }
464
465 SchedulerNameLog name_log;
466 bool is_cancelled = is_item_removed_(item);
467 ESP_LOGD(TAG, " %s '%s/%s' interval=%" PRIu32 " next_execution in %" PRId64 "ms at %" PRIu64 "%s",
468 LOG_STR_ARG(item->get_type_str()), LOG_STR_ARG(item->get_source()),
469 name_log.format(item->get_name_type(), item->get_name(), item->get_name_hash_or_id()), item->interval,
470 (int64_t) (item->get_next_execution() - now_64), item->get_next_execution(),
471 is_cancelled ? LOG_STR_LITERAL(" [CANCELLED]") : LOG_STR_LITERAL(""));
472
473 old_items.push_back(item);
474 }
475 ESP_LOGD(TAG, "\n");
476
477 {
478 SchedulerLockGuard guard{this->lock_};
479 this->items_ = std::move(old_items);
480 // Rebuild heap after moving items back
481 std::make_heap(this->items_.begin(), this->items_.end(), SchedulerItem::cmp);
482 }
483 }
484#endif /* ESPHOME_DEBUG_SCHEDULER */
485
486 // Cleanup removed items before processing
487 // First try to clean items from the top of the heap (fast path)
488 this->cleanup_();
489
490 // If we still have too many cancelled items, do a full cleanup
491 // This only happens if cancelled items are stuck in the middle/bottom of the heap
492 if (this->to_remove_count_() >= MAX_LOGICALLY_DELETED_ITEMS) {
493 this->full_cleanup_removed_items_();
494 }
495 // IMPORTANT: This loop uses index-based access (items_[0]), NOT iterators.
496 // This is intentional — fired intervals are pushed back into items_ via
497 // push_back() + push_heap() below, which may reallocate the vector's storage.
498 // Index-based access is safe across reallocations because we re-read items_[0]
499 // at the top of each iteration. Do NOT convert this to a range-based for loop
500 // or iterator-based loop, as that would break when items are added.
501 while (!this->items_.empty()) {
502 // Don't copy-by value yet
503 SchedulerItem *item = this->items_[0];
504 if (item->get_next_execution() > now_64) {
505 // Not reached timeout yet, done for this call
506 break;
507 }
508 // Check if item is marked for removal
509 // This handles two cases:
510 // 1. Item was marked for removal after cleanup_() but before we got here
511 // 2. Item is marked for removal but wasn't at the front of the heap during cleanup_()
512#ifdef ESPHOME_THREAD_MULTI_NO_ATOMICS
513 // Multi-threaded platforms without atomics: must take lock to safely read remove flag
514 {
515 SchedulerLockGuard guard{this->lock_};
516 if (is_item_removed_locked_(item)) {
517 this->recycle_item_main_loop_(this->pop_raw_locked_());
518 this->to_remove_decrement_locked_();
519 continue;
520 }
521 }
522#else
523 // Single-threaded or multi-threaded with atomics: can check without lock
524 if (is_item_removed_(item)) {
525 SchedulerLockGuard guard{this->lock_};
526 this->recycle_item_main_loop_(this->pop_raw_locked_());
527 this->to_remove_decrement_locked_();
528 continue;
529 }
530#endif
531
532 // Don't run on failed components (is_item_failed_ exempts SELF_POINTER delays).
533 if (this->is_item_failed_(item)) {
534 SchedulerLockGuard guard{this->lock_};
535 this->recycle_item_main_loop_(this->pop_raw_locked_());
536 continue;
537 }
538
539#ifdef ESPHOME_DEBUG_SCHEDULER
540 {
541 SchedulerNameLog name_log;
542 ESP_LOGV(TAG, "Running %s '%s/%s' with interval=%" PRIu32 " next_execution=%" PRIu64 " (now=%" PRIu64 ")",
543 LOG_STR_ARG(item->get_type_str()), LOG_STR_ARG(item->get_source()),
544 name_log.format(item->get_name_type(), item->get_name(), item->get_name_hash_or_id()), item->interval,
545 item->get_next_execution(), now_64);
546 }
547#endif /* ESPHOME_DEBUG_SCHEDULER */
548
549 // Warning: During callback(), a lot of stuff can happen, including:
550 // - timeouts/intervals get added, potentially invalidating vector pointers
551 // - timeouts/intervals get cancelled
552 now = this->execute_item_(item, now);
553
554 SchedulerLockGuard guard{this->lock_};
555
556 // Only pop after function call, this ensures we were reachable
557 // during the function call and know if we were cancelled.
558 SchedulerItem *executed_item = this->pop_raw_locked_();
559
560 if (this->is_item_removed_locked_(executed_item)) {
561 // We were removed/cancelled in the function call, recycle and continue
562 this->to_remove_decrement_locked_();
563 this->recycle_item_main_loop_(executed_item);
564 has_added_items |= !this->to_add_.empty();
565 continue;
566 }
567
568 if (executed_item->type == SchedulerItem::INTERVAL) {
569 executed_item->set_next_execution(now_64 + executed_item->interval);
570 // Push directly back into the heap instead of routing through to_add_.
571 // This is safe because:
572 // 1. We're on the main loop and already hold the lock
573 // 2. The item was already popped from items_ via pop_raw_locked_() above
574 // 3. The while loop uses index-based access (items_[0]), not iterators,
575 // so push_back() reallocation cannot invalidate our iteration
576 // 4. push_heap() restores the heap invariant before the next iteration
577 // peeks at items_[0]
578 // This avoids the to_add_ detour and the overhead of
579 // process_to_add_slow_path_() (lock acquisition, vector iteration, clear).
580 this->items_.push_back(executed_item);
581 std::push_heap(this->items_.begin(), this->items_.end(), SchedulerItem::cmp);
582 } else {
583 // Timeout completed - recycle it
584 this->recycle_item_main_loop_(executed_item);
585 }
586
587 has_added_items |= !this->to_add_.empty();
588 }
589
590 if (has_added_items) {
591 this->process_to_add();
592 }
593
594#ifdef ESPHOME_DEBUG_SCHEDULER
595 // Verify no items were leaked during this call() cycle.
596 // All items must be in items_, to_add_, defer_queue_, or the pool.
597 // Safe to check here because:
598 // - process_defer_queue_ has already run its cleanup_defer_queue_locked_(),
599 // so defer_queue_ contains no nullptr slots inflating the count.
600 // - The while loop above has finished, so no items are held in local variables;
601 // every item has been returned to a container (items_, to_add_, or pool).
602 // Lock needed to get a consistent snapshot of all containers.
603 {
604 SchedulerLockGuard guard{this->lock_};
605 this->debug_verify_no_leak_();
606 }
607#endif
608 // execute_item_() advances `now` as items fire; return it so the caller
609 // stays monotonic with last_wdt_feed_.
610 return now;
611}
612void HOT Scheduler::process_to_add_slow_path_() {
613 SchedulerLockGuard guard{this->lock_};
614 for (auto *&it : this->to_add_) {
615 if (is_item_removed_locked_(it)) {
616 // Recycle cancelled items
617 this->recycle_item_main_loop_(it);
618 it = nullptr;
619 continue;
620 }
621
622 this->items_.push_back(it);
623 std::push_heap(this->items_.begin(), this->items_.end(), SchedulerItem::cmp);
624 }
625 this->to_add_.clear();
626 this->to_add_count_clear_locked_();
627}
628bool HOT Scheduler::cleanup_slow_path_() {
629 // We must hold the lock for the entire cleanup operation because:
630 // 1. We're modifying items_ (via pop_raw_locked_) which requires exclusive access
631 // 2. We're decrementing to_remove_ which is also modified by other threads
632 // (though all modifications are already under lock)
633 // 3. Other threads read items_ when searching for items to cancel in cancel_item_locked_()
634 // 4. We need a consistent view of items_ and to_remove_ throughout the operation
635 // Without the lock, we could access items_ while another thread is reading it,
636 // leading to race conditions
637 SchedulerLockGuard guard{this->lock_};
638 while (!this->items_.empty()) {
639 SchedulerItem *item = this->items_[0];
640 if (!this->is_item_removed_locked_(item))
641 break;
642 this->to_remove_decrement_locked_();
643 this->recycle_item_main_loop_(this->pop_raw_locked_());
644 }
645 return !this->items_.empty();
646}
647Scheduler::SchedulerItem *HOT Scheduler::pop_raw_locked_() {
648 std::pop_heap(this->items_.begin(), this->items_.end(), SchedulerItem::cmp);
649
650 SchedulerItem *item = this->items_.back();
651 this->items_.pop_back();
652 return item;
653}
654
655// Helper to execute a scheduler item
656uint32_t HOT Scheduler::execute_item_(SchedulerItem *item, uint32_t now) {
657 // Resolve the component and (for SELF_POINTER/deferred items) the source name from the shared
658 // union slot with a single name-type check. Self-keyed items have no owning component; their slot
659 // holds the source name (e.g. the owning script), published so deferred work chained inside the
660 // callback re-captures it and the blocking warning can name the script instead of "<null>".
661 Component *component;
662 const LogString *source;
663 if (item->get_name_type() == NameType::SELF_POINTER) {
664 component = nullptr;
665 source = item->source_name;
666 } else {
667 component = item->component;
668 source = nullptr;
669 }
670 // Guard publishes the item's identity + dispatch time, then times the callback.
671 LoopBlockingGuard guard{component, source, now};
672 item->callback();
673 uint32_t end = guard.finish();
674 // Feed the watchdog after each scheduled item (both main heap and defer
675 // queue paths go through here). A run of back-to-back callbacks cannot
676 // starve the wdt. The inline fast path is a load + sub + branch — nearly
677 // free when the 3 ms rate limit hasn't elapsed.
679 return end;
680}
681
682// Common implementation for cancel operations - handles locking
683bool HOT Scheduler::cancel_item_(Component *component, NameType name_type, const char *static_name, uint32_t hash_or_id,
684 SchedulerItem::Type type) {
685 SchedulerLockGuard guard{this->lock_};
686 // Public cancel path uses default find_first=false to cancel ALL matches because
687 // DelayAction parallel mode (skip_cancel=true) can create multiple items with the same key.
688 return this->cancel_item_locked_(component, name_type, static_name, hash_or_id, type);
689}
690
691// Helper to cancel matching items - must be called with lock held.
692// When find_first=true, stops after the first match and exits across containers
693// (used by set_timer_common_ where cancel-before-add guarantees at most one match).
694// When find_first=false, cancels ALL matches across all containers (needed for
695// public cancel path where DelayAction parallel mode can create duplicates).
696// name_type determines matching: STATIC_STRING uses static_name, others use hash_or_id
697size_t Scheduler::mark_matching_items_removed_slow_locked_(std::vector<SchedulerItem *> &container,
698 Component *component, NameType name_type,
699 const char *static_name, uint32_t hash_or_id,
700 SchedulerItem::Type type, bool find_first) {
701 size_t count = 0;
702 for (auto *item : container) {
703 if (this->matches_item_locked_(item, component, name_type, static_name, hash_or_id, type)) {
704 this->set_item_removed_(item, true);
705 if (find_first)
706 return 1;
707 count++;
708 }
709 }
710 return count;
711}
712
713bool HOT Scheduler::cancel_item_locked_(Component *component, NameType name_type, const char *static_name,
714 uint32_t hash_or_id, SchedulerItem::Type type, bool find_first) {
715 // Early return if static string name is invalid
716 if (name_type == NameType::STATIC_STRING && static_name == nullptr) {
717 return false;
718 }
719
720 size_t total_cancelled = 0;
721
722#ifndef ESPHOME_THREAD_SINGLE
723 // Mark items in defer queue as cancelled (they'll be skipped when processed)
724 if (type == SchedulerItem::TIMEOUT) {
725 total_cancelled += this->mark_matching_items_removed_locked_(this->defer_queue_, component, name_type, static_name,
726 hash_or_id, type, find_first);
727 if (find_first && total_cancelled > 0)
728 return true;
729 }
730#endif /* not ESPHOME_THREAD_SINGLE */
731
732 // Cancel items in the main heap
733 // We only mark items for removal here - never recycle directly.
734 // The main loop may be executing an item's callback right now, and recycling
735 // would destroy the callback while it's running (use-after-free).
736 // Only the main loop in call() should recycle items after execution completes.
737 {
738 size_t heap_cancelled = this->mark_matching_items_removed_locked_(this->items_, component, name_type, static_name,
739 hash_or_id, type, find_first);
740 total_cancelled += heap_cancelled;
741 this->to_remove_add_locked_(heap_cancelled);
742 if (find_first && total_cancelled > 0)
743 return true;
744 }
745
746 // Cancel items in to_add_
747 total_cancelled += this->mark_matching_items_removed_locked_(this->to_add_, component, name_type, static_name,
748 hash_or_id, type, find_first);
749
750 return total_cancelled > 0;
751}
752
753bool HOT Scheduler::SchedulerItem::cmp(SchedulerItem *a, SchedulerItem *b) {
754 // High bits are almost always equal (change only on 32-bit rollover ~49 days)
755 // Optimize for common case: check low bits first when high bits are equal
756 return (a->next_execution_high_ == b->next_execution_high_) ? (a->next_execution_low_ > b->next_execution_low_)
757 : (a->next_execution_high_ > b->next_execution_high_);
758}
759
760// Recycle a SchedulerItem back to the freelist for reuse.
761// IMPORTANT: Caller must hold the scheduler lock.
762void Scheduler::recycle_item_main_loop_(SchedulerItem *item) {
763 if (item == nullptr)
764 return;
765
766 item->callback = nullptr; // release captured resources
767 item->next_free = this->scheduler_item_pool_head_;
768 this->scheduler_item_pool_head_ = item;
769 this->scheduler_item_pool_size_++;
770#ifdef ESPHOME_DEBUG_SCHEDULER
771 ESP_LOGD(TAG, "Recycled item to pool (pool size now: %zu)", this->scheduler_item_pool_size_);
772#endif
773}
774
775// Shrink a SchedulerItem* vector's capacity to its current size.
776// std::vector::shrink_to_fit() is non-binding and our toolchain ignores it; the classic
777// swap-with-copy idiom (std::vector<T>(other).swap(other)) instantiates the iterator-range
778// constructor which pulls in std::__throw_bad_array_new_length and ~120 B of related
779// stdlib RTTI/typeinfo. Build into a temp via reserve + push_back instead, then move-assign:
780// reserve uses operator new (throws bad_alloc, already linked) and push_back without growth
781// is the noexcept tail path. Move-assign just swaps pointers.
782// Out-of-line + noinline so the callers in trim_freelist() share one body.
783void __attribute__((noinline)) Scheduler::shrink_scheduler_vector_(std::vector<SchedulerItem *> *v) {
784 if (v->capacity() == v->size())
785 return; // already exact, common after a quiet period
786 std::vector<SchedulerItem *> tmp;
787 tmp.reserve(v->size());
788 for (SchedulerItem *p : *v)
789 tmp.push_back(p);
790 *v = std::move(tmp);
791}
792
793void Scheduler::trim_freelist() {
794 SchedulerLockGuard guard{this->lock_};
795 SchedulerItem *item = this->scheduler_item_pool_head_;
796 size_t freed = 0;
797 while (item != nullptr) {
798 SchedulerItem *next = item->next_free;
799 delete item;
800#ifdef ESPHOME_DEBUG_SCHEDULER
801 this->debug_live_items_--;
802#endif
803 item = next;
804 freed++;
805 }
806 this->scheduler_item_pool_head_ = nullptr;
807 this->scheduler_item_pool_size_ = 0;
808
809 // items_/to_add_/defer_queue_ retain their boot-peak vector capacity (vector grows
810 // by doubling and otherwise keeps the peak). Reclaim that slack as well.
811 shrink_scheduler_vector_(&this->items_);
812 shrink_scheduler_vector_(&this->to_add_);
813#ifndef ESPHOME_THREAD_SINGLE
814 shrink_scheduler_vector_(&this->defer_queue_);
815#endif
816
817#ifdef ESPHOME_DEBUG_SCHEDULER
818 ESP_LOGD(TAG, "Freelist trimmed (%zu items freed)", freed);
819#else
820 (void) freed;
821#endif
822}
823
824#ifdef ESPHOME_DEBUG_SCHEDULER
825void Scheduler::debug_log_timer_(const SchedulerItem *item, NameType name_type, const char *static_name,
826 uint32_t hash_or_id, uint32_t delay, uint64_t now) {
827 // Validate static strings in debug mode
828 if (name_type == NameType::STATIC_STRING && static_name != nullptr) {
829 validate_static_string(static_name);
830 }
831
832 // Debug logging
833 SchedulerNameLog name_log;
834 const char *type_str = LOG_STR_ARG(item->get_type_str());
835 if (item->type == SchedulerItem::TIMEOUT) {
836 ESP_LOGD(TAG, "set_%s(name='%s/%s', %s=%" PRIu32 ")", type_str, LOG_STR_ARG(item->get_source()),
837 name_log.format(name_type, static_name, hash_or_id), type_str, delay);
838 } else {
839 ESP_LOGD(TAG, "set_%s(name='%s/%s', %s=%" PRIu32 ", offset=%" PRIu32 ")", type_str, LOG_STR_ARG(item->get_source()),
840 name_log.format(name_type, static_name, hash_or_id), type_str, delay,
841 static_cast<uint32_t>(item->get_next_execution() - now));
842 }
843}
844#endif /* ESPHOME_DEBUG_SCHEDULER */
845
846// Pop from freelist or allocate. IMPORTANT: caller must hold the lock and must overwrite
847// `item->component` before releasing it -- the popped slot still holds the freelist link.
848Scheduler::SchedulerItem *Scheduler::get_item_from_pool_locked_() {
849 if (this->scheduler_item_pool_head_ != nullptr) {
850 SchedulerItem *item = this->scheduler_item_pool_head_;
851 this->scheduler_item_pool_head_ = item->next_free;
852 this->scheduler_item_pool_size_--;
853#ifdef ESPHOME_DEBUG_SCHEDULER
854 ESP_LOGD(TAG, "Reused item from pool (pool size now: %zu)", this->scheduler_item_pool_size_);
855#endif
856 return item;
857 }
858#ifdef ESPHOME_DEBUG_SCHEDULER
859 ESP_LOGD(TAG, "Allocated new item (pool empty)");
860#endif
861 auto *item = new SchedulerItem();
862#ifdef ESPHOME_DEBUG_SCHEDULER
863 this->debug_live_items_++;
864#endif
865 return item;
866}
867
868#ifdef ESPHOME_DEBUG_SCHEDULER
869bool Scheduler::debug_verify_no_leak_() const {
870 // Invariant: every live SchedulerItem must be in exactly one container.
871 // debug_live_items_ tracks allocations minus deletions.
872 size_t accounted = this->items_.size() + this->to_add_.size() + this->scheduler_item_pool_size_;
873#ifndef ESPHOME_THREAD_SINGLE
874 accounted += this->defer_queue_.size();
875#endif
876 if (accounted != this->debug_live_items_) {
877 ESP_LOGE(TAG,
878 "SCHEDULER LEAK DETECTED: live=%" PRIu32 " but accounted=%" PRIu32 " (items=%" PRIu32 " to_add=%" PRIu32
879 " pool=%" PRIu32
880#ifndef ESPHOME_THREAD_SINGLE
881 " defer=%" PRIu32
882#endif
883 ")",
884 static_cast<uint32_t>(this->debug_live_items_), static_cast<uint32_t>(accounted),
885 static_cast<uint32_t>(this->items_.size()), static_cast<uint32_t>(this->to_add_.size()),
886 static_cast<uint32_t>(this->scheduler_item_pool_size_)
887#ifndef ESPHOME_THREAD_SINGLE
888 ,
889 static_cast<uint32_t>(this->defer_queue_.size())
890#endif
891 );
892 assert(false);
893 return false;
894 }
895 return true;
896}
897#endif
898
899} // namespace esphome
void ESPHOME_ALWAYS_INLINE feed_wdt_with_time(uint32_t time)
Feed the task watchdog, hot entry.
const LogString * get_component_log_str() const ESPHOME_ALWAYS_INLINE
Get the integration where this component was declared as a LogString for logging.
Definition component.h:345
Helper class that wraps a mutex with a RAII-style API.
Definition helpers.h:2222
Mutex implementation, with API based on the unavailable std::mutex.
Definition helpers.h:2183
struct @66::@67 __attribute__
Wake the main loop task from an ISR. ISR-safe.
Definition main_task.h:45
const Component * component
Definition component.cpp:34
uint8_t type
NameCopy * next
unsigned count
Definition gif.cpp:51
uint32_t buffer
Definition gif.cpp:50
const char * format
ESPHOME_LOG_TAG(TAG, CRASH_LOG_TAG)
static float float b
LockGuard SchedulerLockGuard
Definition scheduler.cpp:32
void wake_scheduler_threadsafe()
uint64_t millis_64()
Definition hal.cpp:29
uint32_t random_uint32()
Return a random 32-bit unsigned integer.
Definition helpers.cpp:10
void HOT delay(uint32_t ms)
Definition hal.cpp:85
Application App
Global storage of Application pointer - only one Application can exist.
constexpr uint32_t SCHEDULER_DONT_RUN
Definition component.h:63
static void uint32_t
uint8_t end[39]
Definition sun_gtil2.cpp:17