[preferences] Devirtualize preference backend and manager classes

Eliminates virtual dispatch from ESPPreferenceBackend and ESPPreferences. Only one implementation of each exists per platform build, so the polymorphic design was unnecessary overhead — same pattern as OTA (#14473) and socket (#14398) devirtualizations. Each platform's backend class is now a standalone final class in its own header (preference_backend.h). The preferences manager class is extracted to the platform's preferences.h with a PreferencesMixin CRTP base for shared template helpers. core/preference_backend.h provides the PreferenceBackend alias, ESPPreferenceObject, and DECLARE_PREFERENCE_ALIASES macro. core/preferences.h is a thin wrapper including the active platform. ESPPreferenceBackend and ESPPreferences become backward-compatible type aliases to the concrete types. Zero caller changes required.
2026-10-05 10:31:29 +00:00 · 2026-03-15 08:49:40 -10:00
parent fe9f19d9ed
commit 9529adb049
20 changed files with 1021 additions and 763 deletions
@@ -1,16 +1,14 @@
 #ifdef USE_ESP32

+#include "preferences.h"
 #include "esphome/core/helpers.h"
 #include "esphome/core/log.h"
-#include "esphome/core/preferences.h"
 #include <nvs_flash.h>
 #include <cinttypes>
 #include <cstring>
-#include <memory>
 #include <vector>

-namespace esphome {
-namespace esp32 {
+namespace esphome::esp32 {

 static const char *const TAG = "esp32.preferences";

@@ -24,185 +22,175 @@ struct NVSData {

 static std::vector<NVSData> s_pending_save;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)

-class ESP32PreferenceBackend : public ESPPreferenceBackend {
- public:
-  uint32_t key;
-  uint32_t nvs_handle;
-  bool save(const uint8_t *data, size_t len) override {
-    // try find in pending saves and update that
-    for (auto &obj : s_pending_save) {
-      if (obj.key == this->key) {
-        obj.data.set(data, len);
-        return true;
-      }
+bool ESP32PreferenceBackend::save(const uint8_t *data, size_t len) {
+  // try find in pending saves and update that
+  for (auto &obj : s_pending_save) {
+    if (obj.key == this->key) {
+      obj.data.set(data, len);
+      return true;
    }
-    NVSData save{};
-    save.key = this->key;
-    save.data.set(data, len);
-    s_pending_save.push_back(std::move(save));
-    ESP_LOGVV(TAG, "s_pending_save: key: %" PRIu32 ", len: %zu", this->key, len);
-    return true;
  }
-  bool load(uint8_t *data, size_t len) override {
-    // try find in pending saves and load from that
-    for (auto &obj : s_pending_save) {
-      if (obj.key == this->key) {
-        if (obj.data.size() != len) {
-          // size mismatch
-          return false;
-        }
-        memcpy(data, obj.data.data(), len);
-        return true;
-      }
-    }
+  NVSData save{};
+  save.key = this->key;
+  save.data.set(data, len);
+  s_pending_save.push_back(std::move(save));
+  ESP_LOGVV(TAG, "s_pending_save: key: %" PRIu32 ", len: %zu", this->key, len);
+  return true;
+}

+bool ESP32PreferenceBackend::load(uint8_t *data, size_t len) {
+  // try find in pending saves and load from that
+  for (auto &obj : s_pending_save) {
+    if (obj.key == this->key) {
+      if (obj.data.size() != len) {
+        // size mismatch
+        return false;
+      }
+      memcpy(data, obj.data.data(), len);
+      return true;
+    }
+  }
+
+  char key_str[KEY_BUFFER_SIZE];
+  snprintf(key_str, sizeof(key_str), "%" PRIu32, this->key);
+  size_t actual_len;
+  esp_err_t err = nvs_get_blob(this->nvs_handle, key_str, nullptr, &actual_len);
+  if (err != 0) {
+    ESP_LOGV(TAG, "nvs_get_blob('%s'): %s - the key might not be set yet", key_str, esp_err_to_name(err));
+    return false;
+  }
+  if (actual_len != len) {
+    ESP_LOGVV(TAG, "NVS length does not match (%zu!=%zu)", actual_len, len);
+    return false;
+  }
+  err = nvs_get_blob(this->nvs_handle, key_str, data, &len);
+  if (err != 0) {
+    ESP_LOGV(TAG, "nvs_get_blob('%s') failed: %s", key_str, esp_err_to_name(err));
+    return false;
+  } else {
+    ESP_LOGVV(TAG, "nvs_get_blob: key: %s, len: %zu", key_str, len);
+  }
+  return true;
+}
+
+void ESP32Preferences::open() {
+  nvs_flash_init();
+  esp_err_t err = nvs_open("esphome", NVS_READWRITE, &this->nvs_handle);
+  if (err == 0)
+    return;
+
+  ESP_LOGW(TAG, "nvs_open failed: %s - erasing NVS", esp_err_to_name(err));
+  nvs_flash_deinit();
+  nvs_flash_erase();
+  nvs_flash_init();
+
+  err = nvs_open("esphome", NVS_READWRITE, &this->nvs_handle);
+  if (err != 0) {
+    this->nvs_handle = 0;
+  }
+}
+
+ESPPreferenceObject ESP32Preferences::make_preference(size_t length, uint32_t type) {
+  auto *pref = new ESP32PreferenceBackend();  // NOLINT(cppcoreguidelines-owning-memory)
+  pref->nvs_handle = this->nvs_handle;
+  pref->key = type;
+
+  return ESPPreferenceObject(pref);
+}
+
+bool ESP32Preferences::sync() {
+  if (s_pending_save.empty())
+    return true;
+
+  ESP_LOGV(TAG, "Saving %zu items...", s_pending_save.size());
+  int cached = 0, written = 0, failed = 0;
+  esp_err_t last_err = ESP_OK;
+  uint32_t last_key = 0;
+
+  for (const auto &save : s_pending_save) {
    char key_str[KEY_BUFFER_SIZE];
-    snprintf(key_str, sizeof(key_str), "%" PRIu32, this->key);
-    size_t actual_len;
-    esp_err_t err = nvs_get_blob(this->nvs_handle, key_str, nullptr, &actual_len);
-    if (err != 0) {
-      ESP_LOGV(TAG, "nvs_get_blob('%s'): %s - the key might not be set yet", key_str, esp_err_to_name(err));
-      return false;
-    }
-    if (actual_len != len) {
-      ESP_LOGVV(TAG, "NVS length does not match (%zu!=%zu)", actual_len, len);
-      return false;
-    }
-    err = nvs_get_blob(this->nvs_handle, key_str, data, &len);
-    if (err != 0) {
-      ESP_LOGV(TAG, "nvs_get_blob('%s') failed: %s", key_str, esp_err_to_name(err));
-      return false;
-    } else {
-      ESP_LOGVV(TAG, "nvs_get_blob: key: %s, len: %zu", key_str, len);
-    }
-    return true;
-  }
-};
-
-class ESP32Preferences : public ESPPreferences {
- public:
-  uint32_t nvs_handle;
-
-  void open() {
-    nvs_flash_init();
-    esp_err_t err = nvs_open("esphome", NVS_READWRITE, &nvs_handle);
-    if (err == 0)
-      return;
-
-    ESP_LOGW(TAG, "nvs_open failed: %s - erasing NVS", esp_err_to_name(err));
-    nvs_flash_deinit();
-    nvs_flash_erase();
-    nvs_flash_init();
-
-    err = nvs_open("esphome", NVS_READWRITE, &nvs_handle);
-    if (err != 0) {
-      nvs_handle = 0;
-    }
-  }
-  ESPPreferenceObject make_preference(size_t length, uint32_t type, bool in_flash) override {
-    return this->make_preference(length, type);
-  }
-  ESPPreferenceObject make_preference(size_t length, uint32_t type) override {
-    auto *pref = new ESP32PreferenceBackend();  // NOLINT(cppcoreguidelines-owning-memory)
-    pref->nvs_handle = this->nvs_handle;
-    pref->key = type;
-
-    return ESPPreferenceObject(pref);
-  }
-
-  bool sync() override {
-    if (s_pending_save.empty())
-      return true;
-
-    ESP_LOGV(TAG, "Saving %zu items...", s_pending_save.size());
-    int cached = 0, written = 0, failed = 0;
-    esp_err_t last_err = ESP_OK;
-    uint32_t last_key = 0;
-
-    for (const auto &save : s_pending_save) {
-      char key_str[KEY_BUFFER_SIZE];
-      snprintf(key_str, sizeof(key_str), "%" PRIu32, save.key);
-      ESP_LOGVV(TAG, "Checking if NVS data %s has changed", key_str);
-      if (this->is_changed_(this->nvs_handle, save, key_str)) {
-        esp_err_t err = nvs_set_blob(this->nvs_handle, key_str, save.data.data(), save.data.size());
-        ESP_LOGV(TAG, "sync: key: %s, len: %zu", key_str, save.data.size());
-        if (err != 0) {
-          ESP_LOGV(TAG, "nvs_set_blob('%s', len=%zu) failed: %s", key_str, save.data.size(), esp_err_to_name(err));
-          failed++;
-          last_err = err;
-          last_key = save.key;
-          continue;
-        }
-        written++;
-      } else {
-        ESP_LOGV(TAG, "NVS data not changed skipping %" PRIu32 "  len=%zu", save.key, save.data.size());
-        cached++;
+    snprintf(key_str, sizeof(key_str), "%" PRIu32, save.key);
+    ESP_LOGVV(TAG, "Checking if NVS data %s has changed", key_str);
+    if (this->is_changed_(this->nvs_handle, save, key_str)) {
+      esp_err_t err = nvs_set_blob(this->nvs_handle, key_str, save.data.data(), save.data.size());
+      ESP_LOGV(TAG, "sync: key: %s, len: %zu", key_str, save.data.size());
+      if (err != 0) {
+        ESP_LOGV(TAG, "nvs_set_blob('%s', len=%zu) failed: %s", key_str, save.data.size(), esp_err_to_name(err));
+        failed++;
+        last_err = err;
+        last_key = save.key;
+        continue;
      }
+      written++;
+    } else {
+      ESP_LOGV(TAG, "NVS data not changed skipping %" PRIu32 "  len=%zu", save.key, save.data.size());
+      cached++;
    }
-    s_pending_save.clear();
+  }
+  s_pending_save.clear();

-    ESP_LOGD(TAG, "Writing %d items: %d cached, %d written, %d failed", cached + written + failed, cached, written,
-             failed);
-    if (failed > 0) {
-      ESP_LOGE(TAG, "Writing %d items failed. Last error=%s for key=%" PRIu32, failed, esp_err_to_name(last_err),
-               last_key);
-    }
-
-    // note: commit on esp-idf currently is a no-op, nvs_set_blob always writes
-    esp_err_t err = nvs_commit(this->nvs_handle);
-    if (err != 0) {
-      ESP_LOGV(TAG, "nvs_commit() failed: %s", esp_err_to_name(err));
-      return false;
-    }
-
-    return failed == 0;
+  ESP_LOGD(TAG, "Writing %d items: %d cached, %d written, %d failed", cached + written + failed, cached, written,
+           failed);
+  if (failed > 0) {
+    ESP_LOGE(TAG, "Writing %d items failed. Last error=%s for key=%" PRIu32, failed, esp_err_to_name(last_err),
+             last_key);
  }

- protected:
-  bool is_changed_(uint32_t nvs_handle, const NVSData &to_save, const char *key_str) {
-    size_t actual_len;
-    esp_err_t err = nvs_get_blob(nvs_handle, key_str, nullptr, &actual_len);
-    if (err != 0) {
-      ESP_LOGV(TAG, "nvs_get_blob('%s'): %s - the key might not be set yet", key_str, esp_err_to_name(err));
-      return true;
-    }
-    // Check size first before allocating memory
-    if (actual_len != to_save.data.size()) {
-      return true;
-    }
-    // Most preferences are small, use stack buffer with heap fallback for large ones
-    SmallBufferWithHeapFallback<256> stored_data(actual_len);
-    err = nvs_get_blob(nvs_handle, key_str, stored_data.get(), &actual_len);
-    if (err != 0) {
-      ESP_LOGV(TAG, "nvs_get_blob('%s') failed: %s", key_str, esp_err_to_name(err));
-      return true;
-    }
-    return memcmp(to_save.data.data(), stored_data.get(), to_save.data.size()) != 0;
+  // note: commit on esp-idf currently is a no-op, nvs_set_blob always writes
+  esp_err_t err = nvs_commit(this->nvs_handle);
+  if (err != 0) {
+    ESP_LOGV(TAG, "nvs_commit() failed: %s", esp_err_to_name(err));
+    return false;
  }

-  bool reset() override {
-    ESP_LOGD(TAG, "Erasing storage");
-    s_pending_save.clear();
+  return failed == 0;
+}

-    nvs_flash_deinit();
-    nvs_flash_erase();
-    // Make the handle invalid to prevent any saves until restart
-    nvs_handle = 0;
+bool ESP32Preferences::is_changed_(uint32_t nvs_handle, const NVSData &to_save, const char *key_str) {
+  size_t actual_len;
+  esp_err_t err = nvs_get_blob(nvs_handle, key_str, nullptr, &actual_len);
+  if (err != 0) {
+    ESP_LOGV(TAG, "nvs_get_blob('%s'): %s - the key might not be set yet", key_str, esp_err_to_name(err));
    return true;
  }
-};
+  // Check size first before allocating memory
+  if (actual_len != to_save.data.size()) {
+    return true;
+  }
+  // Most preferences are small, use stack buffer with heap fallback for large ones
+  SmallBufferWithHeapFallback<256> stored_data(actual_len);
+  err = nvs_get_blob(nvs_handle, key_str, stored_data.get(), &actual_len);
+  if (err != 0) {
+    ESP_LOGV(TAG, "nvs_get_blob('%s') failed: %s", key_str, esp_err_to_name(err));
+    return true;
+  }
+  return memcmp(to_save.data.data(), stored_data.get(), to_save.data.size()) != 0;
+}
+
+bool ESP32Preferences::reset() {
+  ESP_LOGD(TAG, "Erasing storage");
+  s_pending_save.clear();
+
+  nvs_flash_deinit();
+  nvs_flash_erase();
+  // Make the handle invalid to prevent any saves until restart
+  this->nvs_handle = 0;
+  return true;
+}

 static ESP32Preferences s_preferences;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)

+ESP32Preferences *get_preferences() { return &s_preferences; }
+
 void setup_preferences() {
  s_preferences.open();
  global_preferences = &s_preferences;
 }

-}  // namespace esp32
+}  // namespace esphome::esp32

+namespace esphome {
 ESPPreferences *global_preferences;  // NOLINT(cppcoreguidelines-avoid-non-const-global-variables)
-
 }  // namespace esphome

 #endif  // USE_ESP32