{"id":23505757,"url":"https://github.com/akashihi/stlcache","last_synced_at":"2025-04-16T01:01:24.922Z","repository":{"id":152312601,"uuid":"1488926","full_name":"akashihi/stlcache","owner":"akashihi","description":"STL-based caches for C++","archived":false,"fork":false,"pushed_at":"2023-05-31T16:39:05.000Z","size":231,"stargazers_count":115,"open_issues_count":2,"forks_count":32,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-29T03:21:19.286Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/akashihi.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":"LICENSE_1_0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-03-16T20:46:14.000Z","updated_at":"2024-12-11T11:24:40.000Z","dependencies_parsed_at":"2024-12-25T09:40:32.551Z","dependency_job_id":"5a91bc46-02ad-4d1e-8a1e-11f16ad017af","html_url":"https://github.com/akashihi/stlcache","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akashihi%2Fstlcache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akashihi%2Fstlcache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akashihi%2Fstlcache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akashihi%2Fstlcache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akashihi","download_url":"https://codeload.github.com/akashihi/stlcache/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249178209,"owners_count":21225349,"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":["hacktoberfest"],"created_at":"2024-12-25T09:39:50.209Z","updated_at":"2025-04-16T01:01:24.908Z","avatar_url":"https://github.com/akashihi.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"STL::Cache - in-memory cache for C++ applications\n\nIntroduction:\n\n   STL::Cache is just a simple wrapper over standard map, that implements\n   some cache algorithms, thus allowing you to limit the storage size and\n   automatically remove unused items from it. (Right now the std::map\n   interface is partially implemented, so it can't be used as a drop-in\n   replacement for the std::map).\n\n   It is intended to be used for keeping any key/value data, especially\n   when data's size are too big, to just put it into the map and keep the\n   whole thing. With STL::Cache you could put enormous (really unlimited)\n   amount of data into it, but it will store only some small part of your\n   data. So re-usable data will be kept near your code and not so popular\n   data will not spend expensive memory.\n\n   STL::Cache uses configurable policies, for decisions, whether data are\n   good, to be kept in cache or they should be thrown away. It is shipped\n   with 8 policies and you are free to implement your own.\n\nGetting and installing:\n\n   The STL::Cache source code is hosted on github, so you can download\n   the source code using wget or other download tool:\n     * https://github.com/akashihi/stlcache/tarball/master (tar.gz\n       format)\n     * https://github.com/akashihi/stlcache/zipball/master (or zip\n       format)\n\n   You could also clone the repository:\n     git clone git://github.com/akashihi/stlcache.git\n\n   Current development code is available at 'master' branch and (more) stable releases have been tagged.\n\n   The STL::Cache is header only and does not require any building. Recommended way of using it is by CMake integration:\n\n        Include(FetchContent)\n        FetchContent_Declare(\n            STLCache\n            GIT_REPOSITORY git://github.com/akashihi/stlcache.git\n            GIT_TAG v0.4\n        )\n        FetchContent_MakeAvailable(STLCache)\n        add_executable(test test.cpp)\n        target_link_libraries(test PRIVATE STLCache)\n\n   Alternatively just get the sources and add 'include' directory to your project's include directories list.\n\n   As i told you, the STL::Cache itself is a header-only library\n   and doesn't requires building. Indeed, it is shipped with tests,\n   documentation and other stuff, that could be built and used. For\n   STL::Cache building you need:\n     * Recent CMake (required)\n     * Boost library (optional)\n     * Doxygen (optional, only for documentation processing)\n\n   After getting this stuff up and running, select a directory for\n   building and issue the following commands:\n        cmake /path/to/the/stlcache/sources\n        make\n        make test\n        make doc\n        make install\n\n   The CMake is using a out-of-source build approach, so it is\n   recommended to create a temporary build directory somewhere and remove\n   it after installation.\n\n   The generated documentation will be put into the \u003cbuild\u003e/doc directory\n   and tests will be built and run directly in the \u003cbuild\u003e directory. They\n   are NOT installed by 'make install' command, so you have to copy them\n   manually, if you really need them.\n\nUsage:\n\n   Select a cache expiration policy , configure cache with it,\n   construct the cache, specifying it's size, and start putting data into\n   the cache:\n     typedef CacheLRU stlcache::cache\u003cint,string,stlcache::policy_lru\u003e;\n     CacheLRU myCache(10);\n\n   The policy, key data type and value data type are passed as parameters\n   to the stlcache::cache class template. In the example above we have\n   constructed cache, that keeps data of type std::string and keys are of\n   type int. It uses a LRU policy for removal of excessive items.\n   Cache object 'myCache' is able to keep only 10 items. Cache size is\n   configured at the construction time and cannot be changed in the future\n   (with exceptions for assignment and swap operations). Additionally you\n   could specify a comparison object and allocator type, see the\n   cache class documentation for the details.\n\n   You could put objects into your cache object using insert call:\n     myCache.insert(1,\"One)\";\n\n   Note, that the insert call could throw a cache full exception\n   or invalid key exception, As keys have to be unique, the insert call\n   may do nothing, if it meets the duplicate key. Don't forget to check\n   it's return value.\n\n   If you are not sure, whether you have element in the cache or not, \n   you can use a safe insert_or_assign call, that will either add new element \n   to the cache or update exiting one with the new value.\n\n   Now, when you have some data in the cache, you may want to retrieve it\n   back:\n     string myOne = myCache.fetch(1);\n\n   The fetch call will return a data value, associated with the\n   supplied key or throw the invalid key exception when the key\n   doesn't exists in the cache. For safier operations, you could check\n   in advance, whether key is in the cache or not:\n     string myOne;\n     if (myCache.check(1)) {\n       myOne = myCache.fetch(1);\n     }\n\n   The check is exception-safe.\n\n   Both check and fetch calls are increasing internal reference\n   count for the key, so, depending on the used policy, it will increase\n   or decrease the entry's chance to become an expiration victim. Under\n   some circumstances you may need to manually change those reference\n   counter, without actually accesing the entry. Something like\n   touching it:\n     myCache.touch(1);\n\n   The cache::touch call is exception-safe and could be used even on\n   non-existent keys.\n\n   When you have done your work, you may manually delete the entry:\n     myCache.erase(1);\n\n   Check it's return value, to get sure, whether something was deleted or\n   not.\n\nThread safety:\n\n    cache can be configured with different locking implementations, thus implementing thread safety. By default a non-locking approach is used and cache is not thread-safe, allowing user to implement external locking. STL::Cache is shipped with the following locking implementations:\n\n        * non-locking - No locking will be done with that implementation, leaving cache non thread-safe. Class name is lock_none\n        * exclusive locking - cache will be locked exclusively on almost every call, thus limiting parallel usage to a single thread. Class name is lock_exclusive\n        * shared locking - Some calls will be allowed to be run in parallel with this policy. But, due to nature of the cache , even operations, that seems to be non-modifying, require exclusive lock to \n          update access tracking data. Class name is lock_shared\nThe locking implementation must be specified as a last parameter of cache type and it is optional.\n\nBoost integration\n    Since version 0.3 stlcache includes Boost specific multi-map based LFU policy: lfu_multi_index\n\n    lfu_multi_index implementes LFU algorithm using a Boost MultiIndex map, which is more slower, but uses less RAM, comparing to the typical LFU implementation. You have to define USE_BOOST macro to access that policy.\n\n\nPolicies:\n\n   The policy is a pluggable implementation of a cache algorithms,\n   used for finding and removing excessive cache entries. STL::Cache is\n   shipped with the following policies:\n     * None - A random expiration policy. Removes some random entry on\n       request\n     * LRU - 'Least recently used' policy.\n     * MRU - 'Most recentrly used' policy\n     * LFU - 'Least frequently used' policy\n     * LFU (Multi-index) - 'Least frequently used' policy implemented on top of the multi index map. Requires Boost.\n     * LFU* - 'Least frequently used' policy, that expires only items\n       with refcount 1, as proposed by M.Arlitt\n     * LFU-Aging - 'Least frequently used' policy with time-based\n       decreasing of usage count\n     * LFU*-Aging - Combination of LFU* and LFU*-Aging\n       policies\n     * Adaptive Replacement - 'Adaptive Replacement' policy\n\n   The cache expiration policy must be specified as a third parameter of\n   cache type and it is mandatory.\n\nYour own policy:\n\n   The policy implementation should keep track of entries in the cache and\n   it must be able to tell the cache, what item should be expired at the\n   moment. There is not any limitations on policy internal structure and\n   stuff, but it is expected, that policy conforms to some predefined\n   interfaces.\n\n   First of all - every policy is built in two classes, one class is the\n   policy iteslf, and another one is a 'bind wrapper':\n\n   Note:\n          All code examples in this section are from policy none\n\n        struct policy_none {\n        template \u003ctypename Key, template \u003ctypename T\u003e class Allocator\u003e\n            struct bind : _policy_none_type\u003cKey,Allocator\u003e {\n                bind(const bind\u0026 x) : _policy_none_type\u003cKey,Allocator\u003e(x)  { }\n                bind(const size_t\u0026 size) : _policy_none_type\u003cKey,Allocator\u003e(size\n) { }\n            };\n        };\n\n   As you may see, the policy itself is automatically configured with\n   caches's Key type and Allocator type. Of course, you could also pass\n   your own template parameters and partially instantiate the policy\n   implementation template:\n        template \u003cclass R\u003e struct policy_none {\n            template \u003ctypename Key, template \u003ctypename T\u003e class Allocator\u003e\n                struct bind : _policy_none_type\u003cR,Key,Allocator\u003e {\n                    bind(const bind\u0026 x) : _policy_none_type\u003cR,Key,Allocator\u003e(x)\n{ }\n                    bind(const size_t\u0026 size) : _policy_none_type\u003cR,Key,Allocator\n\u003e(size) { }\n                };\n        };\n\n   You could pass some implementation of R during cache type definition:\n         stlcache::cache\u003cint,int,stlcache::policy_none\u003cRandomizer\u003e \u003e c;\n\n   Well, the actual implementation must implement the policy interface\n   :\n        template \u003cclass Key,template \u003ctypename T\u003e class Allocator\u003e class policy\n{\n            public:\n            virtual void insert(const Key\u0026 _k) throw(exception_invalid_key)\n=0;\n            virtual void remove(const Key\u0026 _k) throw() =0;\n            virtual void touch(const Key\u0026 _k) throw() =0;\n            virtual void clear() throw() =0;\n            virtual void swap(policy\u003cKey,Allocator\u003e\u0026 _p) throw(exception_inv\nalid_policy)=0;\n            virtual const _victim\u003cKey\u003e victim() throw()  =0;\n        };\n\n   So, the policy could be asked for a victim , entries could be\n   inserted , removed and touched . It's contents could also\n   be cleared or swapped with another policy. Concrete policy\n   implementation should be CopyConstructible, Assignable and must provide\n   a constructor, for specifiying policy size:\n        template \u003cclass Key, template \u003ctypename T\u003e class Allocator\u003e class _polic\ny_none_type : public policy\u003cKey,Allocator\u003e {\n        public:\n            _policy_none_type\u003cKey,Allocator\u003e\u0026 operator= ( const _policy_none_typ\ne\u003cKey,Allocator\u003e\u0026 x) throw() { }\n            _policy_none_type(const _policy_none_type\u003cKey,Allocator\u003e\u0026 x) throw()\n {}\n            _policy_none_type(const size_t\u0026 size ) throw() { }\n\n            virtual void insert(const Key\u0026 _k) throw(exception_invalid_key)\n{}\n            virtual void remove(const Key\u0026 _k) throw() {}\n            virtual void touch(const Key\u0026 _k) throw() {}\n            virtual void clear() throw() {}\n            virtual void swap(policy\u003cKey,Allocator\u003e\u0026 _p) throw(exception_inv\nalid_policy) {}\n\n            virtual const _victim\u003cKey\u003e victim() throw() {}\n        };\n\n   It's up to you, how you will implement those methods and so on. The\n   only important thing, we haven't mentioned yet, is a victim class.\n   It is a way to return optional value from a function. So, when your\n   policy implementatiton cannot find any entry to remove, it will return\n   empty victim object.\n\nAuthors and Licensing\n\n   Copyright (C) 2011-2023 Denis V Chapligin, Martin Hrabovsky, Vojtech Ondruj, Tom Anderson\n   Distributed under the Boost Software License, Version 1.0. \n   (See accompanying file LICENSE_1_0.txt\n   or copy at http://www.boost.org/LICENSE_1_0.txt)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakashihi%2Fstlcache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakashihi%2Fstlcache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakashihi%2Fstlcache/lists"}