{"id":20751603,"url":"https://github.com/arham09/gocache","last_synced_at":"2026-07-06T20:31:33.203Z","repository":{"id":140997293,"uuid":"592651405","full_name":"arham09/gocache","owner":"arham09","description":null,"archived":false,"fork":false,"pushed_at":"2023-04-14T07:04:42.000Z","size":26,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-18T03:43:06.854Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","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/arham09.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-24T08:10:44.000Z","updated_at":"2023-07-14T11:50:04.000Z","dependencies_parsed_at":null,"dependency_job_id":"1e599511-aa9e-45da-a6fc-32a67b94d305","html_url":"https://github.com/arham09/gocache","commit_stats":null,"previous_names":["arham09/cache"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arham09%2Fgocache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arham09%2Fgocache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arham09%2Fgocache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arham09%2Fgocache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arham09","download_url":"https://codeload.github.com/arham09/gocache/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243052216,"owners_count":20228353,"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":[],"created_at":"2024-11-17T08:37:05.862Z","updated_at":"2025-10-25T22:12:19.592Z","avatar_url":"https://github.com/arham09.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# cache\n\u003c!-- [![test](https://github.com/arham09/cache/workflows/test/badge.svg?branch=master) --\u003e\n\u003c!-- [![Go Report Card](https://goreportcard.com/badge/github.com/TwiN/cache)](https://goreportcard.com/report/github.com/TwiN/cache) --\u003e\n\u003c!-- [![codecov](https://codecov.io/gh/TwiN/cache/branch/master/graph/badge.svg)](https://codecov.io/gh/TwiN/cache) --\u003e\n\u003c!-- [![Go version](https://img.shields.io/github/go-mod/go-version/arham09/cache.svg)](https://github.com/arham09/cache) --\u003e\n[![Follow arham09](https://img.shields.io/github/followers/arham09?label=Follow\u0026style=social)](https://github.com/arham09)\n\ncache was created to learn about cache eviction, heavily extracted from [gocache](https://github.com/TwiN/gocache) and adding LFU policy for more eviction, if you want to use it please test it carefully, cache is easy-to-use, high-performance, lightweight and thread-safe (goroutine-safe) in-memory key-value cache with support for LFU, LRU and FIFO eviction policies as well as expiration, bulk operations and even retrieval of keys by pattern.\n\n\n## Table of Contents\n\n- [Features](#features)\n- [Usage](#usage)\n  - [Initializing the cache](#initializing-the-cache)\n  - [Functions](#functions)\n  - [Examples](#examples)\n    - [Creating or updating an entry](#creating-or-updating-an-entry)\n    - [Getting an entry](#getting-an-entry)\n    - [Deleting an entry](#deleting-an-entry)\n    - [Complex example](#complex-example)\n- [Eviction](#eviction)\n  - [MaxSize](#maxsize)\n  - [MaxMemoryUsage](#maxmemoryusage)\n- [Expiration](#expiration)\n- [Performance](#performance)\n  - [Summary](#summary)\n  - [Results](#results)\n\n\n## Features\ncache supports the following cache eviction policies: \n- First in first out (FIFO)\n- Least recently used (LRU)\n- Least frequent used (LFU)\n\nIt also supports cache entry TTL, which is both active and passive. Active expiration means that if you attempt \nto retrieve a cache key that has already expired, it will delete it on the spot and the behavior will be as if\nthe cache key didn't exist. As for passive expiration, there's a background task that will take care of deleting\nexpired keys.\n\nIt also includes what you'd expect from a cache, like GET/SET, bulk operations and get by pattern.\n\n\n## Usage\n```\ngo get -u github.com/arham09/cache\n```\n\n\n### Initializing the cache\n```go\nc := cache.NewCache(WithMaxSize(1000), WithEvictionPolicy(cache.LeastRecentlyUsed))\n```\n\nIf you're planning on using expiration (`SetWithTTL` or `Expire`) and you want expired entries to be automatically deleted \nin the background, make sure to start the janitor when you instantiate the cache:\n\n```go\ncache.StartJanitor()\n```\n\n### Functions\n| Function                          | Description                                                                                                                                                                                                                                                        |\n|-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| WithMaxSize                       | Sets the max size of the cache. `cache.NoMaxSize` means there is no limit. If not set, the default max size is `cache.DefaultMaxSize`.                                                                                                                         |\n| WithMaxMemoryUsage                | Sets the max memory usage of the cache. `cache.NoMaxMemoryUsage` means there is no limit. The default behavior is to not evict based on memory usage.                                                                                                            |\n| WithEvictionPolicy                | Sets the eviction algorithm to be used when the cache reaches the max size. If not set, the default eviction policy is `cache.FirstInFirstOut` (FIFO).                                                                                                           |\n| WithForceNilInterfaceOnNilPointer | Configures whether values with a nil pointer passed to write functions should be forcefully set to nil. Defaults to true.                                                                                                                                          |\n| StartJanitor                      | Starts the janitor, which is in charge of deleting expired cache entries in the background.                                                                                                                                                                        |\n| StopJanitor                       | Stops the janitor.                                                                                                                                                                                                                                                 |\n| Set                               | Same as `SetWithTTL`, but with no expiration (`cache.NoExpiration`)                                                                                                                                                                                              |\n| SetAll                            | Same as `Set`, but in bulk                                                                                                                                                                                                                                         |\n| SetWithTTL                        | Creates or updates a cache entry with the given key, value and expiration time. If the max size after the aforementioned operation is above the configured max size, the tail will be evicted. Depending on the eviction policy, the tail is defined as the oldest |\n| Get                               | Gets a cache entry by its key.                                                                                                                                                                                                                                     |\n| GetByKeys                         | Gets a map of entries by their keys. The resulting map will contain all keys, even if some of the keys in the slice passed as parameter were not present in the cache.                                                                                             |\n| GetAll                            | Gets all cache entries.                                                                                                                                                                                                                                            |\n| GetKeysByPattern                  | Retrieves a slice of keys that matches a given pattern.                                                                                                                                                                                                            |\n| Delete                            | Removes a key from the cache.                                                                                                                                                                                                                                      |\n| DeleteAll                         | Removes multiple keys from the cache.                                                                                                                                                                                                                              |\n| DeleteKeysByPattern               | Removes all keys that that matches a given pattern.                                                                                                                                                                                                                |\n| Count                             | Gets the size of the cache. This includes cache keys which may have already expired, but have not been removed yet.                                                                                                                                                |\n| Clear                             | Wipes the cache.                                                                                                                                                                                                                                                   |\n| TTL                               | Gets the time until a cache key expires.                                                                                                                                                                                                                           |\n| Expire                            | Sets the expiration time of an existing cache key.                                                                                                                                                                                                                 |\n\n\n### Examples\n\n#### Creating or updating an entry\n```go\ncache.Set(\"key\", \"value\") \ncache.Set(\"key\", 1)\ncache.Set(\"key\", struct{ Text string }{Test: \"value\"})\ncache.SetWithTTL(\"key\", []byte(\"value\"), 24*time.Hour)\n```\n\n#### Getting an entry\n```go\nvalue, exists := cache.Get(\"key\")\n```\nYou can also get multiple entries by using `cache.GetByKeys([]string{\"key1\", \"key2\"})`\n\n#### Deleting an entry\n```go\ncache.Delete(\"key\")\n```\nYou can also delete multiple entries by using `cache.DeleteAll([]string{\"key1\", \"key2\"})`\n\n#### Complex example\n```go\npackage main\n\nimport (\n    \"fmt\"\n    \"time\"\n\n    \"github.com/arham09/cache\"\n)\n\nfunc main() {\n    c := cache.NewCache(cache.WithEvictionPolicy(cache.LeastRecentlyUsed), cache.WithMaxSize(10000))\n    cache.StartJanitor() // Passively manages expired entries\n    defer cache.StopJanitor()\n\n    c.Set(\"key\", \"value\")\n    c.SetWithTTL(\"key-with-ttl\", \"value\", 60*time.Minute)\n    c.SetAll(map[string]interface{}{\"k1\": \"v1\", \"k2\": \"v2\", \"k3\": \"v3\"})\n\n    fmt.Println(\"[Count] Cache size:\", cache.Count())\n\n    value, exists := c.Get(\"key\")\n    fmt.Printf(\"[Get] key=key; value=%s; exists=%v\\n\", value, exists)\n    for key, value := range c.GetByKeys([]string{\"k1\", \"k2\", \"k3\"}) {\n        fmt.Printf(\"[GetByKeys] key=%s; value=%s\\n\", key, value)\n    }\n    for _, key := range c.GetKeysByPattern(\"key*\", 0) {\n        fmt.Printf(\"[GetKeysByPattern] pattern=key*; key=%s\\n\", key)\n    }\n\n    c.Expire(\"key\", time.Hour)\n    time.Sleep(500*time.Millisecond)\n    timeUntilExpiration, _ := c.TTL(\"key\")\n    fmt.Println(\"[TTL] Number of minutes before 'key' expires:\", int(timeUntilExpiration.Seconds()))\n\n    c.Delete(\"key\")\n    c.DeleteAll([]string{\"k1\", \"k2\", \"k3\"})\n    \n    c.Clear()\n    fmt.Println(\"[Count] Cache size after clearing the cache:\", c.Count())\n}\n```\n\n\u003cdetails\u003e\n  \u003csummary\u003eOutput\u003c/summary\u003e\n\n```\n[Count] Cache size: 5\n[Get] key=key; value=value; exists=true\n[GetByKeys] key=k1; value=v1\n[GetByKeys] key=k2; value=v2\n[GetByKeys] key=k3; value=v3\n[GetKeysByPattern] pattern=key*; key=key-with-ttl\n[GetKeysByPattern] pattern=key*; key=key\n[TTL] Number of minutes before 'key' expires: 3599\n[Count] Cache size after clearing the cache: 0\n```\n\u003c/details\u003e\n\n\n## Eviction\n### MaxSize\nEviction by MaxSize is the default behavior, and is also the most efficient.\n\nThe code below will create a cache that has a maximum size of 1000:\n```go\nc := cache.NewCache(cache.WithMaxSize(1000))\n```\nThis means that whenever an operation causes the total size of the cache to go above 1000, the tail will be evicted.\n\n### MaxMemoryUsage\nEviction by MaxMemoryUsage is **disabled by default**, and is in alpha.\n\nThe code below will create a cache that has a maximum memory usage of 50MB:\n```go\nc := cache.NewCache(cache.WithMaxSize(0), cache.WithMaxMemoryUsage(50*cache.Megabyte))\n```\nThis means that whenever an operation causes the total memory usage of the cache to go above 50MB, one or more tails\nwill be evicted.\n\nUnlike evictions caused by reaching the MaxSize, evictions triggered by MaxMemoryUsage may lead to multiple entries\nbeing evicted in a row. The reason for this is that if, for instance, you had 100 entries of 0.1MB each and you suddenly added \na single entry of 10MB, 100 entries would need to be evicted to make enough space for that new big entry.\n\nIt's very important to keep in mind that eviction by MaxMemoryUsage is approximate.\n\n**The only memory taken into consideration is the size of the cache, not the size of the entire application.**\nIf you pass along 100MB worth of data in a matter of seconds, even though the cache's memory usage will remain\nunder 50MB (or whatever you configure the MaxMemoryUsage to), the memory footprint generated by that 100MB will \nstill exist until the next GC cycle.\n\nAs previously mentioned, this is a work in progress, and here's a list of the things you should keep in mind:\n- The memory usage of structs are a gross estimation and may not reflect the actual memory usage.\n- Native types (string, int, bool, []byte, etc.) are the most accurate for calculating the memory usage.\n- Adding an entry bigger than the configured MaxMemoryUsage will work, but it will evict all other entries.\n\n\n## Expiration\nThere are two ways that the deletion of expired keys can take place:\n- Active\n- Passive\n\n**Active deletion of expired keys** happens when an attempt is made to access the value of a cache entry that expired. \n`Get`, `GetByKeys` and `GetAll` are the only functions that can trigger active deletion of expired keys.\n\n**Passive deletion of expired keys** runs in the background and is managed by the janitor. \nIf you do not start the janitor, there will be no passive deletion of expired keys.\n\n\n## Performance\n### Summary\n- **Set**: Both map and cache have the same performance.\n- **Get**: Map is faster than cache.\n\nThis is because cache keeps track of the head and the tail for eviction and expiration/TTL. \n\nUltimately, the difference is negligible. \n\nWe could add a way to disable eviction or disable expiration altogether just to match the map's performance, \nbut if you're looking into using a library like cache, odds are, you want more than just a map.\n\n\n### Results\n| key    | value    |\n|:------ |:-------- |\n| goos   | windows  |\n| goarch | amd64    |\n| cpu    | i7-9700K |\n| mem    | 32G DDR4 |\n\n\u003c!-- ```\n// Normal map\nBenchmarkMap_Get\nBenchmarkMap_Get-8                                                              46087372  26.7 ns/op\nBenchmarkMap_Set                                                                   \nBenchmarkMap_Set/small_value-8                                                   3841911   389 ns/op\nBenchmarkMap_Set/medium_value-8                                                  3887074   391 ns/op\nBenchmarkMap_Set/large_value-8                                                   3921956   393 ns/op\n// Cache                                                                         \nBenchmarkCache_Get                                                                 \nBenchmarkCache_Get/FirstInFirstOut-8                                            27273036  46.4 ns/op\nBenchmarkCache_Get/LeastRecentlyUsed-8                                          26648248  46.3 ns/op\nBenchmarkCache_Set                                                              \nBenchmarkCache_Set/FirstInFirstOut_small_value-8                                 2919584   405 ns/op\nBenchmarkCache_Set/FirstInFirstOut_medium_value-8                                2990841   391 ns/op\nBenchmarkCache_Set/FirstInFirstOut_large_value-8                                 2970513   391 ns/op\nBenchmarkCache_Set/LeastRecentlyUsed_small_value-8                               2962939   402 ns/op\nBenchmarkCache_Set/LeastRecentlyUsed_medium_value-8                              2962963   390 ns/op\nBenchmarkCache_Set/LeastRecentlyUsed_large_value-8                               2962928   394 ns/op\nBenchmarkCache_SetUsingMaxMemoryUsage                                           \nBenchmarkCache_SetUsingMaxMemoryUsage/small_value-8                              2683356   447 ns/op\nBenchmarkCache_SetUsingMaxMemoryUsage/medium_value-8                             2637578   441 ns/op\nBenchmarkCache_SetUsingMaxMemoryUsage/large_value-8                              2672434   443 ns/op\nBenchmarkCache_SetWithMaxSize                                                   \nBenchmarkCache_SetWithMaxSize/100_small_value-8                                  4782966   252 ns/op\nBenchmarkCache_SetWithMaxSize/10000_small_value-8                                4067967   296 ns/op\nBenchmarkCache_SetWithMaxSize/100000_small_value-8                               3762055   328 ns/op\nBenchmarkCache_SetWithMaxSize/100_medium_value-8                                 4760479   252 ns/op\nBenchmarkCache_SetWithMaxSize/10000_medium_value-8                               4081050   295 ns/op\nBenchmarkCache_SetWithMaxSize/100000_medium_value-8                              3785050   330 ns/op\nBenchmarkCache_SetWithMaxSize/100_large_value-8                                  4732909   254 ns/op\nBenchmarkCache_SetWithMaxSize/10000_large_value-8                                4079533   297 ns/op\nBenchmarkCache_SetWithMaxSize/100000_large_value-8                               3712820   331 ns/op\nBenchmarkCache_SetWithMaxSizeAndLRU                                             \nBenchmarkCache_SetWithMaxSizeAndLRU/100_small_value-8                            4761732   254 ns/op\nBenchmarkCache_SetWithMaxSizeAndLRU/10000_small_value-8                          4084474   296 ns/op\nBenchmarkCache_SetWithMaxSizeAndLRU/100000_small_value-8                         3761402   329 ns/op\nBenchmarkCache_SetWithMaxSizeAndLRU/100_medium_value-8                           4783075   254 ns/op\nBenchmarkCache_SetWithMaxSizeAndLRU/10000_medium_value-8                         4103980   296 ns/op\nBenchmarkCache_SetWithMaxSizeAndLRU/100000_medium_value-8                        3646023   331 ns/op\nBenchmarkCache_SetWithMaxSizeAndLRU/100_large_value-8                            4779025   254 ns/op\nBenchmarkCache_SetWithMaxSizeAndLRU/10000_large_value-8                          4096192   296 ns/op\nBenchmarkCache_SetWithMaxSizeAndLRU/100000_large_value-8                         3726823   331 ns/op\nBenchmarkCache_GetSetMultipleConcurrent                                         \nBenchmarkCache_GetSetMultipleConcurrent-8                                         707142  1698 ns/op\nBenchmarkCache_GetSetConcurrentWithFrequentEviction\nBenchmarkCache_GetSetConcurrentWithFrequentEviction/FirstInFirstOut-8            3616256   334 ns/op\nBenchmarkCache_GetSetConcurrentWithFrequentEviction/LeastRecentlyUsed-8          3636367   331 ns/op\nBenchmarkCache_GetConcurrentWithLRU                                              \nBenchmarkCache_GetConcurrentWithLRU/FirstInFirstOut-8                            4405557   268 ns/op\nBenchmarkCache_GetConcurrentWithLRU/LeastRecentlyUsed-8                          4445475   269 ns/op\nBenchmarkCache_WithForceNilInterfaceOnNilPointer\nBenchmarkCache_WithForceNilInterfaceOnNilPointer/true_with_nil_struct_pointer-8  6184591   191 ns/op\nBenchmarkCache_WithForceNilInterfaceOnNilPointer/true-8                          6090482   191 ns/op\nBenchmarkCache_WithForceNilInterfaceOnNilPointer/false_with_nil_struct_pointer-8 6184629   187 ns/op\nBenchmarkCache_WithForceNilInterfaceOnNilPointer/false-8                         6281781   186 ns/op\n(Trimmed \"BenchmarkCache_\" for readability)\nWithForceNilInterfaceOnNilPointerWithConcurrency\nWithForceNilInterfaceOnNilPointerWithConcurrency/true_with_nil_struct_pointer-8  4379564   268 ns/op\nWithForceNilInterfaceOnNilPointerWithConcurrency/true-8                          4379558   265 ns/op\nWithForceNilInterfaceOnNilPointerWithConcurrency/false_with_nil_struct_pointer-8 4444456   261 ns/op\nWithForceNilInterfaceOnNilPointerWithConcurrency/false-8                         4493896   262 ns/op\n``` --\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farham09%2Fgocache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farham09%2Fgocache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farham09%2Fgocache/lists"}