{"id":13397039,"url":"https://github.com/VictoriaMetrics/fastcache","last_synced_at":"2025-03-13T23:32:01.472Z","repository":{"id":37271427,"uuid":"158756762","full_name":"VictoriaMetrics/fastcache","owner":"VictoriaMetrics","description":"Fast thread-safe inmemory cache for big number of entries in Go. Minimizes GC overhead","archived":false,"fork":false,"pushed_at":"2024-07-04T15:15:39.000Z","size":2290,"stargazers_count":2113,"open_issues_count":47,"forks_count":175,"subscribers_count":42,"default_branch":"master","last_synced_at":"2024-10-14T12:05:04.969Z","etag":null,"topics":["cache","caching","caching-library","fast","go","golang","inmemory-cache"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VictoriaMetrics.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-11-22T22:50:13.000Z","updated_at":"2024-10-11T23:47:57.000Z","dependencies_parsed_at":"2023-11-24T12:30:14.518Z","dependency_job_id":"301853c7-2cfd-4a66-bbd8-d9540ac55c06","html_url":"https://github.com/VictoriaMetrics/fastcache","commit_stats":{"total_commits":65,"total_committers":13,"mean_commits":5.0,"dds":"0.36923076923076925","last_synced_commit":"c5013df18804b1fb293fe6b9f3906b5081cf698a"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VictoriaMetrics%2Ffastcache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VictoriaMetrics%2Ffastcache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VictoriaMetrics%2Ffastcache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VictoriaMetrics%2Ffastcache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VictoriaMetrics","download_url":"https://codeload.github.com/VictoriaMetrics/fastcache/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243039682,"owners_count":20226134,"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","caching","caching-library","fast","go","golang","inmemory-cache"],"created_at":"2024-07-30T18:01:09.948Z","updated_at":"2025-03-13T23:32:01.445Z","avatar_url":"https://github.com/VictoriaMetrics.png","language":"Go","readme":"[![Build Status](https://github.com/VictoriaMetrics/fastcache/workflows/main/badge.svg)](https://github.com/VictoriaMetrics/fastcache/actions)\n[![GoDoc](https://godoc.org/github.com/VictoriaMetrics/fastcache?status.svg)](http://godoc.org/github.com/VictoriaMetrics/fastcache)\n[![Go Report](https://goreportcard.com/badge/github.com/VictoriaMetrics/fastcache)](https://goreportcard.com/report/github.com/VictoriaMetrics/fastcache)\n[![codecov](https://codecov.io/gh/VictoriaMetrics/fastcache/branch/master/graph/badge.svg)](https://codecov.io/gh/VictoriaMetrics/fastcache)\n\n# fastcache - fast thread-safe inmemory cache for big number of entries in Go\n\n### Features\n\n* Fast. Performance scales on multi-core CPUs. See benchmark results below.\n* Thread-safe. Concurrent goroutines may read and write into a single\n  cache instance.\n* The fastcache is designed for storing big number of entries without\n  [GC overhead](https://syslog.ravelin.com/further-dangers-of-large-heaps-in-go-7a267b57d487).\n* Fastcache automatically evicts old entries when reaching the maximum cache size\n  set on its creation.\n* [Simple API](http://godoc.org/github.com/VictoriaMetrics/fastcache).\n* Simple source code.\n* Cache may be [saved to file](https://godoc.org/github.com/VictoriaMetrics/fastcache#Cache.SaveToFile)\n  and [loaded from file](https://godoc.org/github.com/VictoriaMetrics/fastcache#LoadFromFile).\n* Works on [Google AppEngine](https://cloud.google.com/appengine/docs/go/).\n\n\n### Benchmarks\n\n`Fastcache` performance is compared with [BigCache](https://github.com/allegro/bigcache), standard Go map\nand [sync.Map](https://golang.org/pkg/sync/#Map).\n\n```\nGOMAXPROCS=4 go test github.com/VictoriaMetrics/fastcache -bench='Set|Get' -benchtime=10s\ngoos: linux\ngoarch: amd64\npkg: github.com/VictoriaMetrics/fastcache\nBenchmarkBigCacheSet-4      \t    2000\t  10566656 ns/op\t   6.20 MB/s\t 4660369 B/op\t       6 allocs/op\nBenchmarkBigCacheGet-4      \t    2000\t   6902694 ns/op\t   9.49 MB/s\t  684169 B/op\t  131076 allocs/op\nBenchmarkBigCacheSetGet-4   \t    1000\t  17579118 ns/op\t   7.46 MB/s\t 5046744 B/op\t  131083 allocs/op\nBenchmarkCacheSet-4         \t    5000\t   3808874 ns/op\t  17.21 MB/s\t    1142 B/op\t       2 allocs/op\nBenchmarkCacheGet-4         \t    5000\t   3293849 ns/op\t  19.90 MB/s\t    1140 B/op\t       2 allocs/op\nBenchmarkCacheSetGet-4      \t    2000\t   8456061 ns/op\t  15.50 MB/s\t    2857 B/op\t       5 allocs/op\nBenchmarkStdMapSet-4        \t    2000\t  10559382 ns/op\t   6.21 MB/s\t  268413 B/op\t   65537 allocs/op\nBenchmarkStdMapGet-4        \t    5000\t   2687404 ns/op\t  24.39 MB/s\t    2558 B/op\t      13 allocs/op\nBenchmarkStdMapSetGet-4     \t     100\t 154641257 ns/op\t   0.85 MB/s\t  387405 B/op\t   65558 allocs/op\nBenchmarkSyncMapSet-4       \t     500\t  24703219 ns/op\t   2.65 MB/s\t 3426543 B/op\t  262411 allocs/op\nBenchmarkSyncMapGet-4       \t    5000\t   2265892 ns/op\t  28.92 MB/s\t    2545 B/op\t      79 allocs/op\nBenchmarkSyncMapSetGet-4    \t    1000\t  14595535 ns/op\t   8.98 MB/s\t 3417190 B/op\t  262277 allocs/op\n```\n\n`MB/s` column here actually means `millions of operations per second`.\nAs you can see, `fastcache` is faster than the `BigCache` in all the cases.\n`fastcache` is faster than the standard Go map and `sync.Map` on workloads\nwith inserts.\n\n\n### Limitations\n\n* Keys and values must be byte slices. Other types must be marshaled before\n  storing them in the cache.\n* Big entries with sizes exceeding 64KB must be stored via [distinct API](http://godoc.org/github.com/VictoriaMetrics/fastcache#Cache.SetBig).\n* There is no cache expiration. Entries are evicted from the cache only\n  on cache size overflow. Entry deadline may be stored inside the value in order\n  to implement cache expiration.\n\n\n### Architecture details\n\nThe cache uses ideas from [BigCache](https://github.com/allegro/bigcache):\n\n* The cache consists of many buckets, each with its own lock.\n  This helps scaling the performance on multi-core CPUs, since multiple\n  CPUs may concurrently access distinct buckets.\n* Each bucket consists of a `hash(key) -\u003e (key, value) position` map\n  and 64KB-sized byte slices (chunks) holding encoded `(key, value)` entries.\n  Each bucket contains only `O(chunksCount)` pointers. For instance, 64GB cache\n  would contain ~1M pointers, while similarly-sized `map[string][]byte`\n  would contain ~1B pointers for short keys and values. This would lead to\n  [huge GC overhead](https://syslog.ravelin.com/further-dangers-of-large-heaps-in-go-7a267b57d487).\n\n64KB-sized chunks reduce memory fragmentation and the total memory usage comparing\nto a single big chunk per bucket.\nChunks are allocated off-heap if possible. This reduces total memory usage because\nGC collects unused memory more frequently without the need in `GOGC` tweaking.\n\n\n### Users\n\n* `Fastcache` has been extracted from [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics) sources.\n  See [this article](https://medium.com/devopslinks/victoriametrics-creating-the-best-remote-storage-for-prometheus-5d92d66787ac)\n  for more info about `VictoriaMetrics`.\n\n\n### FAQ\n\n#### What is the difference between `fastcache` and other similar caches like [BigCache](https://github.com/allegro/bigcache) or [FreeCache](https://github.com/coocood/freecache)?\n\n* `Fastcache` is faster. See benchmark results above.\n* `Fastcache` uses less memory due to lower heap fragmentation. This allows\n  saving many GBs of memory on multi-GB caches.\n* `Fastcache` API [is simpler](http://godoc.org/github.com/VictoriaMetrics/fastcache).\n  The API is designed to be used in zero-allocation mode.\n\n\n#### Why `fastcache` doesn't support cache expiration?\n\nBecause we don't need cache expiration in [VictoriaMetrics](https://github.com/VictoriaMetrics/VictoriaMetrics).\nCached entries inside `VictoriaMetrics` never expire. They are automatically evicted on cache size overflow.\n\nIt is easy to implement cache expiration on top of `fastcache` by caching values\nwith marshaled deadlines and verifying deadlines after reading these values\nfrom the cache.\n\n\n#### Why `fastcache` doesn't support advanced features such as [thundering herd protection](https://en.wikipedia.org/wiki/Thundering_herd_problem) or callbacks on entries' eviction?\n\nBecause these features would complicate the code and would make it slower.\n`Fastcache` source code is simple - just copy-paste it and implement the feature you want\non top of it.\n","funding_links":[],"categories":["Go","Data Integration Frameworks","HarmonyOS","Database","开源类库","Awesome","Open source library","0x0D. VictoriaMetrics/fastcache","数据库","Uncategorized","Generators","Repositories","数据库  `go语言实现的数据库`","\u003ca name=\"Go\"\u003e\u003c/a\u003eGo"],"sub_categories":["Caches","Windows Manager","缓存","Advanced Console UIs","Cache","标准 CLI"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVictoriaMetrics%2Ffastcache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FVictoriaMetrics%2Ffastcache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FVictoriaMetrics%2Ffastcache/lists"}