{"id":13397105,"url":"https://github.com/allegro/bigcache","last_synced_at":"2025-05-12T03:38:36.829Z","repository":{"id":37493478,"uuid":"54539060","full_name":"allegro/bigcache","owner":"allegro","description":"Efficient cache for gigabytes of data written in Go.","archived":false,"fork":false,"pushed_at":"2025-05-05T03:12:00.000Z","size":265,"stargazers_count":7814,"open_issues_count":97,"forks_count":605,"subscribers_count":113,"default_branch":"main","last_synced_at":"2025-05-09T18:58:14.063Z","etag":null,"topics":["cache","caching","golang-library","hacktoberfest","performance"],"latest_commit_sha":null,"homepage":"http://allegro.tech/2016/03/writing-fast-cache-service-in-go.html","language":"Go","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/allegro.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-03-23T07:18:52.000Z","updated_at":"2025-05-09T09:52:51.000Z","dependencies_parsed_at":"2023-02-08T10:31:06.266Z","dependency_job_id":"417ab31f-5781-423a-92de-7fad2108df7b","html_url":"https://github.com/allegro/bigcache","commit_stats":{"total_commits":189,"total_committers":71,"mean_commits":"2.6619718309859155","dds":0.8941798941798942,"last_synced_commit":"a2f05d7cbfdc7000a8b7e1c40f27d3f239c204df"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allegro%2Fbigcache","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allegro%2Fbigcache/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allegro%2Fbigcache/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/allegro%2Fbigcache/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/allegro","download_url":"https://codeload.github.com/allegro/bigcache/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253669141,"owners_count":21945061,"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","golang-library","hacktoberfest","performance"],"created_at":"2024-07-30T18:01:10.985Z","updated_at":"2025-05-12T03:38:36.802Z","avatar_url":"https://github.com/allegro.png","language":"Go","readme":"# BigCache [![Build Status](https://github.com/allegro/bigcache/workflows/build/badge.svg)](https://github.com/allegro/bigcache/actions?query=workflow%3Abuild)\u0026nbsp;[![Coverage Status](https://coveralls.io/repos/github/allegro/bigcache/badge.svg?branch=main)](https://coveralls.io/github/allegro/bigcache?branch=main)\u0026nbsp;[![GoDoc](https://godoc.org/github.com/allegro/bigcache/v3?status.svg)](https://godoc.org/github.com/allegro/bigcache/v3)\u0026nbsp;[![Go Report Card](https://goreportcard.com/badge/github.com/allegro/bigcache/v3)](https://goreportcard.com/report/github.com/allegro/bigcache/v3)\n\nFast, concurrent, evicting in-memory cache written to keep big number of entries without impact on performance.\nBigCache keeps entries on heap but omits GC for them. To achieve that, operations on byte slices take place,\ntherefore entries (de)serialization in front of the cache will be needed in most use cases.\n\nRequires Go 1.12 or newer.\n\n## Usage\n\n### Simple initialization\n\n```go\nimport (\n\t\"fmt\"\n\t\"context\"\n\t\"github.com/allegro/bigcache/v3\"\n)\n\ncache, _ := bigcache.New(context.Background(), bigcache.DefaultConfig(10 * time.Minute))\n\ncache.Set(\"my-unique-key\", []byte(\"value\"))\n\nentry, _ := cache.Get(\"my-unique-key\")\nfmt.Println(string(entry))\n```\n\n### Custom initialization\n\nWhen cache load can be predicted in advance then it is better to use custom initialization because additional memory\nallocation can be avoided in that way.\n\n```go\nimport (\n\t\"log\"\n\n\t\"github.com/allegro/bigcache/v3\"\n)\n\nconfig := bigcache.Config {\n\t\t// number of shards (must be a power of 2)\n\t\tShards: 1024,\n\n\t\t// time after which entry can be evicted\n\t\tLifeWindow: 10 * time.Minute,\n\n\t\t// Interval between removing expired entries (clean up).\n\t\t// If set to \u003c= 0 then no action is performed.\n\t\t// Setting to \u003c 1 second is counterproductive — bigcache has a one second resolution.\n\t\tCleanWindow: 5 * time.Minute,\n\n\t\t// rps * lifeWindow, used only in initial memory allocation\n\t\tMaxEntriesInWindow: 1000 * 10 * 60,\n\n\t\t// max entry size in bytes, used only in initial memory allocation\n\t\tMaxEntrySize: 500,\n\n\t\t// prints information about additional memory allocation\n\t\tVerbose: true,\n\n\t\t// cache will not allocate more memory than this limit, value in MB\n\t\t// if value is reached then the oldest entries can be overridden for the new ones\n\t\t// 0 value means no size limit\n\t\tHardMaxCacheSize: 8192,\n\n\t\t// callback fired when the oldest entry is removed because of its expiration time or no space left\n\t\t// for the new entry, or because delete was called. A bitmask representing the reason will be returned.\n\t\t// Default value is nil which means no callback and it prevents from unwrapping the oldest entry.\n\t\tOnRemove: nil,\n\n\t\t// OnRemoveWithReason is a callback fired when the oldest entry is removed because of its expiration time or no space left\n\t\t// for the new entry, or because delete was called. A constant representing the reason will be passed through.\n\t\t// Default value is nil which means no callback and it prevents from unwrapping the oldest entry.\n\t\t// Ignored if OnRemove is specified.\n\t\tOnRemoveWithReason: nil,\n\t}\n\ncache, initErr := bigcache.New(context.Background(), config)\nif initErr != nil {\n\tlog.Fatal(initErr)\n}\n\ncache.Set(\"my-unique-key\", []byte(\"value\"))\n\nif entry, err := cache.Get(\"my-unique-key\"); err == nil {\n\tfmt.Println(string(entry))\n}\n```\n\n### `LifeWindow` \u0026 `CleanWindow`\n\n1. `LifeWindow` is a time. After that time, an entry can be called dead but not deleted.\n\n2. `CleanWindow` is a time. After that time, all the dead entries will be deleted, but not the entries that still have life.\n\n## [Benchmarks](https://github.com/allegro/bigcache-bench)\n\nThree caches were compared: bigcache, [freecache](https://github.com/coocood/freecache) and map.\nBenchmark tests were made using an\ni7-6700K CPU @ 4.00GHz with 32GB of RAM on Ubuntu 18.04 LTS (5.2.12-050212-generic).\n\nBenchmarks source code can be found [here](https://github.com/allegro/bigcache-bench)\n\n### Writes and reads\n\n```bash\ngo version\ngo version go1.13 linux/amd64\n\ngo test -bench=. -benchmem -benchtime=4s ./... -timeout 30m\ngoos: linux\ngoarch: amd64\npkg: github.com/allegro/bigcache/v3/caches_bench\nBenchmarkMapSet-8                     \t12999889\t       376 ns/op\t     199 B/op\t       3 allocs/op\nBenchmarkConcurrentMapSet-8           \t 4355726\t      1275 ns/op\t     337 B/op\t       8 allocs/op\nBenchmarkFreeCacheSet-8               \t11068976\t       703 ns/op\t     328 B/op\t       2 allocs/op\nBenchmarkBigCacheSet-8                \t10183717\t       478 ns/op\t     304 B/op\t       2 allocs/op\nBenchmarkMapGet-8                     \t16536015\t       324 ns/op\t      23 B/op\t       1 allocs/op\nBenchmarkConcurrentMapGet-8           \t13165708\t       401 ns/op\t      24 B/op\t       2 allocs/op\nBenchmarkFreeCacheGet-8               \t10137682\t       690 ns/op\t     136 B/op\t       2 allocs/op\nBenchmarkBigCacheGet-8                \t11423854\t       450 ns/op\t     152 B/op\t       4 allocs/op\nBenchmarkBigCacheSetParallel-8        \t34233472\t       148 ns/op\t     317 B/op\t       3 allocs/op\nBenchmarkFreeCacheSetParallel-8       \t34222654\t       268 ns/op\t     350 B/op\t       3 allocs/op\nBenchmarkConcurrentMapSetParallel-8   \t19635688\t       240 ns/op\t     200 B/op\t       6 allocs/op\nBenchmarkBigCacheGetParallel-8        \t60547064\t        86.1 ns/op\t     152 B/op\t       4 allocs/op\nBenchmarkFreeCacheGetParallel-8       \t50701280\t       147 ns/op\t     136 B/op\t       3 allocs/op\nBenchmarkConcurrentMapGetParallel-8   \t27353288\t       175 ns/op\t      24 B/op\t       2 allocs/op\nPASS\nok  \tgithub.com/allegro/bigcache/v3/caches_bench\t256.257s\n```\n\nWrites and reads in bigcache are faster than in freecache.\nWrites to map are the slowest.\n\n### GC pause time\n\n```bash\ngo version\ngo version go1.13 linux/amd64\n\ngo run caches_gc_overhead_comparison.go\n\nNumber of entries:  20000000\nGC pause for bigcache:  1.506077ms\nGC pause for freecache:  5.594416ms\nGC pause for map:  9.347015ms\n```\n\n```\ngo version\ngo version go1.13 linux/arm64\n\ngo run caches_gc_overhead_comparison.go\nNumber of entries:  20000000\nGC pause for bigcache:  22.382827ms\nGC pause for freecache:  41.264651ms\nGC pause for map:  72.236853ms\n```\n\nTest shows how long are the GC pauses for caches filled with 20mln of entries.\nBigcache and freecache have very similar GC pause time.\n\n### Memory usage\n\nYou may encounter system memory reporting what appears to be an exponential increase, however this is expected behaviour. Go runtime allocates memory in chunks or 'spans' and will inform the OS when they are no longer required by changing their state to 'idle'. The 'spans' will remain part of the process resource usage until the OS needs to repurpose the address. Further reading available [here](https://utcc.utoronto.ca/~cks/space/blog/programming/GoNoMemoryFreeing).\n\n## How it works\n\nBigCache relies on optimization presented in 1.5 version of Go ([issue-9477](https://github.com/golang/go/issues/9477)).\nThis optimization states that if map without pointers in keys and values is used then GC will omit its content.\nTherefore BigCache uses `map[uint64]uint32` where keys are hashed and values are offsets of entries.\n\nEntries are kept in byte slices, to omit GC again.\nByte slices size can grow to gigabytes without impact on performance\nbecause GC will only see single pointer to it.\n\n### Collisions\n\nBigCache does not handle collisions. When new item is inserted and it's hash collides with previously stored item, new item overwrites previously stored value.\n\n## Bigcache vs Freecache\n\nBoth caches provide the same core features but they reduce GC overhead in different ways.\nBigcache relies on `map[uint64]uint32`, freecache implements its own mapping built on\nslices to reduce number of pointers.\n\nResults from benchmark tests are presented above.\nOne of the advantage of bigcache over freecache is that you don’t need to know\nthe size of the cache in advance, because when bigcache is full,\nit can allocate additional memory for new entries instead of\noverwriting existing ones as freecache does currently.\nHowever hard max size in bigcache also can be set, check [HardMaxCacheSize](https://godoc.org/github.com/allegro/bigcache#Config).\n\n## HTTP Server\n\nThis package also includes an easily deployable HTTP implementation of BigCache, which can be found in the [server](/server) package.\n\n## More\n\nBigcache genesis is described in allegro.tech blog post: [writing a very fast cache service in Go](http://allegro.tech/2016/03/writing-fast-cache-service-in-go.html)\n\n## License\n\nBigCache is released under the Apache 2.0 license (see [LICENSE](LICENSE))\n","funding_links":[],"categories":["Go","开源类库","Database","数据库","Open source library","0x0E. allegro/bigcache","Data Integration Frameworks","數據庫","Generators","数据库  `go语言实现的数据库`","\u003cspan id=\"数据库-database\"\u003e数据库 Database\u003c/span\u003e","\u003ca name=\"Go\"\u003e\u003c/a\u003eGo","Uncategorized"],"sub_categories":["缓存","Caches","高级控制台界面","Cache","Advanced Console UIs","高級控制台界面","标准 CLI","\u003cspan id=\"高级控制台用户界面-advanced-console-uis\"\u003e高级控制台用户界面 Advanced Console UIs\u003c/span\u003e"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallegro%2Fbigcache","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fallegro%2Fbigcache","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fallegro%2Fbigcache/lists"}