https://github.com/atomicgo/cache
🧠 A generic, thread-safe cache implementation in Go for improved performance!
https://github.com/atomicgo/cache
atomicgo cache go golang golang-library
Last synced: about 2 months ago
JSON representation
🧠 A generic, thread-safe cache implementation in Go for improved performance!
- Host: GitHub
- URL: https://github.com/atomicgo/cache
- Owner: atomicgo
- License: mit
- Created: 2022-11-25T14:09:04.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-09-13T11:30:43.000Z (9 months ago)
- Last Synced: 2024-10-22T15:48:13.759Z (8 months ago)
- Topics: atomicgo, cache, go, golang, golang-library
- Language: Go
- Homepage: https://atomicgo.dev
- Size: 56.6 KB
- Stars: 6
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
AtomicGo | cache
---
Documentation
|
Contributing
|
Code of Conduct
---
go get atomicgo.dev/cache
# cache
```go
import "atomicgo.dev/cache"
```
Package cache is a generic, fast and thread\-safe cache implementation to improve performance of your Go applications.
## Index
- [type Cache](<#type-cache>)
- [func New[T any](options ...Options) *Cache[T]](<#func-new>)
- [func (c *Cache[T]) Close()](<#func-cachet-close>)
- [func (c *Cache[T]) Contains(key string) bool](<#func-cachet-contains>)
- [func (c *Cache[T]) Delete(key string)](<#func-cachet-delete>)
- [func (c *Cache[T]) EnableAutoPurge(purgeInterval ...time.Duration) *Cache[T]](<#func-cachet-enableautopurge>)
- [func (c *Cache[T]) Expired(key string) bool](<#func-cachet-expired>)
- [func (c *Cache[T]) Get(key string) T](<#func-cachet-get>)
- [func (c *Cache[T]) GetEntry(key string) *Entry[T]](<#func-cachet-getentry>)
- [func (c *Cache[T]) GetExpiration(key string) time.Duration](<#func-cachet-getexpiration>)
- [func (c *Cache[T]) GetOrSet(key string, callback func() T, expiration ...time.Duration) T](<#func-cachet-getorset>)
- [func (c *Cache[T]) Keys() []string](<#func-cachet-keys>)
- [func (c *Cache[T]) Purge()](<#func-cachet-purge>)
- [func (c *Cache[T]) PurgeExpired()](<#func-cachet-purgeexpired>)
- [func (c *Cache[T]) Set(key string, value T, expiration ...time.Duration)](<#func-cachet-set>)
- [func (c *Cache[T]) SetExpiration(expiration time.Duration)](<#func-cachet-setexpiration>)
- [func (c *Cache[T]) Size() int](<#func-cachet-size>)
- [func (c *Cache[T]) StopAutoPurge()](<#func-cachet-stopautopurge>)
- [func (c *Cache[T]) ValidKeys() []string](<#func-cachet-validkeys>)
- [func (c *Cache[T]) ValidSize() int](<#func-cachet-validsize>)
- [func (c *Cache[T]) Values() []T](<#func-cachet-values>)
- [type Entry](<#type-entry>)
- [func (e Entry[T]) Expired() bool](<#func-entryt-expired>)
- [func (e *Entry[T]) SetExpiration(expiration time.Duration)](<#func-entryt-setexpiration>)
- [type Options](<#type-options>)
## type [Cache]()
Cache is a fast and thread\-safe cache implementation with expiration.
```go
type Cache[T any] struct {
Options Options
// contains filtered or unexported fields
}
```
### func [New]()
```go
func New[T any](options ...Options) *Cache[T]
```
New returns a new Cache. The default Expiration time is 0, which means no Expiration.
Example
```go
package main
import (
"atomicgo.dev/cache"
"time"
)
func main() {
// Create a cache for string values, without any options.
cache.New[string]()
// Create a cache for string values, with options.
cache.New[string](cache.Options{
DefaultExpiration: time.Second * 10,
})
// Create a cache for int values, without any options.
cache.New[int]()
// Create a cache for int values, with options.
cache.New[int](cache.Options{
DefaultExpiration: time.Second * 10,
})
// Create a cache for any values, without any options.
cache.New[any]()
// Create a cache for any values, with options.
cache.New[any](cache.Options{
DefaultExpiration: time.Second * 10,
})
}
```
### func \(\*Cache\[T\]\) [Close]()
```go
func (c *Cache[T]) Close()
```
Close purges the cache and stops the auto purge goroutine, if active.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
)
func main() {
c := cache.New[string]()
// Fill the cache with some values.
c.Set("1", "one")
c.Set("2", "two")
c.Set("3", "three")
// Close the cache.
c.Close()
// Get the size.
fmt.Println(c.Size())
}
```
#### Output
```
0
```
### func \(\*Cache\[T\]\) [Contains]()
```go
func (c *Cache[T]) Contains(key string) bool
```
Contains returns true if the key is in the cache, and the key is not expired.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
)
func main() {
c := cache.New[string]()
// Fill the cache with some values.
c.Set("1", "one")
c.Set("2", "two")
c.Set("3", "three")
// Check if the cache contains a key.
fmt.Println(c.Contains("1"))
fmt.Println(c.Contains("4"))
}
```
#### Output
```
true
false
```
### func \(\*Cache\[T\]\) [Delete]()
```go
func (c *Cache[T]) Delete(key string)
```
Delete removes the key from the cache.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
)
func main() {
c := cache.New[string]()
// Fill the cache with some values.
c.Set("1", "one")
c.Set("2", "two")
c.Set("3", "three")
// Delete a key.
c.Delete("3")
// Get the size.
fmt.Println(c.Size())
}
```
#### Output
```
2
```
### func \(\*Cache\[T\]\) [EnableAutoPurge]()
```go
func (c *Cache[T]) EnableAutoPurge(purgeInterval ...time.Duration) *Cache[T]
```
EnableAutoPurge starts a goroutine that purges expired keys from the cache. The interval is the time between purges. If the interval is 0, the default interval of the cache options is used. If the cache options do not specify a default interval, the default interval is 1 minute.
### func \(\*Cache\[T\]\) [Expired]()
```go
func (c *Cache[T]) Expired(key string) bool
```
Expired returns true if the key is expired.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"time"
)
func main() {
c := cache.New[string](cache.Options{
DefaultExpiration: time.Millisecond * 10,
})
// Set a value for a key.
c.Set("1", "one")
// Check if the key is expired.
fmt.Println(c.Expired("1"))
// Sleep for 10ms to let the key expire.
time.Sleep(time.Millisecond * 10)
// Check if the key is expired.
fmt.Println(c.Expired("1"))
}
```
#### Output
```
false
true
```
### func \(\*Cache\[T\]\) [Get]()
```go
func (c *Cache[T]) Get(key string) T
```
Get returns the value for a key. If the key does not exist, nil is returned. If the key is expired, the zero value is returned and the key is deleted.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
)
func main() {
c := cache.New[string]()
// Set a value for a key.
c.Set("1", "one")
// Get the value for a key.
fmt.Println(c.Get("1"))
}
```
#### Output
```
one
```
### func \(\*Cache\[T\]\) [GetEntry]()
```go
func (c *Cache[T]) GetEntry(key string) *Entry[T]
```
GetEntry returns the Entry for a key. If the key does not exist, nil is returned.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"time"
)
func main() {
c := cache.New[string](cache.Options{
DefaultExpiration: time.Second * 10,
})
// Set a value for a key.
c.Set("1", "one")
// Get the entry for a key.
entry := c.GetEntry("1")
fmt.Println(entry.Value)
fmt.Println(entry.Expiration)
}
```
#### Output
```
one
10s
```
### func \(\*Cache\[T\]\) [GetExpiration]()
```go
func (c *Cache[T]) GetExpiration(key string) time.Duration
```
GetExpiration returns the Expiration time for a key.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"time"
)
func main() {
c := cache.New[string](cache.Options{
DefaultExpiration: time.Second * 10,
})
// Set a value for a key.
c.Set("1", "one")
// Get the expiration for a key.
fmt.Println(c.GetExpiration("1"))
}
```
#### Output
```
10s
```
### func \(\*Cache\[T\]\) [GetOrSet]()
```go
func (c *Cache[T]) GetOrSet(key string, callback func() T, expiration ...time.Duration) T
```
GetOrSet returns the value for a key. If the key does not exist, the value is set to the result of the callback function and returned. If the key is expired, the value is set to the result of the callback function and returned.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
)
func main() {
c := cache.New[string]()
// Try to get or set a value for a key.
c.GetOrSet("1", func() string {
return "one"
})
fmt.Println(c.Get("1"))
// try to get or set a value for an existing key.
c.GetOrSet("1", func() string {
return "something else"
})
fmt.Println(c.Get("1"))
// delete the key
c.Delete("1")
// try to get or set a value for a non-existing key.
c.GetOrSet("1", func() string {
return "something else"
})
fmt.Println(c.Get("1"))
}
```
#### Output
```
one
one
something else
```
### func \(\*Cache\[T\]\) [Keys]()
```go
func (c *Cache[T]) Keys() []string
```
Keys returns a slice of all keys in the cache, expired or not.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"sort"
)
func main() {
c := cache.New[string]()
// Fill the cache with some values.
c.Set("1", "one")
c.Set("2", "two")
c.Set("3", "three")
// Get the keys.
keys := c.Keys()
sort.Strings(keys)
fmt.Println(keys)
}
```
#### Output
```
[1 2 3]
```
### func \(\*Cache\[T\]\) [Purge]()
```go
func (c *Cache[T]) Purge()
```
Purge removes all keys from the cache.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
)
func main() {
c := cache.New[string]()
// Fill the cache with some values.
c.Set("1", "one")
c.Set("2", "two")
c.Set("3", "three")
// Purge the cache.
c.Purge()
// Check if the cache is empty.
fmt.Println(c.Size())
}
```
#### Output
```
0
```
### func \(\*Cache\[T\]\) [PurgeExpired]()
```go
func (c *Cache[T]) PurgeExpired()
```
PurgeExpired removes all expired keys from the cache.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"time"
)
func main() {
c := cache.New[string](cache.Options{
DefaultExpiration: time.Second,
})
// Fill the cache with some values.
c.Set("1", "one", time.Millisecond*10)
c.Set("2", "two", time.Millisecond*10)
c.Set("3", "three")
// Purge the expired keys.
c.PurgeExpired()
fmt.Println(c.Size())
// Sleep for 10ms to let the first two keys expire.
time.Sleep(time.Millisecond * 10)
// Purge the expired keys.
c.PurgeExpired()
fmt.Println(c.Size())
}
```
#### Output
```
3
1
```
### func \(\*Cache\[T\]\) [Set]()
```go
func (c *Cache[T]) Set(key string, value T, expiration ...time.Duration)
```
Set sets the value for a key. If the key already exists, the value is overwritten. If the Expiration time is 0, the default Expiration time is used.
Example
```go
package main
import (
"atomicgo.dev/cache"
"time"
)
func main() {
c := cache.New[string]()
// Set a value for a key.
c.Set("1", "one")
// Set a value for a key with a custom expiration.
c.Set("2", "two", time.Second*10)
}
```
### func \(\*Cache\[T\]\) [SetExpiration]()
```go
func (c *Cache[T]) SetExpiration(expiration time.Duration)
```
SetExpiration sets the Expiration time all keys in the cache.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"time"
)
func main() {
c := cache.New[string](cache.Options{
DefaultExpiration: time.Second * 10,
})
// Set a value for a key.
c.Set("1", "one")
c.Set("2", "two")
c.Set("3", "three", time.Second*1337)
// Set the expiration for a key.
c.SetExpiration(time.Second * 20)
// Get the expiration for a key.
fmt.Println(c.GetExpiration("1"))
fmt.Println(c.GetExpiration("2"))
fmt.Println(c.GetExpiration("3"))
}
```
#### Output
```
20s
20s
20s
```
### func \(\*Cache\[T\]\) [Size]()
```go
func (c *Cache[T]) Size() int
```
Size returns the number of keys in the cache, expired or not.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
)
func main() {
c := cache.New[string]()
// Fill the cache with some values.
c.Set("1", "one")
c.Set("2", "two")
c.Set("3", "three")
// Get the size.
fmt.Println(c.Size())
}
```
#### Output
```
3
```
### func \(\*Cache\[T\]\) [StopAutoPurge]()
```go
func (c *Cache[T]) StopAutoPurge()
```
StopAutoPurge stops the auto purge goroutine.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"time"
)
func main() {
c := cache.New[string](cache.Options{
AutoPurgeInterval: time.Millisecond * 10,
})
c.EnableAutoPurge()
// Fill the cache with some values.
c.Set("1", "one")
c.Set("2", "two")
c.Set("3", "three")
// Stop the auto purge.
c.StopAutoPurge()
// Sleep for 10 milliseconds to let the auto purge run.
time.Sleep(time.Millisecond * 10)
// Get the size.
fmt.Println(c.Size())
}
```
#### Output
```
3
```
### func \(\*Cache\[T\]\) [ValidKeys]()
```go
func (c *Cache[T]) ValidKeys() []string
```
ValidKeys returns a slice of all valid keys in the cache.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"sort"
"time"
)
func main() {
c := cache.New[string]()
// Fill the cache with some values.
c.Set("1", "one")
c.Set("2", "two")
c.Set("3", "three")
c.Set("expiresSoon", "data", time.Millisecond*10)
validKeys := c.ValidKeys()
sort.Strings(validKeys)
fmt.Println(validKeys)
// Sleep for 10ms to let the "expiresSoon" key expire.
time.Sleep(time.Millisecond * 10)
// Get the valid keys.
validKeys = c.ValidKeys()
sort.Strings(validKeys)
fmt.Println(validKeys)
}
```
#### Output
```
[1 2 3 expiresSoon]
[1 2 3]
```
### func \(\*Cache\[T\]\) [ValidSize]()
```go
func (c *Cache[T]) ValidSize() int
```
ValidSize returns the number of keys in the cache that are not expired.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"time"
)
func main() {
c := cache.New[string]()
// Fill the cache with some values.
c.Set("1", "one")
c.Set("2", "two")
c.Set("3", "three")
c.Set("expiresSoon", "data", time.Millisecond*10)
fmt.Println(c.ValidSize())
// Sleep for 10ms to let the "expiresSoon" key expire.
time.Sleep(time.Millisecond * 10)
// Get the valid size.
fmt.Println(c.ValidSize())
}
```
#### Output
```
4
3
```
### func \(\*Cache\[T\]\) [Values]()
```go
func (c *Cache[T]) Values() []T
```
Values returns a slice of all values in the cache.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"sort"
)
func main() {
c := cache.New[string]()
// Fill the cache with some values.
c.Set("1", "one")
c.Set("2", "two")
c.Set("3", "three")
// Get the values.
values := c.Values()
sort.Strings(values)
fmt.Println(values)
}
```
#### Output
```
[one three two]
```
## type [Entry]()
Entry is a cache entry.
```go
type Entry[T any] struct {
Value T
CachedAt time.Time
Expiration time.Duration
}
```
### func \(Entry\[T\]\) [Expired]()
```go
func (e Entry[T]) Expired() bool
```
Expired returns if the Entry is expired.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"time"
)
func main() {
c := cache.New[string](cache.Options{
DefaultExpiration: time.Millisecond * 10,
})
// Set a value for a key.
c.Set("1", "one")
// Get the entry for a key.
entry := c.GetEntry("1")
// Check if the entry is expired.
fmt.Println(entry.Expired())
// Sleep for 10ms to let the entry expire.
time.Sleep(time.Millisecond * 10)
// Check if the entry is expired.
fmt.Println(entry.Expired())
}
```
#### Output
```
false
true
```
### func \(\*Entry\[T\]\) [SetExpiration]()
```go
func (e *Entry[T]) SetExpiration(expiration time.Duration)
```
SetExpiration sets the Expiration time for the Entry.
Example
```go
package main
import (
"atomicgo.dev/cache"
"fmt"
"time"
)
func main() {
c := cache.New[string](cache.Options{
DefaultExpiration: time.Second * 10,
})
// Set a value for a key.
c.Set("1", "one")
// Get the entry for a key.
entry := c.GetEntry("1")
// Set the expiration for the entry.
entry.SetExpiration(time.Second * 20)
// Get the expiration for a key.
fmt.Println(c.GetExpiration("1"))
}
```
#### Output
```
20s
```
## type [Options]()
Options can be passed to New to configure the cache.
```go
type Options struct {
DefaultExpiration time.Duration
AutoPurgeInterval time.Duration
}
```
Generated by [gomarkdoc]()
---
> [AtomicGo.dev](https://atomicgo.dev) ·
> with ❤️ by [@MarvinJWendt](https://github.com/MarvinJWendt) |
> [MarvinJWendt.com](https://marvinjwendt.com)