Initial Commit

Author: influentcoder

.gitignore

@@ -0,0 +1,2 @@
+build/
+googletest/

.vscode/settings.json

@@ -0,0 +1,66 @@
+{
+    "C_Cpp.default.configurationProvider": "ms-vscode.cmake-tools",
+    "files.associations": {
+        "list": "cpp",
+        "any": "cpp",
+        "array": "cpp",
+        "atomic": "cpp",
+        "*.tcc": "cpp",
+        "cctype": "cpp",
+        "chrono": "cpp",
+        "clocale": "cpp",
+        "cmath": "cpp",
+        "cstdarg": "cpp",
+        "cstddef": "cpp",
+        "cstdint": "cpp",
+        "cstdio": "cpp",
+        "cstdlib": "cpp",
+        "ctime": "cpp",
+        "cwchar": "cpp",
+        "cwctype": "cpp",
+        "deque": "cpp",
+        "forward_list": "cpp",
+        "unordered_map": "cpp",
+        "unordered_set": "cpp",
+        "vector": "cpp",
+        "exception": "cpp",
+        "algorithm": "cpp",
+        "functional": "cpp",
+        "iterator": "cpp",
+        "map": "cpp",
+        "memory": "cpp",
+        "memory_resource": "cpp",
+        "numeric": "cpp",
+        "optional": "cpp",
+        "random": "cpp",
+        "ratio": "cpp",
+        "set": "cpp",
+        "string": "cpp",
+        "string_view": "cpp",
+        "system_error": "cpp",
+        "tuple": "cpp",
+        "type_traits": "cpp",
+        "utility": "cpp",
+        "fstream": "cpp",
+        "initializer_list": "cpp",
+        "iomanip": "cpp",
+        "iosfwd": "cpp",
+        "iostream": "cpp",
+        "istream": "cpp",
+        "limits": "cpp",
+        "new": "cpp",
+        "ostream": "cpp",
+        "sstream": "cpp",
+        "stdexcept": "cpp",
+        "streambuf": "cpp",
+        "cinttypes": "cpp",
+        "typeinfo": "cpp",
+        "variant": "cpp",
+        "bit": "cpp",
+        "cstring": "cpp",
+        "bitset": "cpp",
+        "complex": "cpp",
+        "typeindex": "cpp"
+    },
+    "cmake.configureOnOpen": true
+}

CMakeLists.txt

@@ -0,0 +1,21 @@
+cmake_minimum_required(VERSION 3.16)
+
+set(This ExpiringLRUCache)
+
+project(${This} C CXX)
+
+set(CMAKE_C_STANDARD 11)
+set(CMAKE_CXX_STANDARD 17)
+
+add_subdirectory(googletest)
+
+enable_testing()
+
+set(Headers
+    ExpiringLRUCache.hpp
+)
+
+add_library(${This} STATIC ${Headers})
+
+add_subdirectory(examples)
+add_subdirectory(tests)

ExpiringLRUCache.hpp

@@ -0,0 +1,150 @@
+#ifndef EXPIRING_LRU_CACHE_HPP
+#define EXPIRING_LRU_CACHE_HPP 1
+
+#include <list>
+#include <unordered_map>
+#include <chrono>
+
+/**
+ * @brief A container built on top of unordered_map and list to implement a LRU cache.
+ * After a certain time, the elements of the cache expire and are lazily evicted from
+ * the cache.
+ * 
+ * @tparam K Type of key objects.
+ * @tparam V Type of mapped values.
+ */
+template <class K, class V>
+class ExpiringLruCache
+{
+    using clock_t = std::chrono::steady_clock;
+    using time_point_t = clock_t::time_point;
+
+    using listk_t = typename std::list<K>;
+    using list_it_t = typename listk_t::iterator;
+    using tuple_t = typename std::tuple<V, list_it_t, time_point_t>;
+    using mapkpairkv_t = typename std::unordered_map<K, typename std::tuple<V, list_it_t, time_point_t>>;
+
+public:
+
+    using iterator = typename mapkpairkv_t::iterator;
+    using const_iterator = typename mapkpairkv_t::const_iterator;
+    
+    /**
+     * Build a cache with a given capacity and TTL (time-to-live).
+     * @param capacity The capacity of the cache. When the cache size reaches capicity,
+     * and a new element is inserted, the least used element will be evicted from the
+     * cache.
+     * @param ttl Time-to-live for the elements in the cache, in seconds.
+     */
+    ExpiringLruCache(size_t capacity, unsigned int ttl) : m_capacity(capacity) {
+        m_ttl = std::chrono::seconds(ttl);
+    }
+
+    /**
+     * Get an iterator, where the first element points to a key and the second element
+     * points to a tuple. The tuple is composed of three elements:
+     * 0. The value associated to the key.
+     * 1. The underlying list iterator.
+     * 2. The time point which represents the time the element was created.
+     */
+    iterator find(const K &key)
+    {
+        using std::chrono::duration_cast;
+        using std::chrono::seconds;
+
+        const auto it = m_cache.find(key);
+        if (it != m_cache.end())
+        {
+            if (duration_cast<seconds>(clock_t::now() - std::get<2>(it->second)).count() > m_ttl.count())
+            {
+                m_used.erase(std::get<1>(it->second));
+                m_cache.erase(it);
+                return m_cache.end();
+            }
+
+            touch(it);
+        }
+        return it;
+    }
+
+    /**
+     * Returns a reference to the mapped value of the element with key k in the LRU
+     * cache.
+     * 
+     * If k does not match the key of any element in the container, the function throws
+     * an out_of_range exception.
+     */
+    V& at(const K &key)
+    {
+        const auto it = find(key);
+        if (it == m_cache.end())
+        {
+            throw std::out_of_range("Out of range");
+        }
+
+        return std::get<0>(it->second);
+    }
+
+    /**
+     * Returns an iterator pointing to the past-the-end element in the container.
+     */
+    const_iterator end() const
+    {
+        return m_cache.end();
+    }
+
+    /**
+     * Insert a new elements in the LRU cache. Unlike the unordered_map emplace(), if
+     * the key already exists, the value will be replaced with the provided value.
+     */
+    void emplace(const K &key, const V &value)
+    {
+        const auto it = m_cache.find(key);
+        if (it != m_cache.end())
+        {
+            touch(it);
+        }
+        else
+        {
+            if (m_cache.size() == m_capacity)
+            {
+                m_cache.erase(m_used.back());
+                m_used.pop_back();
+            }
+            m_used.push_front(key);
+        }
+        m_cache[key] = {value, m_used.begin(), clock_t::now()};
+    }
+
+    /**
+     * Returns the number of elements in the LRU cache container.
+     */
+    size_t size()
+    {
+        return m_cache.size();
+    }
+
+    /**
+     * Size of the underlying list, use for testing purposes only.
+     */
+    size_t _listSize()
+    {
+        return m_used.size();
+    }
+
+private:
+    void touch(const iterator &it)
+    {
+        // We use splice instead of erase()/push_front() to avoid an unnecessary copy.
+        m_used.splice(m_used.begin(), m_used, std::get<1>(it->second));
+        std::get<1>(it->second) = m_used.begin();
+        std::get<2>(it->second) = clock_t::now();
+    }
+
+    mapkpairkv_t m_cache;
+    listk_t m_used;
+    size_t m_capacity;
+    std::chrono::duration<int64_t> m_ttl;
+};
+
+#endif /* EXPIRING_LRU_CACHE_HPP */

