From fde80bc53055de3e48af8c6f21c20249929369a5 Mon Sep 17 00:00:00 2001 From: RubenKelevra Date: Sat, 19 Jul 2025 21:44:35 +0200 Subject: [PATCH] core/scheduler: split millis_64_ into different platform functions --- esphome/core/defines.h | 11 +- esphome/core/scheduler.cpp | 267 ++++++++++++++++++++++--------------- esphome/core/scheduler.h | 14 +- 3 files changed, 178 insertions(+), 114 deletions(-) diff --git a/esphome/core/defines.h b/esphome/core/defines.h index 4e3145444d..d13c838ea7 100644 --- a/esphome/core/defines.h +++ b/esphome/core/defines.h @@ -229,14 +229,19 @@ #define USE_SOCKET_SELECT_SUPPORT #endif -// Helper macro for platforms that lack atomic scheduler support +// Helper macro for single core platforms that lack atomic scheduler support #if defined(USE_ESP8266) || defined(USE_RP2040) #define ESPHOME_SINGLE_CORE #endif -// Helper macro for platforms with atomic scheduler support +// Helper macro for multi core platforms that lack atomic scheduler support +#if !defined(ESPHOME_SINGLE_CORE) && defined(USE_LIBRETINY) +#define ESPHOME_MULTI_CORE_NO_ATOMICS +#endif + +// Helper macro for multi core platforms with atomic scheduler support #if !defined(ESPHOME_SINGLE_CORE) && !defined(USE_LIBRETINY) -#define ESPHOME_ATOMIC_SCHEDULER +#define ESPHOME_MULTI_CORE_ATOMICS #endif // Disabled feature flags diff --git a/esphome/core/scheduler.cpp b/esphome/core/scheduler.cpp index 21c45c2f97..ee4ec3818c 100644 --- a/esphome/core/scheduler.cpp +++ b/esphome/core/scheduler.cpp @@ -273,15 +273,15 @@ void HOT Scheduler::call(uint32_t now) { if (now_64 - last_print > 2000) { last_print = now_64; std::vector> old_items; -#ifdef ESPHOME_ATOMIC_SCHEDULER +#ifdef ESPHOME_MULTI_CORE_ATOMICS const auto last_dbg = this->last_millis_.load(std::memory_order_relaxed); const auto major_dbg = this->millis_major_.load(std::memory_order_relaxed); ESP_LOGD(TAG, "Items: count=%zu, now=%" PRIu64 " (%" PRIu16 ", %" PRIu32 ")", this->items_.size(), now_64, major_dbg, last_dbg); -#else /* not ESPHOME_ATOMIC_SCHEDULER */ +#else /* not ESPHOME_MULTI_CORE_ATOMICS */ ESP_LOGD(TAG, "Items: count=%zu, now=%" PRIu64 " (%" PRIu16 ", %" PRIu32 ")", this->items_.size(), now_64, this->millis_major_, this->last_millis_); -#endif /* else ESPHOME_ATOMIC_SCHEDULER */ +#endif /* else ESPHOME_MULTI_CORE_ATOMICS */ while (!this->empty_()) { std::unique_ptr item; { @@ -494,10 +494,18 @@ bool HOT Scheduler::cancel_item_locked_(Component *component, const char *name_c return total_cancelled > 0; } +#ifdef ESPHOME_SINGLE_CORE + uint64_t Scheduler::millis_64_(uint32_t now) { // THREAD SAFETY NOTE: - // This function can be called from multiple threads simultaneously on ESP32/LibreTiny. - // On single-core platforms, atomics are not needed. + // This function has three implemenations, based on the precompiler flags + // - ESPHOME_SINGLE_CORE + // - ESPHOME_MULTI_CORE_NO_ATOMICS + // - ESPHOME_MULTI_CORE_ATOMICS + // + // Make sure all changes are synchronous if you edit this function. + // + // This is the single core implementation. // // IMPORTANT: Always pass fresh millis() values to this function. The implementation // handles out-of-order timestamps between threads, but minimizing time differences @@ -509,101 +517,8 @@ uint64_t Scheduler::millis_64_(uint32_t now) { // This prevents race conditions at the rollover boundary without requiring // 64-bit atomics or locking on every call. -#ifdef ESPHOME_ATOMIC_SCHEDULER - for (;;) { - uint16_t major = this->millis_major_.load(std::memory_order_acquire); -#else /* not ESPHOME_ATOMIC_SCHEDULER */ uint16_t major = this->millis_major_; -#endif /* else ESPHOME_ATOMIC_SCHEDULER */ -#ifdef USE_LIBRETINY - // LibreTiny: Multi-threaded but lacks atomic operation support - // TODO: If LibreTiny ever adds atomic support, remove this entire block and - // let it fall through to the atomic-based implementation below - // We need to use a lock when near the rollover boundary to prevent races - uint32_t last = this->last_millis_; - - // Define a safe window around the rollover point (10 seconds) - // This covers any reasonable scheduler delays or thread preemption - static const uint32_t ROLLOVER_WINDOW = 10000; // 10 seconds in milliseconds - - // Check if we're near the rollover boundary (close to std::numeric_limits::max() or just past 0) - bool near_rollover = (last > (std::numeric_limits::max() - ROLLOVER_WINDOW)) || (now < ROLLOVER_WINDOW); - - if (near_rollover || (now < last && (last - now) > HALF_MAX_UINT32)) { - // Near rollover or detected a rollover - need lock for safety - LockGuard guard{this->lock_}; - // Re-read with lock held - last = this->last_millis_; - - if (now < last && (last - now) > HALF_MAX_UINT32) { - // True rollover detected (happens every ~49.7 days) - this->millis_major_++; - major++; -#ifdef ESPHOME_DEBUG_SCHEDULER - ESP_LOGD(TAG, "Detected true 32-bit rollover at %" PRIu32 "ms (was %" PRIu32 ")", now, last); -#endif /* ESPHOME_DEBUG_SCHEDULER */ - } - // Update last_millis_ while holding lock - this->last_millis_ = now; - } else if (now > last) { - // Normal case: Not near rollover and time moved forward - // Update without lock. While this may cause minor races (microseconds of - // backwards time movement), they're acceptable because: - // 1. The scheduler operates at millisecond resolution, not microsecond - // 2. We've already prevented the critical rollover race condition - // 3. Any backwards movement is orders of magnitude smaller than scheduler delays - this->last_millis_ = now; - } - // If now <= last and we're not near rollover, don't update - // This minimizes backwards time movement - -#elif defined(ESPHOME_ATOMIC_SCHEDULER) - /* - * Multi-threaded platforms with atomic support (ESP32) - * Acquire so that if we later decide **not** to take the lock we still - * observe a `millis_major_` value coherent with the loaded `last_millis_`. - * The acquire load ensures any later read of `millis_major_` sees its - * corresponding increment. - */ - uint32_t last = this->last_millis_.load(std::memory_order_acquire); - - // If we might be near a rollover (large backwards jump), take the lock for the entire operation - // This ensures rollover detection and last_millis_ update are atomic together - if (now < last && (last - now) > HALF_MAX_UINT32) { - // Potential rollover - need lock for atomic rollover detection + update - LockGuard guard{this->lock_}; - // Re-read with lock held; mutex already provides ordering - last = this->last_millis_.load(std::memory_order_relaxed); - - if (now < last && (last - now) > HALF_MAX_UINT32) { - // True rollover detected (happens every ~49.7 days) - this->millis_major_.fetch_add(1, std::memory_order_relaxed); - major++; -#ifdef ESPHOME_DEBUG_SCHEDULER - ESP_LOGD(TAG, "Detected true 32-bit rollover at %" PRIu32 "ms (was %" PRIu32 ")", now, last); -#endif /* ESPHOME_DEBUG_SCHEDULER */ - } - /* - * Update last_millis_ while holding the lock to prevent races - * Publish the new low-word *after* bumping `millis_major_` (done above) - * so readers never see a mismatched pair. - */ - this->last_millis_.store(now, std::memory_order_release); - } else { - // Normal case: Try lock-free update, but only allow forward movement within same epoch - // This prevents accidentally moving backwards across a rollover boundary - while (now > last && (now - last) < HALF_MAX_UINT32) { - if (this->last_millis_.compare_exchange_weak(last, now, - std::memory_order_release, // success - std::memory_order_relaxed)) { // failure - break; - } - // CAS failure means no data was published; relaxed is fine - // last is automatically updated by compare_exchange_weak if it fails - } - } -#else /* not USE_LIBRETINY; not ESPHOME_ATOMIC_SCHEDULER */ // Single-core platforms: No atomics needed uint32_t last = this->last_millis_; @@ -620,19 +535,163 @@ uint64_t Scheduler::millis_64_(uint32_t now) { if (now > last) { this->last_millis_ = now; } -#endif /* else (USE_LIBRETINY / ESPHOME_ATOMIC_SCHEDULER) */ -#ifdef ESPHOME_ATOMIC_SCHEDULER + // Combine major (high 32 bits) and now (low 32 bits) into 64-bit time + return now + (static_cast(major) << 32); +} + +#endif + +#ifdef ESPHOME_MULTI_CORE_NO_ATOMICS + +uint64_t Scheduler::millis_64_(uint32_t now) { + // THREAD SAFETY NOTE: + // This function has three implemenations, based on the precompiler flags + // - ESPHOME_SINGLE_CORE + // - ESPHOME_MULTI_CORE_NO_ATOMICS + // - ESPHOME_MULTI_CORE_ATOMICS + // + // Make sure all changes are synchronous if you edit this function. + // + // This is the multi core no atomics implementation. + // + // IMPORTANT: Always pass fresh millis() values to this function. The implementation + // handles out-of-order timestamps between threads, but minimizing time differences + // helps maintain accuracy. + // + // The implementation handles the 32-bit rollover (every 49.7 days) by: + // 1. Using a lock when detecting rollover to ensure atomic update + // 2. Restricting normal updates to forward movement within the same epoch + // This prevents race conditions at the rollover boundary without requiring + // 64-bit atomics or locking on every call. + + uint16_t major = this->millis_major_; + + // LibreTiny: Multi-threaded but lacks atomic operation support + // TODO: If LibreTiny ever adds atomic support, remove this entire block and + // let it fall through to the atomic-based implementation below + // We need to use a lock when near the rollover boundary to prevent races + uint32_t last = this->last_millis_; + + // Define a safe window around the rollover point (10 seconds) + // This covers any reasonable scheduler delays or thread preemption + static const uint32_t ROLLOVER_WINDOW = 10000; // 10 seconds in milliseconds + + // Check if we're near the rollover boundary (close to std::numeric_limits::max() or just past 0) + bool near_rollover = (last > (std::numeric_limits::max() - ROLLOVER_WINDOW)) || (now < ROLLOVER_WINDOW); + + if (near_rollover || (now < last && (last - now) > HALF_MAX_UINT32)) { + // Near rollover or detected a rollover - need lock for safety + LockGuard guard{this->lock_}; + // Re-read with lock held + last = this->last_millis_; + + if (now < last && (last - now) > HALF_MAX_UINT32) { + // True rollover detected (happens every ~49.7 days) + this->millis_major_++; + major++; +#ifdef ESPHOME_DEBUG_SCHEDULER + ESP_LOGD(TAG, "Detected true 32-bit rollover at %" PRIu32 "ms (was %" PRIu32 ")", now, last); +#endif /* ESPHOME_DEBUG_SCHEDULER */ + } + // Update last_millis_ while holding lock + this->last_millis_ = now; + } else if (now > last) { + // Normal case: Not near rollover and time moved forward + // Update without lock. While this may cause minor races (microseconds of + // backwards time movement), they're acceptable because: + // 1. The scheduler operates at millisecond resolution, not microsecond + // 2. We've already prevented the critical rollover race condition + // 3. Any backwards movement is orders of magnitude smaller than scheduler delays + this->last_millis_ = now; + } + // If now <= last and we're not near rollover, don't update + // This minimizes backwards time movement + + // Combine major (high 32 bits) and now (low 32 bits) into 64-bit time + return now + (static_cast(major) << 32); +} + +#endif + +#ifdef ESPHOME_MULTI_CORE_ATOMICS + +uint64_t Scheduler::millis_64_(uint32_t now) { + // THREAD SAFETY NOTE: + // This function has three implemenations, based on the precompiler flags + // - ESPHOME_SINGLE_CORE + // - ESPHOME_MULTI_CORE_NO_ATOMICS + // - ESPHOME_MULTI_CORE_ATOMICS + // + // Make sure all changes are synchronous if you edit this function. + // + // This is the multi core with atomics implementation. + // + // IMPORTANT: Always pass fresh millis() values to this function. The implementation + // handles out-of-order timestamps between threads, but minimizing time differences + // helps maintain accuracy. + // + // The implementation handles the 32-bit rollover (every 49.7 days) by: + // 1. Using a lock when detecting rollover to ensure atomic update + // 2. Restricting normal updates to forward movement within the same epoch + // This prevents race conditions at the rollover boundary without requiring + // 64-bit atomics or locking on every call. + + for (;;) { + uint16_t major = this->millis_major_.load(std::memory_order_acquire); + + /* + * Multi-threaded platforms with atomic support (ESP32) + * Acquire so that if we later decide **not** to take the lock we still + * observe a `millis_major_` value coherent with the loaded `last_millis_`. + * The acquire load ensures any later read of `millis_major_` sees its + * corresponding increment. + */ + uint32_t last = this->last_millis_.load(std::memory_order_acquire); + + // If we might be near a rollover (large backwards jump), take the lock for the entire operation + // This ensures rollover detection and last_millis_ update are atomic together + if (now < last && (last - now) > HALF_MAX_UINT32) { + // Potential rollover - need lock for atomic rollover detection + update + LockGuard guard{this->lock_}; + // Re-read with lock held; mutex already provides ordering + last = this->last_millis_.load(std::memory_order_relaxed); + + if (now < last && (last - now) > HALF_MAX_UINT32) { + // True rollover detected (happens every ~49.7 days) + this->millis_major_.fetch_add(1, std::memory_order_relaxed); + major++; +#ifdef ESPHOME_DEBUG_SCHEDULER + ESP_LOGD(TAG, "Detected true 32-bit rollover at %" PRIu32 "ms (was %" PRIu32 ")", now, last); +#endif /* ESPHOME_DEBUG_SCHEDULER */ + } + /* + * Update last_millis_ while holding the lock to prevent races + * Publish the new low-word *after* bumping `millis_major_` (done above) + * so readers never see a mismatched pair. + */ + this->last_millis_.store(now, std::memory_order_release); + } else { + // Normal case: Try lock-free update, but only allow forward movement within same epoch + // This prevents accidentally moving backwards across a rollover boundary + while (now > last && (now - last) < HALF_MAX_UINT32) { + if (this->last_millis_.compare_exchange_weak(last, now, + std::memory_order_release, // success + std::memory_order_relaxed)) { // failure + break; + } + // CAS failure means no data was published; relaxed is fine + // last is automatically updated by compare_exchange_weak if it fails + } + } uint16_t major_end = this->millis_major_.load(std::memory_order_relaxed); if (major_end == major) return now + (static_cast(major) << 32); } -#else /* not ESPHOME_ATOMIC_SCHEDULER */ - // Combine major (high 32 bits) and now (low 32 bits) into 64-bit time - return now + (static_cast(major) << 32); -#endif /* ESPHOME_ATOMIC_SCHEDULER */ } +#endif + bool HOT Scheduler::SchedulerItem::cmp(const std::unique_ptr &a, const std::unique_ptr &b) { return a->next_execution_ > b->next_execution_; diff --git a/esphome/core/scheduler.h b/esphome/core/scheduler.h index 540db3c16c..0e3bca22a6 100644 --- a/esphome/core/scheduler.h +++ b/esphome/core/scheduler.h @@ -5,7 +5,7 @@ #include #include #include -#ifdef ESPHOME_ATOMIC_SCHEDULER +#ifdef ESPHOME_MULTI_CORE_ATOMICS #include #endif @@ -209,7 +209,7 @@ class Scheduler { // Single-core platforms don't need the defer queue and save 40 bytes of RAM std::deque> defer_queue_; // FIFO queue for defer() calls #endif /* ESPHOME_SINGLE_CORE */ -#ifdef ESPHOME_ATOMIC_SCHEDULER +#ifdef ESPHOME_MULTI_CORE_ATOMICS /* * Multi-threaded platforms with atomic support: last_millis_ needs atomic for lock-free updates * @@ -221,21 +221,21 @@ class Scheduler { * it also observes the corresponding increment of `millis_major_`. */ std::atomic last_millis_{0}; -#else /* not ESPHOME_ATOMIC_SCHEDULER */ +#else /* not ESPHOME_MULTI_CORE_ATOMICS */ // Platforms without atomic support or single-threaded platforms uint32_t last_millis_{0}; -#endif /* else ESPHOME_ATOMIC_SCHEDULER */ +#endif /* else ESPHOME_MULTI_CORE_ATOMICS */ /* * Upper 16 bits of the 64-bit millis counter. Incremented only while holding * `lock_`; read concurrently. Atomic (relaxed) avoids a formal data race. * Ordering relative to `last_millis_` is provided by its release store and the * corresponding acquire loads. */ -#ifdef ESPHOME_ATOMIC_SCHEDULER +#ifdef ESPHOME_MULTI_CORE_ATOMICS std::atomic millis_major_{0}; -#else /* not ESPHOME_ATOMIC_SCHEDULER */ +#else /* not ESPHOME_MULTI_CORE_ATOMICS */ uint16_t millis_major_{0}; -#endif /* else ESPHOME_ATOMIC_SCHEDULER */ +#endif /* else ESPHOME_MULTI_CORE_ATOMICS */ uint32_t to_remove_{0}; };