Blender V5.3
cache_limiter.h
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2025 Blender Foundation
2 *
3 * SPDX-License-Identifier: Apache-2.0 */
4
5#pragma once
6
7#include <functional>
8#include <list>
9#include <memory>
10#include <mutex>
11
13
14/* Cache limiter
15 *
16 * System to ensure a number of cached resources do not exceed a specified maximum number of
17 * items. Cached handles hold a reference to the resources, and the limiter will delete
18 * resources if the maximum is exceeded and there no current users of the resource. */
19
20template<typename T> class CacheLimiter;
21template<typename T> class CacheHandleGuard;
22
23/* Cache Handle
24 *
25 * Holds a reference to cached resource, which may get deleted if the maximum number
26 * of items is exceeded. */
27template<typename T> class CacheHandle {
28 public:
30 const std::function<std::unique_ptr<T>()> &creator)
31 {
32 {
33 std::scoped_lock lock(internal_mutex_);
34 if (!internal_) {
35 internal_ = std::make_shared<Internal>(limiter);
36 }
37 }
38 return internal_->acquire(creator);
39 }
40
41 private:
42 friend class CacheLimiter<T>;
43 friend class CacheHandleGuard<T>;
44
45 class Internal : public std::enable_shared_from_this<Internal> {
46 public:
47 explicit Internal(CacheLimiter<T> &limiter) : limiter_(limiter) {}
48
49 ~Internal()
50 {
51 limiter_.unregister(this);
52 delete_resource();
53 }
54
55 CacheHandleGuard<T> acquire(std::function<std::unique_ptr<T>()> creator)
56 {
57 limiter_.register_and_add_guard(*this);
58
59 std::lock_guard<std::mutex> lock(resource_mutex_);
60 if (!resource_) {
61 resource_ = creator();
62 }
63 return CacheHandleGuard<T>(*this);
64 }
65
66 void delete_resource()
67 {
68 std::lock_guard<std::mutex> lock(resource_mutex_);
69 resource_.reset();
70 }
71
72 CacheLimiter<T> &limiter_;
73 std::unique_ptr<T> resource_;
74 std::mutex resource_mutex_;
75
76 int guard_count_ = 0;
77 bool in_lru_list_ = false;
78 typename std::list<typename CacheHandle<T>::Internal *>::iterator lru_iterator_;
79 };
80
81 /* Shared pointer for lifetime extension in cache eviction. */
82 std::mutex internal_mutex_;
83 std::shared_ptr<Internal> internal_;
84};
85
86/* Cache Handle Guard
87 *
88 * Ensures a cache resource is not deleted as long as it exists. This is meant to
89 * be used as a temporary object on the stack to keep the resource alive while using
90 * it. A CacheHandleGuard should not outlive the CacheHandle it was created from. */
91template<typename T> class CacheHandleGuard {
92 public:
93 CacheHandleGuard() = default;
95 {
96 handle_.limiter_.remove_guard(handle_);
97 }
98
101
104
105 const std::unique_ptr<T> &get() const
106 {
107 return handle_.resource_;
108 }
109
110 private:
111 friend class CacheHandle<T>;
112 CacheHandleGuard(typename CacheHandle<T>::Internal &source) : handle_(source) {}
113
114 typename CacheHandle<T>::Internal &handle_;
115};
116
117/* Cache limiter
118 *
119 * Cache handles are registered with this global limiter. */
120template<typename T> class CacheLimiter {
121 public:
122 explicit CacheLimiter(size_t max_items) : max_items_(max_items) {}
123
124 CacheLimiter(const CacheLimiter &) = delete;
126
127 private:
128 friend class CacheHandle<T>;
129 friend class CacheHandleGuard<T>;
130
131 /* When handle is deleted. */
132 void unregister(typename CacheHandle<T>::Internal *handle)
133 {
134 std::lock_guard<std::mutex> lock(mutex_);
135 if (handle->in_lru_list_) {
136 lru_list_.erase(handle->lru_iterator_);
137 handle->in_lru_list_ = false;
138 }
139 }
140
141 /* When handle guard is acquired. */
142 void register_and_add_guard(typename CacheHandle<T>::Internal &handle)
143 {
144 std::unique_lock<std::mutex> lock(mutex_);
145
146 /* (Re)insert handle at the front of the LRU list. */
147 handle.guard_count_++;
148 if (handle.in_lru_list_) {
149 lru_list_.erase(handle.lru_iterator_);
150 }
151 lru_list_.push_front(&handle);
152 handle.lru_iterator_ = lru_list_.begin();
153 handle.in_lru_list_ = true;
154
155 /* Evict other handles if needed. */
156 while (lru_list_.size() > max_items_) {
157 typename CacheHandle<T>::Internal *handle_to_evict = nullptr;
158
159 /* From the back of the LRU list, find an item with no users. */
160 auto it = lru_list_.rbegin();
161 while (it != lru_list_.rend()) {
162 typename CacheHandle<T>::Internal *candidate = *it;
163 if (candidate->guard_count_ <= 0) {
164 handle_to_evict = candidate;
165 break;
166 }
167 ++it;
168 }
169
170 if (!handle_to_evict) {
171 break;
172 }
173
174 lru_list_.erase(handle_to_evict->lru_iterator_);
175 handle_to_evict->in_lru_list_ = false;
176
177 /* Get a shared pointer to ensure this does not get deleted
178 * before we have unloaded the resource. */
179 auto handle_to_evict_ptr = handle_to_evict->shared_from_this();
180
181 lock.unlock();
182
183 /* Unload resource while unlocked, to avoid holding lock
184 * too long if deletion is expensive. */
185 handle_to_evict_ptr->delete_resource();
186 handle_to_evict_ptr.reset();
187
188 lock.lock();
189 }
190 }
191
192 /* When handle guard is deleted. */
193 void remove_guard(typename CacheHandle<T>::Internal &handle)
194 {
195 std::lock_guard<std::mutex> lock(mutex_);
196 handle.guard_count_--;
197 }
198
199 size_t max_items_;
200 std::mutex mutex_;
201 std::list<typename CacheHandle<T>::Internal *> lru_list_;
202};
203
volatile int lock
CacheHandleGuard(CacheHandleGuard &&other)=delete
const std::unique_ptr< T > & get() const
CacheHandleGuard(const CacheHandleGuard &)=delete
CacheHandleGuard & operator=(const CacheHandleGuard &)=delete
CacheHandleGuard()=default
CacheHandleGuard & operator=(CacheHandleGuard &&other)=delete
friend class CacheLimiter< T >
CacheHandleGuard< T > acquire(CacheLimiter< T > &limiter, const std::function< std::unique_ptr< T >()> &creator)
friend class CacheHandleGuard< T >
CacheLimiter(const CacheLimiter &)=delete
CacheLimiter(size_t max_items)
CacheLimiter & operator=(const CacheLimiter &)=delete
#define CCL_NAMESPACE_END
#define T