LICENSE.md

@@ -0,0 +1,13 @@
+Copyright [2020-present] [Guillaume Jean-Philippe Humbert]
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

README.md

@@ -0,0 +1,89 @@
+# High Performance LRU Cache With Expiring Elements
+
+This is very similar to a traditional LRU cache, with the additional feature that
+elements expire after a certain determined time.
+
+If we try to get an element which has passed its time-to-live (TTL), it won't be
+considered found and will be evicted from the cache.
+
+# Sample Usage
+
+See the examples folder:
+
+```cpp
+#include <iostream>
+#include <string>
+#include <unistd.h>
+#include "../ExpiringLRUCache.hpp"
+
+int main()
+{
+    using Cache = ExpiringLruCache<int, std::string>;
+
+    size_t capacity = 2;
+    unsigned int timeToLiveInSeconds = 3;
+
+    Cache cache(capacity, timeToLiveInSeconds);
+
+    cache.emplace(1, "a");
+    cache.emplace(2, "b");
+
+    std::cout << cache.at(1) << std::endl; // prints "a"
+    std::cout << cache.at(2) << std::endl; // prints "b"
+
+    // The find() method returns an iterator, on which the first element is the key and
+    // the second element is a tuple of three elements:
+    // 0. The value
+    // 1. A list iterator on the keys
+    // 2. A chrono time point which represents the time when the element was created or
+    //    last accessed.
+    std::cout << std::get<0>(cache.find(1)->second) << std::endl; // prints "a"
+    std::cout << std::get<0>(cache.find(2)->second) << std::endl; // prints "b"
+
+    sleep(2);
+    // Refresh the timestamp.
+    cache.at(1);
+
+    sleep(2);
+    std::cout << cache.at(1) << std::endl; // prints "a"
+    // prints 1 (true), as the element was evicted due to being outdated
+    std::cout << (cache.find(2) == cache.end()) << std::endl;
+
+    std::unordered_map<int, int> map;
+    map.emplace(1, 10);
+    map.emplace(1, 11);
+    std::cout << map.at(1) << std::endl;
+
+    return 0;
+}
+```
+
+# Build the example
+
+```bash
+$ mkdir build
+$ cd build
+$ cmake ..
+$ cmake --build . --target Example
+```
+
+To run it:
+
+```bash
+$ ./examples/Example
+```
+
+# Build the tests
+
+```bash
+$ mkdir build
+$ cd build
+$ cmake ..
+$ cmake --build . --target ExpiringLRUCacheTests
+```
+
+Run the tests:
+
+```
+$ ctest -T test --output-on-failure
+```

examples/CMakeLists.txt

@@ -0,0 +1,16 @@
+cmake_minimum_required(VERSION 3.16)
+
+set(This Example)
+
+set(Sources
+    Example.cpp
+)
+
+# Needed as the library provides only a ".hpp" file which is not automatically
+# recognized by cmake.
+set_target_properties(ExpiringLRUCache PROPERTIES LINKER_LANGUAGE CXX)
+
+add_executable(${This} ${Sources})
+target_link_libraries(${This} PUBLIC
+    ExpiringLRUCache
+)