Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(rc6): ResourcePool eviction budget + LRU (3-state lifecycle) (E-core)

yhh65e48a661ac1
diff --git a/src/esengine/resource/ResourcePool.hpp b/src/esengine/resource/ResourcePool.hpp
index 0bb34a928..2acce7e23 100644
--- a/src/esengine/resource/ResourcePool.hpp
+++ b/src/esengine/resource/ResourcePool.hpp
@@ -89,9 +89,13 @@ public:
*/
struct Entry {
Unique<T> resource; ///< The owned resource
- u32 refCount = 0; ///< Reference count (0 = freed)
+ u32 refCount = 0; ///< Reference count (0 = freed or evictable)
std::string path; ///< Optional path for caching
u32 generation = 0; ///< Reuse counter for stale handle detection
+ usize bytes = 0; ///< Resource size, for the eviction budget (0 = untracked)
+ bool evictable = false;///< refCount==0 but retained as a cache entry (in the LRU)
+ u32 lruPrev = 0; ///< Intrusive LRU links (entry index; 0 = sentinel/none)
+ u32 lruNext = 0; ///< Intrusive LRU links (entry index; 0 = sentinel/none)
};
ResourcePool() {
@@ -109,25 +113,28 @@ public:
* @brief Adds a resource to the pool
* @param resource The resource to add (takes ownership)
* @param path Optional path for cache lookup
+ * @param bytes Resource size for the eviction budget (0 = untracked)
* @return Handle to the added resource
*/
- Handle<T> add(Unique<T> resource, const std::string& path = "") {
+ Handle<T> add(Unique<T> resource, const std::string& path = "", usize bytes = 0) {
u32 index;
u32 gen;
if (!freeList_.empty()) {
index = freeList_.back();
freeList_.pop_back();
gen = entries_[index].generation;
- entries_[index] = {std::move(resource), 1, path, gen};
+ entries_[index] = {std::move(resource), 1, path, gen, bytes, false, 0, 0};
} else {
index = static_cast<u32>(entries_.size());
gen = 0;
- entries_.push_back({std::move(resource), 1, path, 0});
+ entries_.push_back({std::move(resource), 1, path, 0, bytes, false, 0, 0});
}
+ residentBytes_ += bytes;
auto handle = Handle<T>::fromParts(index, gen);
if (!path.empty()) {
pathToId_[path] = handle.id();
}
+ enforceBudget_(); // the new resource is held; this evicts OTHER evictables if over budget
return handle;
}
@@ -205,11 +212,17 @@ public:
void addRef(Handle<T> handle) {
if (!handle.isValid()) return;
u32 idx = handle.index();
- if (idx < entries_.size()) {
- auto& entry = entries_[idx];
- if (entry.refCount > 0 && entry.generation == handle.generation()) {
- entry.refCount++;
- }
+ if (idx >= entries_.size()) return;
+ auto& entry = entries_[idx];
+ if (entry.generation != handle.generation()) return;
+ if (entry.evictable) {
+ // Reviving a cached (refCount==0) entry: pull it out of the LRU back
+ // into the held state. This is the cache-hit path (findByPath → addRef).
+ lruRemove_(idx);
+ entry.evictable = false;
+ entry.refCount = 1;
+ } else if (entry.refCount > 0) {
+ entry.refCount++;
}
}
@@ -224,13 +237,16 @@ public:
auto& entry = entries_[index];
if (entry.refCount == 0 || entry.generation != gen) return;
if (--entry.refCount == 0) {
- if (!entry.path.empty()) {
- pathToId_.erase(entry.path);
+ if (budget_ == 0) {
+ freeEntry_(index); // no budget → free immediately (the default)
+ } else {
+ // 3-state lifecycle: held → evictable (cached in the LRU, still
+ // findByPath-able for cache hits) → evicted. Drop the oldest
+ // evictable entries if this pushed us over the byte budget.
+ entry.evictable = true;
+ lruPushBack_(index);
+ enforceBudget_();
}
- entry.resource.reset();
- entry.path.clear();
- entry.generation = (entry.generation + 1) & Handle<T>::GEN_MASK;
- freeList_.push_back(index);
}
}
@@ -249,7 +265,47 @@ public:
entries_.clear();
freeList_.clear();
pathToId_.clear();
- entries_.push_back({nullptr, 0, "", 0});
+ residentBytes_ = 0;
+ lruHead_ = 0;
+ lruTail_ = 0;
+ entries_.push_back({nullptr, 0, "", 0, 0, false, 0, 0}); // reserved sentinel (index 0)
+ }
+
+ // =========================================================================
+ // Eviction budget (RC6 gap 3): held → evictable → evicted
+ // =========================================================================
+
+ /**
+ * @brief Sets the resident-byte budget. 0 (default) disables caching — a
+ * resource is freed the instant its refCount hits 0 (legacy behavior).
+ * When > 0, refCount==0 resources are retained as evictable cache
+ * entries and dropped (oldest-first) only when over budget.
+ */
+ void setBudget(usize bytes) {
+ budget_ = bytes;
+ enforceBudget_();
+ }
+
+ /** @brief The current resident-byte budget (0 = caching disabled). */
+ usize budget() const { return budget_; }
+
+ /** @brief Bytes currently resident (held + evictable entries). */
+ usize residentBytes() const { return residentBytes_; }
+
+ /** @brief Number of evictable (refCount==0, cached) entries. */
+ usize evictableCount() const {
+ usize n = 0;
+ for (u32 i = lruHead_; i != 0; i = entries_[i].lruNext) ++n;
+ return n;
+ }
+
+ /** @brief True if the handle's entry is alive but evictable (cached). */
+ bool isEvictable(Handle<T> handle) const {
+ if (!handle.isValid()) return false;
+ u32 idx = handle.index();
+ if (idx >= entries_.size()) return false;
+ const auto& entry = entries_[idx];
+ return entry.generation == handle.generation() && entry.evictable;
}
/**
@@ -282,9 +338,65 @@ public:
}
private:
+ /** Actually free an entry: drop its resource + path, recycle the slot. */
+ void freeEntry_(u32 index) {
+ auto& entry = entries_[index];
+ if (entry.evictable) lruRemove_(index);
+ // Only drop the path mapping if it still points here — a later add() of the
+ // same path (while this entry lingered evictable) may have re-bound it.
+ if (!entry.path.empty()) {
+ auto it = pathToId_.find(entry.path);
+ if (it != pathToId_.end() && Handle<T>::extractIndex(it->second) == index) {
+ pathToId_.erase(it);
+ }
+ }
+ residentBytes_ -= entry.bytes;
+ entry.resource.reset();
+ entry.path.clear();
+ entry.bytes = 0;
+ entry.evictable = false;
+ entry.generation = (entry.generation + 1) & Handle<T>::GEN_MASK;
+ freeList_.push_back(index);
+ }
+
+ /** Evict oldest evictable entries until resident bytes fit the budget. Held
+ * (refCount>0) entries are never evicted, so resident can exceed the budget
+ * when the live set alone does — that's unavoidable, not a bug. */
+ void enforceBudget_() {
+ if (budget_ == 0) return;
+ while (residentBytes_ > budget_ && lruHead_ != 0) {
+ freeEntry_(lruHead_); // freeEntry_ → lruRemove_ advances lruHead_
+ }
+ }
+
+ /** Append `index` as the most-recently-released (LRU tail). */
+ void lruPushBack_(u32 index) {
+ auto& e = entries_[index];
+ e.lruNext = 0;
+ e.lruPrev = lruTail_;
+ if (lruTail_ != 0) entries_[lruTail_].lruNext = index;
+ else lruHead_ = index;
+ lruTail_ = index;
+ }
+
+ /** Unlink `index` from the LRU list. */
+ void lruRemove_(u32 index) {
+ auto& e = entries_[index];
+ if (e.lruPrev != 0) entries_[e.lruPrev].lruNext = e.lruNext;
+ else lruHead_ = e.lruNext;
+ if (e.lruNext != 0) entries_[e.lruNext].lruPrev = e.lruPrev;
+ else lruTail_ = e.lruPrev;
+ e.lruPrev = 0;
+ e.lruNext = 0;
+ }
+
std::vector<Entry> entries_;
std::vector<u32> freeList_;
std::unordered_map<std::string, u32> pathToId_;
+ usize budget_ = 0; ///< Resident-byte budget (0 = caching disabled)
+ usize residentBytes_ = 0; ///< Sum of bytes of all alive entries (held + evictable)
+ u32 lruHead_ = 0; ///< Oldest evictable entry (next to evict); 0 = empty
+ u32 lruTail_ = 0; ///< Newest evictable entry; 0 = empty
};
} // namespace esengine::resource
diff --git a/tests/resource/test_resource_pool.cpp b/tests/resource/test_resource_pool.cpp
index b75fe9605..e4dec0786 100644
--- a/tests/resource/test_resource_pool.cpp
+++ b/tests/resource/test_resource_pool.cpp
@@ -257,3 +257,96 @@ TEST_CASE("pool_mixed_operations") {
pool.release(h1.id());
CHECK(pool.get(h1) == nullptr);
}
+
+// =============================================================================
+// Eviction budget + LRU (RC6 gap 3): held → evictable → evicted
+// =============================================================================
+
+TEST_CASE("pool_budget_zero_frees_immediately") {
+ // Default (budget 0) is unchanged: refCount 0 → freed at once, not cached.
+ test::DummyPool pool;
+ auto h = pool.add(esengine::makeUnique<test::DummyResource>(1), "a", 100);
+ pool.release(h.id());
+ CHECK_EQ(pool.residentBytes(), 0u);
+ CHECK_EQ(pool.evictableCount(), 0u);
+ CHECK(!pool.findByPath("a").isValid());
+ CHECK(pool.get(h) == nullptr);
+}
+
+TEST_CASE("pool_budget_retains_released_as_evictable_cache") {
+ test::DummyPool pool;
+ pool.setBudget(1000);
+ auto h = pool.add(esengine::makeUnique<test::DummyResource>(7), "a.png", 100);
+ CHECK_EQ(pool.residentBytes(), 100u);
+ pool.release(h.id());
+ // Not freed — retained as an evictable cache entry: still resident + findable.
+ CHECK_EQ(pool.residentBytes(), 100u);
+ CHECK(pool.isEvictable(h));
+ CHECK_EQ(pool.evictableCount(), 1u);
+ CHECK(pool.get(h) == nullptr); // refCount 0 → must revive before use
+ CHECK(pool.findByPath("a.png").isValid()); // but a cache hit can still find it
+}
+
+TEST_CASE("pool_budget_revive_on_cache_hit") {
+ test::DummyPool pool;
+ pool.setBudget(1000);
+ auto h = pool.add(esengine::makeUnique<test::DummyResource>(7), "a.png", 100);
+ pool.release(h.id());
+ CHECK(pool.isEvictable(h));
+
+ auto found = pool.findByPath("a.png");
+ pool.addRef(found); // revive the cached entry
+ CHECK(!pool.isEvictable(h));
+ CHECK_EQ(pool.getRefCount(h), 1u);
+ CHECK(pool.get(h) != nullptr);
+ CHECK_EQ(pool.get(h)->value, 7);
+ CHECK_EQ(pool.evictableCount(), 0u);
+}
+
+TEST_CASE("pool_budget_evicts_oldest_first") {
+ test::DummyPool pool;
+ pool.setBudget(250);
+ auto a = pool.add(esengine::makeUnique<test::DummyResource>(1), "a", 100);
+ auto b = pool.add(esengine::makeUnique<test::DummyResource>(2), "b", 100);
+ auto c = pool.add(esengine::makeUnique<test::DummyResource>(3), "c", 100);
+ CHECK_EQ(pool.residentBytes(), 300u); // all held — allowed to exceed the budget
+
+ pool.release(a.id()); // a evictable; 300 > 250 → evict oldest (a) → 200
+ CHECK_EQ(pool.residentBytes(), 200u);
+ CHECK(pool.get(a) == nullptr);
+ CHECK(!pool.findByPath("a").isValid());
+
+ pool.release(b.id()); // b evictable; 200 ≤ 250 → retained as cache
+ CHECK_EQ(pool.residentBytes(), 200u);
+ CHECK(pool.isEvictable(b));
+ CHECK(pool.findByPath("b").isValid());
+
+ CHECK(pool.get(c) != nullptr); // c still held
+}
+
+TEST_CASE("pool_budget_never_evicts_held") {
+ test::DummyPool pool;
+ pool.setBudget(50); // smaller than even one resource
+ auto a = pool.add(esengine::makeUnique<test::DummyResource>(1), "a", 100);
+ auto b = pool.add(esengine::makeUnique<test::DummyResource>(2), "b", 100);
+ // Both held → never evicted, even though resident far exceeds the budget.
+ CHECK_EQ(pool.residentBytes(), 200u);
+ CHECK_EQ(pool.evictableCount(), 0u);
+ CHECK(pool.get(a) != nullptr);
+ CHECK(pool.get(b) != nullptr);
+}
+
+TEST_CASE("pool_set_budget_evicts_now") {
+ test::DummyPool pool;
+ pool.setBudget(1000);
+ auto a = pool.add(esengine::makeUnique<test::DummyResource>(1), "a", 100);
+ auto b = pool.add(esengine::makeUnique<test::DummyResource>(2), "b", 100);
+ pool.release(a.id());
+ pool.release(b.id());
+ CHECK_EQ(pool.evictableCount(), 2u);
+
+ pool.setBudget(100); // shrink → evict oldest until ≤ 100: a goes, b (100) stays
+ CHECK_EQ(pool.residentBytes(), 100u);
+ CHECK(!pool.findByPath("a").isValid());
+ CHECK(pool.findByPath("b").isValid());
+}