gache is thinnest cache library for go application
Go 1.18~
go get github.com/kpango/gache/v2 // data sets
var (
key1 = "key"
key2 = 5050
key3 = struct{}{}
value1 = "value"
value2 = 88888
value3 = struct{}{}
)
// instantiate gache for any type as gc with setup default expiration.
// see more Options in example/main.go
gc := gache.New[any]().SetDefaultExpire(time.Second * 10)
// store with expire setting
gc.SetWithExpire(key1, value1, time.Second*30)
gc.SetWithExpire(key2, value2, time.Second*60)
gc.SetWithExpire(key3, value3, time.Hour) // load cache data
v1, ok := gc.Get(key1)
v2, ok := gc.Get(key2)
v3, ok := gc.Get(key3)
// open exported cache file
file, err := os.OpenFile("./gache-sample.gdb", os.O_TRUNC|os.O_CREATE|os.O_WRONLY, 0755)
if err != nil {
glg.Error(err)
return
}
// export cached variable with expiration time
gc.Write(context.Background(), file)
file.Close()
// open exported cache file
file, err = os.OpenFile("./gache-sample.gdb", os.O_RDONLY, 0755)
if err != nil {
glg.Error(err)
return
}
defer file.Close()
// instantiate new gache for any type as gcn with load exported cache from file
gcn := gache.New[any]().SetDefaultExpire(time.Minute).Read(file)
// gache supports range loop processing method
gcn.Range(context.Background(), func(k string, v any, exp int64) bool {
glg.Debugf("key:\t%v\nval:\t%v", k, v)
return true
})
// instantiate new gache for int64 type as gci
gci := gache.New[int64]()
gci.Set("sample1", int64(0))
gci.Set("sample2", int64(10))
gci.Set("sample3", int64(100))
// gache supports range loop processing method and inner function argument is int64 as contract
gci.Range(context.Background(), func(k string, v int64, exp int64) bool {
glg.Debugf("key:\t%v\nval:\t%d", k, v)
return true
})
// Optional configurations
// WithDefaultExpiration sets the default expiration time for keys.
// WithMaxKeyLength limits the max bytes of the key used to compute the shard ID.
// StartExpired runs a background job that periodically removes expired items.
// Set the expired hook function and enable it before starting the expiration daemon
gch := gache.New(
gache.WithDefaultExpiration[string](time.Minute),
gache.WithMaxKeyLength[string](256),
).SetExpiredHook(func(ctx context.Context, key string, v string) {
fmt.Printf("Item expired: key=%s value=%s\n", key, v)
}).EnableExpiredHook().StartExpired(context.Background(), time.Second*10)
// Store an item only if it does not already exist
gch.SetIfNotExists("key4", "value4")
// Extend the expiration time of an existing item
gch.ExtendExpire("key4", time.Minute*5)
// Read a value and refresh its expiration duration
v7, ok := gch.GetRefresh("key4")
// Retrieve a value regardless of its expiration state
v8, ok := gch.GetWithIgnoredExpire("key4")
// Retrieve a value and remove it from the cache
v9, ok := gch.Pop("key4")
// Get all keys currently in the cache
keys := gch.Keys(context.Background())
// Clear the entire cache
gch.Clear()
// Stop the background expiration job
gch.Stop()Benchmark results are shown below and benchmarked in this repository
go test -count=1 -timeout=30m -run=NONE -bench . -benchmem
goos: linux
goarch: amd64
pkg: github.com/kpango/go-cache-lib-benchmarks
cpu: AMD Ryzen Threadripper 3990X 64-Core Processor
BenchmarkDefaultMapSetGetSmallDataNoTTL/P100-128 1325295 820.7 ns/op 130 B/op 8 allocs/op
BenchmarkDefaultMapSetGetSmallDataNoTTL/P1000-128 1861357 1437 ns/op 134 B/op 8 allocs/op
BenchmarkDefaultMapSetGetSmallDataNoTTL/P10000-128 1264531 1214 ns/op 209 B/op 10 allocs/op
BenchmarkDefaultMapSetGetBigDataNoTTL/P100-128 8 187055869 ns/op 4324350 B/op 265392 allocs/op
BenchmarkDefaultMapSetGetBigDataNoTTL/P1000-128 8 181473875 ns/op 5475553 B/op 294184 allocs/op
BenchmarkDefaultMapSetGetBigDataNoTTL/P10000-128 5 220690015 ns/op 24675384 B/op 774189 allocs/op
BenchmarkSyncMapSetGetSmallDataNoTTL/P100-128 468852 2421 ns/op 324 B/op 12 allocs/op
BenchmarkSyncMapSetGetSmallDataNoTTL/P1000-128 646905 2153 ns/op 337 B/op 12 allocs/op
BenchmarkSyncMapSetGetSmallDataNoTTL/P10000-128 134409 7484 ns/op 1088 B/op 31 allocs/op
BenchmarkSyncMapSetGetBigDataNoTTL/P100-128 150 15476148 ns/op 10492638 B/op 393388 allocs/op
BenchmarkSyncMapSetGetBigDataNoTTL/P1000-128 87 13345667 ns/op 10603526 B/op 396161 allocs/op
BenchmarkSyncMapSetGetBigDataNoTTL/P10000-128 64 20342732 ns/op 12085859 B/op 433220 allocs/op
BenchmarkGacheV2SetGetSmallDataNoTTL/P100-128 4071116 268.8 ns/op 0 B/op 0 allocs/op
BenchmarkGacheV2SetGetSmallDataNoTTL/P1000-128 4239015 263.3 ns/op 4 B/op 0 allocs/op
BenchmarkGacheV2SetGetSmallDataNoTTL/P10000-128 829630 1239 ns/op 123 B/op 3 allocs/op
BenchmarkGacheV2SetGetSmallDataWithTTL/P100-128 4241361 261.0 ns/op 0 B/op 0 allocs/op
BenchmarkGacheV2SetGetSmallDataWithTTL/P1000-128 4414032 265.2 ns/op 2 B/op 0 allocs/op
BenchmarkGacheV2SetGetSmallDataWithTTL/P10000-128 1549258 828.6 ns/op 66 B/op 1 allocs/op
BenchmarkGacheV2SetGetBigDataNoTTL/P100-128 175 13330066 ns/op 6118 B/op 149 allocs/op
BenchmarkGacheV2SetGetBigDataNoTTL/P1000-128 288 15665110 ns/op 35775 B/op 891 allocs/op
BenchmarkGacheV2SetGetBigDataNoTTL/P10000-128 111 11865924 ns/op 922887 B/op 23067 allocs/op
BenchmarkGacheV2SetGetBigDataWithTTL/P100-128 202 10517910 ns/op 71942 B/op 926 allocs/op
BenchmarkGacheV2SetGetBigDataWithTTL/P1000-128 178 7074201 ns/op 130711 B/op 2338 allocs/op
BenchmarkGacheV2SetGetBigDataWithTTL/P10000-128 121 8614236 ns/op 935641 B/op 22406 allocs/op
BenchmarkGacheSetGetSmallDataNoTTL/P100-128 4186824 295.3 ns/op 160 B/op 8 allocs/op
BenchmarkGacheSetGetSmallDataNoTTL/P1000-128 3938966 292.6 ns/op 162 B/op 8 allocs/op
BenchmarkGacheSetGetSmallDataNoTTL/P10000-128 1315594 828.4 ns/op 237 B/op 9 allocs/op
BenchmarkGacheSetGetSmallDataWithTTL/P100-128 4069194 290.2 ns/op 160 B/op 8 allocs/op
BenchmarkGacheSetGetSmallDataWithTTL/P1000-128 3971908 290.7 ns/op 162 B/op 8 allocs/op
BenchmarkGacheSetGetSmallDataWithTTL/P10000-128 1327264 808.4 ns/op 239 B/op 9 allocs/op
BenchmarkGacheSetGetBigDataNoTTL/P100-128 111 10852804 ns/op 5252157 B/op 262376 allocs/op
BenchmarkGacheSetGetBigDataNoTTL/P1000-128 126 12960028 ns/op 5324244 B/op 264177 allocs/op
BenchmarkGacheSetGetBigDataNoTTL/P10000-128 30 33683216 ns/op 8656380 B/op 347484 allocs/op
BenchmarkGacheSetGetBigDataWithTTL/P100-128 43 23279869 ns/op 5732087 B/op 266737 allocs/op
BenchmarkGacheSetGetBigDataWithTTL/P1000-128 66 15942434 ns/op 5697604 B/op 268565 allocs/op
BenchmarkGacheSetGetBigDataWithTTL/P10000-128 44 23237133 ns/op 7893435 B/op 323972 allocs/op
BenchmarkTTLCacheSetGetSmallDataNoTTL/P100-128 882207 1298 ns/op 2 B/op 0 allocs/op
BenchmarkTTLCacheSetGetSmallDataNoTTL/P1000-128 845092 1543 ns/op 13 B/op 0 allocs/op
BenchmarkTTLCacheSetGetSmallDataNoTTL/P10000-128 3519 285093 ns/op 29142 B/op 727 allocs/op
BenchmarkTTLCacheSetGetSmallDataWithTTL/P100-128 387933 3810 ns/op 6 B/op 0 allocs/op
BenchmarkTTLCacheSetGetSmallDataWithTTL/P1000-128 390312 4000 ns/op 29 B/op 0 allocs/op
BenchmarkTTLCacheSetGetSmallDataWithTTL/P10000-128 29668 33910 ns/op 3506 B/op 86 allocs/op
BenchmarkTTLCacheSetGetBigDataNoTTL/P100-128 5 204745341 ns/op 207612 B/op 5177 allocs/op
BenchmarkTTLCacheSetGetBigDataNoTTL/P1000-128 5 224919335 ns/op 2050129 B/op 51255 allocs/op
BenchmarkTTLCacheSetGetBigDataNoTTL/P10000-128 5 218444703 ns/op 20483260 B/op 512064 allocs/op
BenchmarkTTLCacheSetGetBigDataWithTTL/P100-128 4 287848085 ns/op 259426 B/op 6476 allocs/op
BenchmarkTTLCacheSetGetBigDataWithTTL/P1000-128 4 302964096 ns/op 2561812 B/op 64064 allocs/op
BenchmarkTTLCacheSetGetBigDataWithTTL/P10000-128 4 309252153 ns/op 25602738 B/op 640073 allocs/op
BenchmarkGoCacheSetGetSmallDataNoTTL/P100-128 1929801 633.2 ns/op 65 B/op 4 allocs/op
BenchmarkGoCacheSetGetSmallDataNoTTL/P1000-128 2484928 789.5 ns/op 68 B/op 4 allocs/op
BenchmarkGoCacheSetGetSmallDataNoTTL/P10000-128 1936200 630.7 ns/op 117 B/op 5 allocs/op
BenchmarkGoCacheSetGetSmallDataWithTTL/P100-128 1224057 1691 ns/op 65 B/op 4 allocs/op
BenchmarkGoCacheSetGetSmallDataWithTTL/P1000-128 950708 1344 ns/op 76 B/op 4 allocs/op
BenchmarkGoCacheSetGetSmallDataWithTTL/P10000-128 855729 1377 ns/op 184 B/op 7 allocs/op
BenchmarkGoCacheSetGetBigDataNoTTL/P100-128 6 215690920 ns/op 2269766 B/op 135390 allocs/op
BenchmarkGoCacheSetGetBigDataNoTTL/P1000-128 6 230979864 ns/op 3805484 B/op 173790 allocs/op
BenchmarkGoCacheSetGetBigDataNoTTL/P10000-128 7 229134180 ns/op 16728165 B/op 496844 allocs/op
BenchmarkGoCacheSetGetBigDataWithTTL/P100-128 6 208563272 ns/op 2268909 B/op 135381 allocs/op
BenchmarkGoCacheSetGetBigDataWithTTL/P1000-128 5 204595908 ns/op 4146240 B/op 182314 allocs/op
BenchmarkGoCacheSetGetBigDataWithTTL/P10000-128 4 258577174 ns/op 27698782 B/op 771128 allocs/op
BenchmarkBigCacheSetGetSmallDataNoTTL/P100-128 270231 4398 ns/op 387 B/op 8 allocs/op
BenchmarkBigCacheSetGetSmallDataNoTTL/P1000-128 223383 4722 ns/op 351 B/op 9 allocs/op
BenchmarkBigCacheSetGetSmallDataNoTTL/P10000-128 242823 4873 ns/op 1399 B/op 18 allocs/op
BenchmarkBigCacheSetGetSmallDataWithTTL/P100-128 262276 4270 ns/op 398 B/op 8 allocs/op
BenchmarkBigCacheSetGetSmallDataWithTTL/P1000-128 295706 4142 ns/op 276 B/op 8 allocs/op
BenchmarkBigCacheSetGetSmallDataWithTTL/P10000-128 176874 6012 ns/op 633 B/op 22 allocs/op
BenchmarkBigCacheSetGetBigDataNoTTL/P100-128 1 1185592807 ns/op 1271035544 B/op 290139 allocs/op
BenchmarkBigCacheSetGetBigDataNoTTL/P1000-128 1 1709417994 ns/op 1870864472 B/op 519513 allocs/op
BenchmarkBigCacheSetGetBigDataNoTTL/P10000-128 1 1633921555 ns/op 2790072184 B/op 2823394 allocs/op
BenchmarkBigCacheSetGetBigDataWithTTL/P100-128 1 1315226054 ns/op 1271036280 B/op 290166 allocs/op
BenchmarkBigCacheSetGetBigDataWithTTL/P1000-128 1 1464488357 ns/op 1558084768 B/op 519305 allocs/op
BenchmarkBigCacheSetGetBigDataWithTTL/P10000-128 1 1191370621 ns/op 703706888 B/op 2822443 allocs/op
BenchmarkGCacheLRUSetGetSmallDataNoTTL/P100-128 343375 3183 ns/op 717 B/op 23 allocs/op
BenchmarkGCacheLRUSetGetSmallDataNoTTL/P1000-128 377926 3641 ns/op 733 B/op 24 allocs/op
BenchmarkGCacheLRUSetGetSmallDataNoTTL/P10000-128 332992 4056 ns/op 1014 B/op 31 allocs/op
BenchmarkGCacheLRUSetGetSmallDataWithTTL/P100-128 458796 3683 ns/op 293 B/op 16 allocs/op
BenchmarkGCacheLRUSetGetSmallDataWithTTL/P1000-128 390602 3041 ns/op 317 B/op 16 allocs/op
BenchmarkGCacheLRUSetGetSmallDataWithTTL/P10000-128 303390 3536 ns/op 628 B/op 24 allocs/op
BenchmarkGCacheLRUSetGetBigDataNoTTL/P100-128 5 226899462 ns/op 12579105 B/op 581883 allocs/op
BenchmarkGCacheLRUSetGetBigDataNoTTL/P1000-128 5 250336714 ns/op 14422416 B/op 627967 allocs/op
BenchmarkGCacheLRUSetGetBigDataNoTTL/P10000-128 5 243371795 ns/op 32855524 B/op 1088776 allocs/op
BenchmarkGCacheLRUSetGetBigDataWithTTL/P100-128 5 232806613 ns/op 12579201 B/op 581884 allocs/op
BenchmarkGCacheLRUSetGetBigDataWithTTL/P1000-128 5 232518008 ns/op 14422872 B/op 627969 allocs/op
BenchmarkGCacheLRUSetGetBigDataWithTTL/P10000-128 5 224906140 ns/op 32854968 B/op 1088768 allocs/op
BenchmarkGCacheLFUSetGetSmallDataNoTTL/P100-128 400503 3708 ns/op 530 B/op 19 allocs/op
BenchmarkGCacheLFUSetGetSmallDataNoTTL/P1000-128 388532 3537 ns/op 554 B/op 20 allocs/op
BenchmarkGCacheLFUSetGetSmallDataNoTTL/P10000-128 353187 3377 ns/op 821 B/op 27 allocs/op
BenchmarkGCacheLFUSetGetSmallDataWithTTL/P100-128 377215 2732 ns/op 294 B/op 16 allocs/op
BenchmarkGCacheLFUSetGetSmallDataWithTTL/P1000-128 475148 3714 ns/op 312 B/op 16 allocs/op
BenchmarkGCacheLFUSetGetSmallDataWithTTL/P10000-128 419940 3309 ns/op 533 B/op 22 allocs/op
BenchmarkGCacheLFUSetGetBigDataNoTTL/P100-128 5 235838146 ns/op 11321305 B/op 555674 allocs/op
BenchmarkGCacheLFUSetGetBigDataNoTTL/P1000-128 5 235307749 ns/op 13164232 B/op 601751 allocs/op
BenchmarkGCacheLFUSetGetBigDataNoTTL/P10000-128 5 218986777 ns/op 31596737 B/op 1062553 allocs/op
BenchmarkGCacheLFUSetGetBigDataWithTTL/P100-128 4 251297641 ns/op 11792154 B/op 563512 allocs/op
BenchmarkGCacheLFUSetGetBigDataWithTTL/P1000-128 5 235102039 ns/op 13164120 B/op 601750 allocs/op
BenchmarkGCacheLFUSetGetBigDataWithTTL/P10000-128 5 228952630 ns/op 31596086 B/op 1062549 allocs/op
BenchmarkGCacheARCSetGetSmallDataNoTTL/P100-128 272907 5860 ns/op 905 B/op 27 allocs/op
BenchmarkGCacheARCSetGetSmallDataNoTTL/P1000-128 278677 6286 ns/op 936 B/op 28 allocs/op
BenchmarkGCacheARCSetGetSmallDataNoTTL/P10000-128 211556 6138 ns/op 1386 B/op 39 allocs/op
BenchmarkGCacheARCSetGetSmallDataWithTTL/P100-128 293352 4129 ns/op 296 B/op 16 allocs/op
BenchmarkGCacheARCSetGetSmallDataWithTTL/P1000-128 454358 3600 ns/op 313 B/op 16 allocs/op
BenchmarkGCacheARCSetGetSmallDataWithTTL/P10000-128 237105 4603 ns/op 723 B/op 26 allocs/op
BenchmarkGCacheARCSetGetBigDataNoTTL/P100-128 2 577636447 ns/op 34417548 B/op 734857 allocs/op
BenchmarkGCacheARCSetGetBigDataNoTTL/P1000-128 3 381003655 ns/op 19842962 B/op 740771 allocs/op
BenchmarkGCacheARCSetGetBigDataNoTTL/P10000-128 3 358527355 ns/op 50563448 B/op 1508772 allocs/op
BenchmarkGCacheARCSetGetBigDataWithTTL/P100-128 2 597467738 ns/op 34417644 B/op 734861 allocs/op
BenchmarkGCacheARCSetGetBigDataWithTTL/P1000-128 3 389213407 ns/op 19843562 B/op 740778 allocs/op
BenchmarkGCacheARCSetGetBigDataWithTTL/P10000-128 3 384577490 ns/op 50562904 B/op 1508771 allocs/op
PASS
ok github.com/kpango/go-cache-lib-benchmarks 2326.540s
- Fork it ( https://github.com/kpango/gache/fork )
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create new Pull Request
gache released under MIT license, refer LICENSE file.
The Go Gopher character is licensed under the Creative Commons 4.0 Attribution license. The image was originally created by Renee French.
