AtomicGo | cache

---

Documentation | Contributing | Code of Conduct

---

go get atomicgo.dev/cache

cache

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
  • func New[T any](options ...Options) *Cache[T]
  • func (c *Cache[T]) Close()
  • func (c *Cache[T]) Contains(key string) bool
  • func (c *Cache[T]) Delete(key string)
  • func (c *Cache[T]) EnableAutoPurge(purgeInterval ...time.Duration) *Cache[T]
  • func (c *Cache[T]) Expired(key string) bool
  • func (c *Cache[T]) Get(key string) T
  • func (c *Cache[T]) GetEntry(key string) *Entry[T]
  • func (c *Cache[T]) GetExpiration(key string) time.Duration
  • func (c *Cache[T]) GetOrSet(key string, callback func() T, expiration ...time.Duration) T
  • func (c *Cache[T]) Keys() []string
  • func (c *Cache[T]) Purge()
  • func (c *Cache[T]) PurgeExpired()
  • func (c *Cache[T]) Set(key string, value T, expiration ...time.Duration)
  • func (c *Cache[T]) SetExpiration(expiration time.Duration)
  • func (c *Cache[T]) Size() int
  • func (c *Cache[T]) StopAutoPurge()
  • func (c *Cache[T]) ValidKeys() []string
  • func (c *Cache[T]) ValidSize() int
  • func (c *Cache[T]) Values() []T
• type Entry
  • func (e Entry[T]) Expired() bool
  • func (e *Entry[T]) SetExpiration(expiration time.Duration)
• type Options

type Cache

Cache is a fast and thread-safe cache implementation with expiration.

typeCache[Tany] struct {
OptionsOptions// contains filtered or unexported fields
}

func New

funcNew[Tany](options...Options) *Cache[T]

New returns a new Cache. The default Expiration time is 0, which means no Expiration.

package main
import (
"time""atomicgo.dev/cache"
)
funcmain() {
// 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

func (c*Cache[T]) Close()

Close purges the cache and stops the auto purge goroutine, if active.

package main
import (
"fmt""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) Contains(keystring) bool

Contains returns true if the key is in the cache, and the key is not expired.

package main
import (
"fmt""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) Delete(keystring)

Delete removes the key from the cache.

package main
import (
"fmt""atomicgo.dev/cache"
)
funcmain() {
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

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

func (c*Cache[T]) Expired(keystring) bool

Expired returns true if the key is expired.

package main
import (
"fmt""time""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) Get(keystring) 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.

package main
import (
"fmt""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) GetEntry(keystring) *Entry[T]

GetEntry returns the Entry for a key. If the key does not exist, nil is returned.

package main
import (
"fmt""time""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) GetExpiration(keystring) time.Duration

GetExpiration returns the Expiration time for a key.

package main
import (
"fmt""time""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) GetOrSet(keystring, callbackfunc() 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.

package main
import (
"fmt""atomicgo.dev/cache"
)
funcmain() {
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 keyc.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

func (c*Cache[T]) Keys() []string

Keys returns a slice of all keys in the cache, expired or not.

package main
import (
"fmt""sort""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) Purge()

Purge removes all keys from the cache.

package main
import (
"fmt""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) PurgeExpired()

PurgeExpired removes all expired keys from the cache.

package main
import (
"fmt""time""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) Set(keystring, valueT, 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.

package main
import (
"time""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) SetExpiration(expiration time.Duration)

SetExpiration sets the Expiration time all keys in the cache.

package main
import (
"fmt""time""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) Size() int

Size returns the number of keys in the cache, expired or not.

package main
import (
"fmt""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) StopAutoPurge()

StopAutoPurge stops the auto purge goroutine.

package main
import (
"fmt""time""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) ValidKeys() []string

ValidKeys returns a slice of all valid keys in the cache.

package main
import (
"fmt""sort""time""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) ValidSize() int

ValidSize returns the number of keys in the cache that are not expired.

package main
import (
"fmt""time""atomicgo.dev/cache"
)
funcmain() {
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

func (c*Cache[T]) Values() []T

Values returns a slice of all values in the cache.

package main
import (
"fmt""sort""atomicgo.dev/cache"
)
funcmain() {
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.

typeEntry[Tany] struct {
ValueTCachedAt time.TimeExpiration time.Duration
}

func (Entry[T]) Expired

func (eEntry[T]) Expired() bool

Expired returns if the Entry is expired.

package main
import (
"fmt""time""atomicgo.dev/cache"
)
funcmain() {
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

func (e*Entry[T]) SetExpiration(expiration time.Duration)

SetExpiration sets the Expiration time for the Entry.

package main
import (
"fmt""time""atomicgo.dev/cache"
)
funcmain() {
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.

typeOptionsstruct {
DefaultExpiration time.DurationAutoPurgeInterval time.Duration
}

Generated by gomarkdoc

---

AtomicGo.dev · with ❤️ by @MarvinJWendt | mjw.dev