{"id":42326455,"url":"https://github.com/ikod/cachetools","last_synced_at":"2026-01-27T13:10:41.314Z","repository":{"id":33531528,"uuid":"145146232","full_name":"ikod/cachetools","owner":"ikod","description":"python cachetools for dlang","archived":false,"fork":false,"pushed_at":"2025-04-13T07:47:12.000Z","size":2345,"stargazers_count":29,"open_issues_count":8,"forks_count":8,"subscribers_count":3,"default_branch":"master","last_synced_at":"2026-01-24T14:40:55.255Z","etag":null,"topics":["2q-cache","cache","cachetools","d","dlang","doubly-linked-list","hashmap","hashtable","lru-cache","ordereddict","set","ttl","unrolled-list"],"latest_commit_sha":null,"homepage":null,"language":"D","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ikod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-08-17T17:01:01.000Z","updated_at":"2025-05-23T20:09:28.000Z","dependencies_parsed_at":"2023-01-15T01:19:06.153Z","dependency_job_id":null,"html_url":"https://github.com/ikod/cachetools","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/ikod/cachetools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikod%2Fcachetools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikod%2Fcachetools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikod%2Fcachetools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikod%2Fcachetools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ikod","download_url":"https://codeload.github.com/ikod/cachetools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ikod%2Fcachetools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28813292,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-27T12:25:15.069Z","status":"ssl_error","status_checked_at":"2026-01-27T12:25:05.297Z","response_time":168,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["2q-cache","cache","cachetools","d","dlang","doubly-linked-list","hashmap","hashtable","lru-cache","ordereddict","set","ttl","unrolled-list"],"created_at":"2026-01-27T13:10:40.817Z","updated_at":"2026-01-27T13:10:41.296Z","avatar_url":"https://github.com/ikod.png","language":"D","readme":"[![Run Tests](https://github.com/ikod/cachetools/actions/workflows/blank.yml/badge.svg)](https://github.com/ikod/cachetools/actions/workflows/blank.yml)\n[![codecov.io](https://codecov.io/github/ikod/cachetools/coverage.svg?branch=master)](https://codecov.io/github/ikod/cachetools?branch=master)\n[![Dub downloads](https://img.shields.io/dub/dt/cachetools.svg)](http://code.dlang.org/packages/cachetools)\n# cachetools #\n\nThis package contains some cache implementations (for example LRU cache) and underlying data structures.\n\nWhy you may want to use it? Because it is fast, `@safe`. It is also `@nogc` and `nothrow` (inherited from your key/value types).\n\nLimitations:\n* Cache implementations are not inherited from inerface or base class.\nThis is because inheritance and attribute inference don't work together.\n\n### 2Q cache ###\n\n2Q cache is variant of multi-level LRU cache. Original paper http://www.vldb.org/conf/1994/P439.PDF\nIt is adaptive, scan-resistant and can give more hits than plain LRU.\n\nThis cache consists from three parts (In, Out and Main) where 'In' receive all new elements, 'Out' receives all\noverflows from 'In', and 'Main' is LRU cache which hold all long-lived data.)\n\n\n### LRU cache ###\n\nLRU cache keep limited number of items in memory. When adding new item to already full cache we have to evict some items.\nEviction candidates are selected first from expired items (using per-cache configurable TTL) or from oldest accessed items.\n\n## Code examples ##\n\n```d\n    auto cache = new CacheLRU!(int, string); // can be Cache2Q!(int, string)\n    cache.size = 2048;      // keep 2048 elements in cache\n    cache.ttl = 60.seconds; // set 60 seconds TTL for items in cache\n    \n    cache.put(1, \"one\");\n    auto v = cache.get(1);\n    assert(v == \"one\");  // 1 is in cache\n    v = cache.get(2);\n    assert(v.isNull);    // no such item in cache\n\n```\n\nDefault values for TTL is 0 which means - no TTL. Default value for size is 1024;\n\n### Class instance as key ###\n\nTo use class as key with this code, you have to define toHash and opEquals(**important**: opEquals to the class instance not Object) as safe or trusted (optionally as nogc if\nyou need it):\n\n```d\n    import cachetools.hash: hash_function;\n    class C\n    {\n        int s;\n        this(int v)\n        {\n            s = v;\n        }\n        override hash_t toHash() const\n        {\n            return hash_function(s);\n        }\n        bool opEquals(const C other) pure const @safe\n        {\n            return s == other.s;\n        }\n    }\n    CacheLRU!(immutable C, string) cache = new CacheLRU!(immutable C, string);\n    immutable C s1 = new immutable C(1);\n    cache.put(s1, \"one\");\n    auto s11 = cache.get(s1);\n    assert(s11 == \"one\");\n\n```\n\n### Cache events ###\n\nSometimes you have to know if items are purged from cache or modified. You can configure cache to report such events.\n*Important warning* - if you enable cache events and do not check it after cache operations, then list of stored events will\ngrow without bounds. Code sample:\n```d\n\n    auto lru = new CacheLRU!(int, string);\n    lru.enableCacheEvents();\n    lru.put(1, \"one\");\n    lru.put(1, \"next one\");\n    assert(lru.get(1) == \"next one\");\n    auto events = lru.cacheEvents();\n    writeln(events);\n\n```\noutput:\n```\n[CacheEvent!(int, string)(Updated, 1, \"one\")]\n```\nEach `CacheEvent` have `key` and `val` members and name of the event(Removed, Expired, Updated, Evicted).\nEvents generated in case:\n* Event.Removed - when item removed from the cache via `remove(key)` or `clear()`.\n* Event.Expired - when item has TTL and get(key) for this item called.\n* Event.Updated - when you call put(key, value) and key already presented in cache.\n* Event.Evicted - when cache have some limits (like total number of items in cache or total size) and this limit reached, so we have to purge something from cache.\n\n## Hash Table ##\n\nSome parts of this package are based on internal hash table which can be used independently. It is open-addressing\nhash table with keys and values stored inline in the buckets array to avoid unnecessary allocations and better use \nof CPU cache for small key/value types.\n\nHash Table supports immutable keys and values. Due to language limitations you can't use structs with immutable/const\nmembers.\n\nAll hash table code is `@safe` and require from user supplied functions such as `toHash` or `opEquals` also be safe (or trusted).\n\nIt is also `@nogc` if `toHash` and `opEquals` are `@nogc`. `opIndex` is not `@nogc` as it can throw exception.\n\nSeveral code samples:\n\n```d\nimport cachetools.containers.hashmap;\n\nstring[] words = [\"hello\", \"my\", \"friend\", \"hello\"];\n\nvoid main()\n{\n    HashMap!(string, int) counter;\n\n    build0(counter); // build table (verbose variant)\n    report(counter);\n\n    counter.clear(); // clear table\n\n    build1(counter); // build table (less verbose variant)\n    report(counter);\n}\n\n/// verbose variant\nvoid build0(ref HashMap!(string, int) counter) @safe @nogc\n{\n    foreach(word; words)\n    {\n        auto w = word in counter;\n        if ( w !is null )\n        {\n            (*w)++; // update\n        }\n        else\n        {\n            counter[word] = 1; // create\n        }\n    }\n}\n/// short variant\nvoid build1(ref HashMap!(string, int) counter) @safe @nogc\n{\n    foreach(word; words)\n    {\n        auto w = word in counter;\n        counter.getOrAdd(word, 0)++;\n    }\n}\n\nvoid report(ref HashMap!(string, int) hashmap) @safe\n{\n    import std.stdio;\n    writefln(\"keys: %s\", hashmap.byKey);\n    writefln(\"values: %s\", hashmap.byValue);\n    writefln(\"pairs: %s\", hashmap.byPair);\n    writeln(\"---\");\n}\n```\nOutput:\n```\nkeys: [\"hello\", \"friend\", \"my\"]\nvalues: [2, 1, 1]\npairs: [Tuple!(string, \"key\", int, \"value\")(\"hello\", 2), Tuple!(string, \"key\", int, \"value\")(\"friend\", 1), Tuple!(string, \"key\", int, \"value\")(\"my\", 1)]\n---\nkeys: [\"hello\", \"friend\", \"my\"]\nvalues: [2, 1, 1]\npairs: [Tuple!(string, \"key\", int, \"value\")(\"hello\", 2), Tuple!(string, \"key\", int, \"value\")(\"friend\", 1), Tuple!(string, \"key\", int, \"value\")(\"my\", 1)]\n---\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikod%2Fcachetools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fikod%2Fcachetools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fikod%2Fcachetools/lists"}