feat multi-index-lru: test with custom allocator, docs update

Tests: протестировано CI

---

Pull Request resolved: #1165

Co-authored-by: antoshkka <antoshkka@userver.tech>
Co-authored-by: antoshkka <antoshkka@userver.tech>
commit_hash:028203cca6622a0bb38e9abcc4a4d94bec97ec77

Author: 2 people

libraries/multi-index-lru/include/userver/multi-index-lru/container.hpp

@@ -24,6 +24,8 @@ class Container {
         : max_size_(max_size)
     {}
 
+    /// @brief Constructs element in-place
+    /// @returns pair<iterator, bool>
     template <typename... Args>
     auto emplace(Args&&... args) {
         auto& seq_index = get_sequenced();
@@ -71,6 +73,7 @@ class Container {
         return get_index<Tag>().find(key);
     }
 
+    /// @brief Returns range of matching elements, updates all
     template <typename Tag, typename Key>
     auto equal_range(const Key& key) {
         auto& primary_index = get_index<Tag>();
@@ -87,6 +90,7 @@ class Container {
         return std::pair{begin, end};
     }
 
+    /// @brief Returns range of matching elements without updates
     template <typename Tag, typename Key>
     auto equal_range_no_update(const Key& key) const {
         return get_index<Tag>().equal_range(key);
@@ -158,6 +162,7 @@ class Container {
         }
     }
 
+    /// @brief Returns end iterator for the specified `Tag` index
     template <typename Tag>
     auto end() const {
         return get_index<Tag>().end();

libraries/multi-index-lru/include/userver/multi-index-lru/expirable_container.hpp

@@ -137,6 +137,7 @@ class ExpirableContainer {
         return impl::IteratorToValue{container_.template end<Tag>()};
     }
 
+    /// @brief Removes all expired items from container
     void cleanup_expired() {
         const auto now = std::chrono::steady_clock::now();
 

libraries/multi-index-lru/src/container_test.cpp

@@ -231,7 +231,78 @@ UTEST_F(ProductsTest, ProductEviction) {
     EXPECT_EQ(cache.find<NameTag>("Mouse"), cache.end<NameTag>());
 }
 
-TEST(Snippet, SimpleUsage) {
+class ProductsTestWithAllocator : public ProductsTest {
+protected:
+    class Counter {
+    public:
+        static std::atomic<size_t> count;
+        static void increment() { count++; }
+        static size_t get() { return count.load(); }
+        static void reset() { count = 0; }
+    };
+
+    template <typename T>
+    class CountingAllocator : public std::allocator<T> {
+    public:
+        CountingAllocator() = default;
+        template <typename U>
+        CountingAllocator(const CountingAllocator<U>&) {}
+
+        T* allocate(size_t n) {
+            Counter::increment();
+            return std::allocator<T>::allocate(n);
+        }
+
+        static size_t get_count() { return Counter::get(); }
+        static void reset_count() { Counter::reset(); }
+
+        template <typename U>
+        struct rebind {  // NOLINT(readability-identifier-naming)
+            using other = CountingAllocator<U>;
+        };
+    };
+
+    using ProductCache = multi_index_lru::Container<
+        Product,
+        boost::multi_index::indexed_by<
+            boost::multi_index::ordered_unique<
+                boost::multi_index::tag<SkuTag>,
+                boost::multi_index::member<Product, std::string, &Product::sku>>,
+            boost::multi_index::ordered_unique<
+                boost::multi_index::tag<NameTag>,
+                boost::multi_index::member<Product, std::string, &Product::name>>>,
+        CountingAllocator<Product>>;
+};
+
+std::atomic<size_t> ProductsTestWithAllocator::Counter::count{0};
+
+UTEST_F(ProductsTestWithAllocator, AllocationsCheck) {
+    ProductCache cache(20);
+
+    for (int i = 0; i < 1000; ++i) {
+        cache.insert(Product{"A" + std::to_string(i), "Laptop_" + std::to_string(i), 999.99});
+    }
+    const auto first_allocations_count = ProductsTestWithAllocator::CountingAllocator<int>::get_count();
+
+    cache.clear();
+    for (int i = 0; i < 1000; ++i) {
+        cache.insert(Product{"A" + std::to_string(i), "Laptop_" + std::to_string(i), 999.99});
+    }
+
+    // no extra allocations since nodes are being reused
+    EXPECT_EQ(first_allocations_count, ProductsTestWithAllocator::CountingAllocator<int>::get_count());
+
+    cache.insert(Product{"B_0", "C_0", 999.99});
+    cache.erase(cache.find<NameTag>("C_0"));
+    cache.insert(Product{"B_1", "C_1", 999.99});
+    cache.erase(cache.find<SkuTag>("B_1"));
+    cache.insert(Product{"B_2", "C_2", 999.99});
+
+    // no extra allocations since nodes are being reused
+    EXPECT_EQ(first_allocations_count, ProductsTestWithAllocator::CountingAllocator<int>::get_count());
+}
+
+UTEST(Snippet, SimpleUsage) {
     struct MyValueT {
         std::string key;
         int val;

scripts/docs/en/userver/libraries/multi_index_lru.md

@@ -1,12 +1,29 @@
 # MultiIndex LRU Container
 
-## Introduction
-
 Generic LRU (Least Recently Used) cache container implementation that combines Boost.MultiIndex for flexible indexing
-for efficient LRU tracking. It uses @ref multi_index_lru.
+with efficient LRU tracking. The container maintains elements in access order while supporting multiple indexing
+strategies through Boost.MultiIndex. The LRU eviction policy automatically removes the least recently accessed items
+when capacity is reached.
+
+Two container variants are provided:
+- **Container** - Basic LRU cache with capacity management
+- **ExpirableContainer** - Extended version with time-based expiration (TTL)
+
+## MultiIndex LRU Implementation Notes
+
+### MultiIndex LRU Node Reuse Strategy
+The container maintains a free list of allocated nodes to reduce memory allocations. When items are evicted or erased,
+their nodes are moved to the free list and reused for future insertions.
+
+### MultiIndex LRU Thread Safety
+This container is **not thread-safe**. External synchronization is required for concurrent access.
+
+### MultiIndex LRU Iterator Invalidation
+- Insertions may invalidate iterators if capacity is exceeded and eviction occurs
+- Erasures invalidate iterators to the erased element only
+- Find operations do not invalidate iterators
+- `set_capacity()` may invalidate iterators when reducing capacity
 
-The container maintains elements in access order while supporting multiple indexing strategies through Boost.MultiIndex.
- The LRU eviction policy automatically removes the least recently accessed items when capacity is reached.
 
 ## Usage