ESPBufferManager integration

Author: zekageri

CHANGELOG.md

@@ -8,6 +8,7 @@ The format follows Keep a Changelog and the project adheres to Semantic Versioni
 ### Changed
 - Removed the library-provided inline `timer` instance. Sketches should now declare their own `ESPTimer` objects (global, static, or as class members) before calling `init()`, enabling multiple independent timer managers.
 - Added `clearTimeout(id)` for explicit timeout cancellation and kept `clearTimer(id)` as a backward-compatible alias.
+- Added `ESPTimerConfig::usePSRAMBuffers` and routed timer-owned persistent/transient vectors through `ESPBufferManager` with safe fallback to default heap.
 
 ### Fixed
 - Ensured per-second and per-minute countdown timers emit their final tick by rounding up remaining time.

README.md

@@ -60,6 +60,7 @@ Explore `examples/Basic/Basic.ino` for a complete sketch that demonstrates all t
 - `pause*` calls are idempotent and only transition `Running → Paused`. Use the matching `resume*` or `toggleRunStatus*` helpers to continue.
 - Each timer type owns its own FreeRTOS task. Tune `ESPTimerConfig` when you need larger stacks or different priorities.
 - IDs are unique per `ESPTimer` instance. Clearing a timer frees the ID; reusing stale IDs after `clear*` will fail.
+- `usePSRAMBuffers = true` is best-effort for timer-owned dynamic buffers. If PSRAM is unavailable, allocation falls back to normal heap automatically.
 
 ## API Reference
 - `void init(const ESPTimerConfig& cfg = {})` – allocate mutexes and spawn each timer task with the provided stack/priority/core settings.
@@ -77,6 +78,9 @@ Explore `examples/Basic/Basic.ino` for a complete sketch that demonstrates all t
 - Stack sizes (`stackSizeTimeout`, `stackSizeInterval`, `stackSizeSec`, `stackSizeMs`, `stackSizeMin`).
 - Priorities (`priorityTimeout`, …).
 - Core affinity (`core*`, `-1` = no pin).
+- Buffer policy (`usePSRAMBuffers`) for timer-owned vectors and callback dispatch staging buffers.
+
+`usePSRAMBuffers` only affects allocations owned by ESPTimer. Callback captures (`std::function`) can still allocate outside this policy depending on capture size and STL behavior.
 
 `ESPTimerStatus` reports `Invalid`, `Running`, `Paused`, `Stopped`, or `Completed`.
 

library.json

@@ -21,7 +21,12 @@
   ],
   "frameworks": ["arduino"],
   "platforms": ["espressif32"],
