{"id":20602331,"url":"https://github.com/jbaldwin/libcappuccino","last_synced_at":"2025-04-15T01:54:25.898Z","repository":{"id":50198620,"uuid":"176630239","full_name":"jbaldwin/libcappuccino","owner":"jbaldwin","description":"C++17 Cache Data Structure Library","archived":false,"fork":false,"pushed_at":"2023-11-25T22:26:27.000Z","size":527,"stargazers_count":25,"open_issues_count":1,"forks_count":10,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-15T01:54:20.314Z","etag":null,"topics":["cache","cpp","cpp17","cpp17-library","lru","modern-cpp"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jbaldwin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-03-20T01:46:18.000Z","updated_at":"2025-02-20T03:21:00.000Z","dependencies_parsed_at":"2023-11-25T19:23:56.503Z","dependency_job_id":"a4b03426-97f8-4e28-bc19-00bc4f4ee9c6","html_url":"https://github.com/jbaldwin/libcappuccino","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbaldwin%2Flibcappuccino","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbaldwin%2Flibcappuccino/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbaldwin%2Flibcappuccino/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jbaldwin%2Flibcappuccino/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jbaldwin","download_url":"https://codeload.github.com/jbaldwin/libcappuccino/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248991540,"owners_count":21194894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cache","cpp","cpp17","cpp17-library","lru","modern-cpp"],"created_at":"2024-11-16T09:13:32.401Z","updated_at":"2025-04-15T01:54:25.882Z","avatar_url":"https://github.com/jbaldwin.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# libcappuccino - C++17 Cache and Associative Data Structure Library\n\n[![build](https://github.com/jbaldwin/libcappuccino/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/jbaldwin/libcappuccino/actions/workflows/ci.yml)\n[![Coverage Status](https://coveralls.io/repos/github/jbaldwin/libcappuccino/badge.svg?branch=main)](https://coveralls.io/github/jbaldwin/libcappuccino?branch=main)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/8ecca4da783a437eba8c62964fed59ba)](https://www.codacy.com/gh/jbaldwin/libcappuccino/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=jbaldwin/libcappuccino\u0026amp;utm_campaign=Badge_Grade)\n[![language][badge.language]][language]\n[![license][badge.license]][license]\n\nhttps://github.com/jbaldwin/libcappuccino\n\n**libcappuccino** is licensed under the Apache 2.0 license.\n\n## Overview\n* Thread safe cache and associative datastructures.\n  * Can disable thread safety for singly threaded apps via `thread_safe::no`.\n* The following eviction policies are currently supported:\n  * Cache (Fixed size contiguous memory).\n    * First in first out (FIFO).\n    * Least frequently used (LFU).\n    * Least frequently used with dynamic aging (LFUDA).\n    * Least recently used (LRU).\n    * Most recently used (MRU).\n    * Random Replacement (RR).\n    * Time aware least recently used (TLRU).\n    * Uniform time aware least recently used (UTLRU).\n  * Associative (Dynamic size non-contiguous memory).\n    * Uniform time aware set (UTSET).\n    * Uniform time aware map (UTMAP).\n\n## Usage\n\n### Examples\n\nSee all of the examples under the examples/ directory.  Below are some simple examples\nto get your started on using libcappuccino.\n\n#### Indivudal item TTL Least Recently Used Example\nThis example provides a individual item TTL LRU cache.  This means each item placed in the cache\ncan have its own TTL value and the eviction policy is TTL expired first and then LRU second.  This cache\nis useful when items should have various TTLs applied to them.  Use the Uniform TTL LRU if every item\nhas the same TTL as it is more efficient on CPU and memory usage.  This type of cache could be compared\nto the likes of how Redis/Memcached work but in memory of the application rather than a separate\nprocess.\n\n```C++\n    #include \u003ccappuccino/cappuccino.hpp\u003e\n    \n    #include \u003cchrono\u003e\n    #include \u003ciostream\u003e\n    \n    int main()\n    {\n        using namespace std::chrono_literals;\n    \n        // Create a cache with up to 3 items.\n        cappuccino::tlru_cache\u003cuint64_t, std::string\u003e cache{3};\n    \n        // Insert \"hello\", \"world\" with different TTLs.\n        cache.insert(1h, 1, \"Hello\");\n        cache.insert(2h, 2, \"World\");\n    \n        // Insert a third value to fill the cache.\n        cache.insert(3h, 3, \"nope\");\n    \n        {\n            // Grab hello and world, this update their LRU positions.\n            auto hello = cache.find(1);\n            auto world = cache.find(2);\n    \n            std::cout \u003c\u003c hello.value() \u003c\u003c \", \" \u003c\u003c world.value() \u003c\u003c \"!\" \u003c\u003c std::endl;\n        }\n    \n        // Insert \"hola\", this will replace \"nope\" since its the oldest lru item,\n        // nothing has expired at this time.\n        cache.insert(30min, 4, \"Hola\");\n    \n        {\n            auto hola  = cache.find(4); // \"hola\" was just inserted, it will be found\n            auto hello = cache.find(1); // \"hello\" will also have a value, it is at the end of the lru list\n            auto world = cache.find(2); // \"world\" is in the middle of our 3 lru list.\n            auto nope  = cache.find(3); // \"nope\" was lru'ed when \"hola\" was inserted\n                                        // since \"hello\" and \"world were fetched\n    \n            if (hola.has_value())\n            {\n                std::cout \u003c\u003c hola.value() \u003c\u003c \"\\n\";\n            }\n    \n            if (hello.has_value())\n            {\n                std::cout \u003c\u003c hello.value() \u003c\u003c \"\\n\";\n            }\n    \n            if (world.has_value())\n            {\n                std::cout \u003c\u003c world.value() \u003c\u003c \"\\n\";\n            }\n    \n            if (!nope.has_value())\n            {\n                std::cout \u003c\u003c \"Nope was LRU'ed out of the cache.\\n\";\n            }\n        }\n    \n        return 0;\n    }\n```\n\n##### Insert, Update, Insert Or Update\nEach `insert()` method on the various caches takes an optional parameter `allow` that tells the cache\nhow the insert call should behave.  By default this parameter is set to allow `insert_or_update` on the\nelements being inserted into the cache.  This means if they do not exist in the cache they will be added\nand if they do exists the values will be udpated and any metadata like TTLs will be adjusted/reset.  The\ncaller can also specify this parameter as just `insert` to only allow the item to be added if it doesn't\nalready exist or as `update` to only change the item in the cahce if it already exists.\n\n```C++\n    #include \u003ccappuccino/cappuccino.hpp\u003e\n    \n    int main()\n    {\n        using namespace std::chrono_literals;\n        using namespace cappuccino;\n        // Uniform TTL LRU cache with a 1 hour TTL and 200 element cache capacity.\n        // The key is uint64_t and the value is std::string.\n        utlru_cache\u003cuint64_t, std::string\u003e cache{1h, 200};\n    \n        cache.insert(1, \"Hello\", allow::insert); // OK\n        cache.insert(1, \"Hello\", allow::insert); // ERROR! already exists\n    \n        // Note that allow::insert can succeed if the item is TTLed out\n        // in certain types of caches that support TTLs.\n    \n        cache.insert(1, \"Hola\", allow::update);  // OK exists\n        cache.insert(2, \"World\", allow::update); // ERROR! doesn't exist\n    \n        cache.insert(2, \"World\"); // OK, parameter defaults to allow::insert_or_update\n        return 0;\n    }\n```\n\n### Requirements\n    C++17 compiler (g++/clang++)\n    CMake\n    make and/or ninja\n\n### Instructions\n\n#### Building\n    # This will produce a shared and static library to link against your project.\n    mkdir Release \u0026\u0026 cd Release\n    cmake -DCMAKE_BUILD_TYPE=Release ..\n    cmake --build .\n\n#### CMake Projects\n\n##### add_subdirectory()\nTo use within your cmake project you can clone the project or use git submodules and then `add_subdirectory` in the parent project's `CMakeList.txt`,\nassuming the cappuccino code is in a `libcappuccino/` subdirectory of the parent project:\n\n```bash\n    add_subdirectory(libcappuccino)\n```\n\nTo link to the `\u003cproject_name\u003e` then use the following:\n\n    add_executable(\u003cproject_name\u003e main.cpp)\n    target_link_libraries(\u003cproject_name\u003e PRIVATE cappuccino)\n\nInclude cappuccino in the project's code by simply including `#include \u003ccappuccino/Cappuccino.hpp\u003e` as needed.\n\n##### FetchContent\nCMake can also include the project directly via a `FetchContent` declaration.  In your project's `CMakeLists.txt`\ninclude the following code to download the git repository and make it available to link to.\n\n```bash\n    cmake_minimum_required(VERSION 3.11)\n    \n    # ... cmake project stuff ...\n    \n    include(FetchContent)\n    FetchContent_Declare(\n        cappuccino\n        GIT_REPOSITORY https://github.com/jbaldwin/libcappuccino.git\n        GIT_TAG        \u003cTAG_OR_GIT_HASH\u003e\n    )\n    FetchContent_MakeAvailable(cappuccino)\n    \n    # ... cmake project more stuff ...\n    \n    target_link_libraries(${PROJECT_NAME} PRIVATE cappuccino)\n```\n\n### Contributing and Testing\n\nThis project has a GitHub Actions CI implementation to compile and run unit tests.\n\nCurrently tested distros:\n*   ubuntu:latest\n*   fedora:latest\n*   msvc:latest\n\nCurrently tested compilers:\n*   g++\n*   clang\n*   msvc\n\nContributing a new feature should include relevant tests.  Examples\nare welcome if understanding how the feature works is difficult or provides some additional value the tests otherwise cannot.\n\nCMake is setup to understand how to run the tests.  Building and then running `ctest` will\nexecute the tests locally.\n\n```bash\nmkdir Release \u0026\u0026 cd Release\ncmake -DCMAKE_BUILD_TYPE=Release ..\ncmake --build .\nctest -VV\n```\n\n### Support\n\nFile bug reports, feature requests and questions using [GitHub Issues](https://github.com/jbaldwin/libcappuccino/issues)\n\nCopyright © 2017-2023, Josh Baldwin\n\n[badge.language]: https://img.shields.io/badge/language-C%2B%2B17-yellow.svg\n[badge.license]: https://img.shields.io/badge/license-Apache--2.0-blue\n\n[language]: https://en.wikipedia.org/wiki/C%2B%2B17\n[license]: https://en.wikipedia.org/wiki/Apache_License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbaldwin%2Flibcappuccino","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjbaldwin%2Flibcappuccino","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjbaldwin%2Flibcappuccino/lists"}