core/scheduler: split millis_64_ into different platform functions

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

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<std::unique_ptr<SchedulerItem>> 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<SchedulerItem> 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.
+  // This function has three implemenations, based on the precompiler flags
-  // On single-core platforms, atomics are not needed.
+  // - 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<uint32_t>::max() or just past 0)
-    bool near_rollover = (last > (std::numeric_limits<uint32_t>::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<uint64_t>(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<uint32_t>::max() or just past 0)
+  bool near_rollover = (last > (std::numeric_limits<uint32_t>::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<uint64_t>(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<uint64_t>(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<uint64_t>(major) << 32);
-#endif /* ESPHOME_ATOMIC_SCHEDULER */
 }
 
+#endif
+
 bool HOT Scheduler::SchedulerItem::cmp(const std::unique_ptr<SchedulerItem> &a,
                                        const std::unique_ptr<SchedulerItem> &b) {
   return a->next_execution_ > b->next_execution_;

esphome/core/scheduler.h

@@ -5,7 +5,7 @@
 #include <memory>
 #include <cstring>
 #include <deque>
-#ifdef ESPHOME_ATOMIC_SCHEDULER
+#ifdef ESPHOME_MULTI_CORE_ATOMICS
 #include <atomic>
 #endif
 
@@ -209,7 +209,7 @@ class Scheduler {
   // Single-core platforms don't need the defer queue and save 40 bytes of RAM
   std::deque<std::unique_ptr<SchedulerItem>> 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<uint32_t> 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<uint16_t> 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};
 };