-  "dependencies": [],
+  "dependencies": [
+    {
+      "name": "ESPBufferManager",
+      "version": "https://github.com/ESPToolKit/esp-buffer-manager.git"
+    }
+  ],
   "headers": ["ESPTimer.h"],
   "build": {
     "flags": [

library.properties

@@ -8,5 +8,5 @@ category=HTTP
 url=https://github.com/ESPToolKit/esp-timer
 repository=https://github.com/ESPToolKit/esp-timer.git
 architectures=esp32
-depends=
+depends=ESPBufferManager
 license=MIT

src/esp_timer/timer.cpp

@@ -61,6 +61,18 @@ uint32_t ESPTimer::nextId() {
 void ESPTimer::init(const ESPTimerConfig& cfg) {
   if (initialized_) return;
   cfg_ = cfg;
+  usePSRAMBuffers_ = cfg_.usePSRAMBuffers;
+
+  TimerVector<TimeoutItem> timeoutStorage{TimerAllocator<TimeoutItem>(usePSRAMBuffers_)};
+  timeouts_.swap(timeoutStorage);
+  TimerVector<IntervalItem> intervalStorage{TimerAllocator<IntervalItem>(usePSRAMBuffers_)};
+  intervals_.swap(intervalStorage);
+  TimerVector<SecItem> secStorage{TimerAllocator<SecItem>(usePSRAMBuffers_)};
+  secs_.swap(secStorage);
+  TimerVector<MsItem> msStorage{TimerAllocator<MsItem>(usePSRAMBuffers_)};
+  mss_.swap(msStorage);
+  TimerVector<MinItem> minStorage{TimerAllocator<MinItem>(usePSRAMBuffers_)};
+  mins_.swap(minStorage);
 
   if (!mutex_) {
     mutex_ = xSemaphoreCreateMutex();
@@ -380,9 +392,10 @@ void ESPTimer::minTaskTrampoline(void* arg) { static_cast<ESPTimer*>(arg)->minTa
 void ESPTimer::timeoutTask() {
   while (running_.load(std::memory_order_acquire)) {
     const uint32_t now = millis();
-    std::vector<std::function<void()>> toCall;
+    TimerVector<std::function<void()>> toCall{TimerAllocator<std::function<void()>>(usePSRAMBuffers_)};
 
     lock();
+    toCall.reserve(timeouts_.size());
     // Collect callbacks due and remove completed
     auto it = timeouts_.begin();
     while (it != timeouts_.end()) {
@@ -410,9 +423,10 @@ void ESPTimer::timeoutTask() {
 void ESPTimer::intervalTask() {
   while (running_.load(std::memory_order_acquire)) {
     const uint32_t now = millis();
-    std::vector<std::function<void()>> toCall;
+    TimerVector<std::function<void()>> toCall{TimerAllocator<std::function<void()>>(usePSRAMBuffers_)};
 
     lock();
+    toCall.reserve(intervals_.size());
     for (auto& it : intervals_) {
       if (it.status == ESPTimerStatus::Running) {
         if (now - it.lastFireMs >= it.periodMs) {
@@ -442,9 +456,10 @@ void ESPTimer::secTask() {
   while (running_.load(std::memory_order_acquire)) {
     const uint32_t now = millis();
     struct Call { std::function<void(int)> fn; int arg; };
-    std::vector<Call> toCall;
+    TimerVector<Call> toCall{TimerAllocator<Call>(usePSRAMBuffers_)};
 
     lock();
+    toCall.reserve(secs_.size());
     for (auto& it : secs_) {
       if (it.status == ESPTimerStatus::Running) {
         if (now - it.lastTickMs >= 1000) {
@@ -482,9 +497,10 @@ void ESPTimer::msTask() {
   while (running_.load(std::memory_order_acquire)) {
     const uint32_t now = millis();
     struct Call { std::function<void(uint32_t)> fn; uint32_t arg; };
-    std::vector<Call> toCall;
+    TimerVector<Call> toCall{TimerAllocator<Call>(usePSRAMBuffers_)};
 
     lock();
+    toCall.reserve(mss_.size());
     for (auto& it : mss_) {
       if (it.status == ESPTimerStatus::Running) {
         // Fire at ~1ms cadence; on busy systems it may be coarser
@@ -519,9 +535,10 @@ void ESPTimer::minTask() {
   while (running_.load(std::memory_order_acquire)) {
     const uint32_t now = millis();
     struct Call { std::function<void(int)> fn; int arg; };
-    std::vector<Call> toCall;
+    TimerVector<Call> toCall{TimerAllocator<Call>(usePSRAMBuffers_)};
 
     lock();
+    toCall.reserve(mins_.size());
     for (auto& it : mins_) {
       if (it.status == ESPTimerStatus::Running) {
         if (now - it.lastTickMs >= 60000) {

src/esp_timer/timer.h

@@ -7,6 +7,7 @@
 #include <freertos/FreeRTOS.h>
 #include <freertos/task.h>
 #include <freertos/semphr.h>
+#include "timer_allocator.h"
 
 // Public types
 enum class ESPTimerStatus : uint8_t {
@@ -38,6 +39,10 @@ struct ESPTimerConfig {
   int8_t coreSec = -1;
   int8_t coreMs = -1;
   int8_t coreMin = -1;
+
+  // Prefer PSRAM-backed buffers for timer-owned dynamic containers.
+  // Falls back to default heap automatically when unavailable.
+  bool usePSRAMBuffers = false;
 };
 
 class ESPTimer {
@@ -128,11 +133,11 @@ class ESPTimer {
   };
 
   // Storage per type
-  std::vector<TimeoutItem> timeouts_;
-  std::vector<IntervalItem> intervals_;
-  std::vector<SecItem> secs_;
-  std::vector<MsItem> mss_;
-  std::vector<MinItem> mins_;
+  TimerVector<TimeoutItem> timeouts_;
+  TimerVector<IntervalItem> intervals_;
+  TimerVector<SecItem> secs_;
+  TimerVector<MsItem> mss_;
+  TimerVector<MinItem> mins_;
 
   // FreeRTOS bits
   SemaphoreHandle_t mutex_ = nullptr;
@@ -146,6 +151,7 @@ class ESPTimer {
   bool initialized_ = false;
   std::atomic<bool> running_{false};
   uint32_t nextId_ = 1;
+  bool usePSRAMBuffers_ = false;
 
   uint32_t nextId();
   void lock();

src/esp_timer/timer_allocator.h

@@ -0,0 +1,98 @@
+#pragma once
+
+#if __has_include(<ESPBufferManager.h>)
+#include <ESPBufferManager.h>
+#define ESP_TIMER_HAS_BUFFER_MANAGER 1
+#elif __has_include(<esp_buffer_manager/buffer_manager.h>)
+#include <esp_buffer_manager/buffer_manager.h>
+#define ESP_TIMER_HAS_BUFFER_MANAGER 1
+#else
+#define ESP_TIMER_HAS_BUFFER_MANAGER 0
+#endif
+
+#include <cstddef>
+#include <cstdlib>
+#include <limits>
+#include <new>
+#include <vector>
+
+namespace timer_allocator_detail {
+inline void* allocate(std::size_t bytes, bool usePSRAMBuffers) noexcept {
+#if ESP_TIMER_HAS_BUFFER_MANAGER
+  return ESPBufferManager::allocate(bytes, usePSRAMBuffers);
+#else
+  (void)usePSRAMBuffers;
+  return std::malloc(bytes);
+#endif
+}
+
+inline void deallocate(void* ptr) noexcept {
+#if ESP_TIMER_HAS_BUFFER_MANAGER
+  ESPBufferManager::deallocate(ptr);
+#else
+  std::free(ptr);
+#endif
+}
+}  // namespace timer_allocator_detail
+
+template <typename T>
+class TimerAllocator {
+ public:
+  using value_type = T;
+
+  TimerAllocator() noexcept = default;
+  explicit TimerAllocator(bool usePSRAMBuffers) noexcept : usePSRAMBuffers_(usePSRAMBuffers) {}
+
+  template <typename U>
+  TimerAllocator(const TimerAllocator<U>& other) noexcept : usePSRAMBuffers_(other.usePSRAMBuffers()) {}
+
+  T* allocate(std::size_t n) {
+    if (n == 0) {
+      return nullptr;
+    }
+    if (n > (std::numeric_limits<std::size_t>::max() / sizeof(T))) {
+#if defined(__cpp_exceptions)
+      throw std::bad_alloc();
+#else
+      std::abort();
+#endif
+    }
+
+    void* memory = timer_allocator_detail::allocate(n * sizeof(T), usePSRAMBuffers_);
+    if (memory == nullptr) {
+#if defined(__cpp_exceptions)
+      throw std::bad_alloc();
+#else
+      std::abort();
+#endif
+    }
+    return static_cast<T*>(memory);
+  }
+
+  void deallocate(T* ptr, std::size_t) noexcept {
+    timer_allocator_detail::deallocate(ptr);
+  }
+
+  bool usePSRAMBuffers() const noexcept {
+    return usePSRAMBuffers_;
+  }
+
+  template <typename U>
+  bool operator==(const TimerAllocator<U>& other) const noexcept {
+    return usePSRAMBuffers_ == other.usePSRAMBuffers();
+  }
+
+  template <typename U>
+  bool operator!=(const TimerAllocator<U>& other) const noexcept {
+    return !(*this == other);
+  }
+
+ private:
+  template <typename>
+  friend class TimerAllocator;
+
+  bool usePSRAMBuffers_ = false;
+};
+
+template <typename T>
+using TimerVector = std::vector<T, TimerAllocator<T>>;

test/test_basic/test_main.cpp

@@ -6,6 +6,7 @@ ESPTimer timer;
 
 void test_api_compiles() {
     ESPTimerConfig cfg;
+    cfg.usePSRAMBuffers = true;
     timer.init(cfg);
 
     auto id1 = timer.setTimeout([]() {}, 1000);