<h1 align="center">AtomicGo | cache</h1> <p align="center"> <img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fatomicgo.dev%2Fapi%2Fshields%2Fcache&style=flat-square" alt="Downloads"> <a href="https://github.com/atomicgo/cache/releases"> <img src="https://img.shields.io/github/v/release/atomicgo/cache?style=flat-square" alt="Latest Release"> </a> <a href="https://codecov.io/gh/atomicgo/cache" target="_blank"> <img src="https://img.shields.io/github/actions/workflow/status/atomicgo/cache/go.yml?style=flat-square" alt="Tests"> </a> <a href="https://codecov.io/gh/atomicgo/cache" target="_blank"> <img src="https://img.shields.io/codecov/c/gh/atomicgo/cache?color=magenta&logo=codecov&style=flat-square" alt="Coverage"> </a> <a href="https://codecov.io/gh/atomicgo/cache"> <!-- unittestcount:start --><img src="https://img.shields.io/badge/Unit_Tests-38-magenta?style=flat-square" alt="Unit test count"><!-- unittestcount:end --> </a> <a href="https://opensource.org/licenses/MIT" target="_blank"> <img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT"> </a> <a href="https://goreportcard.com/report/github.com/atomicgo/cache" target="_blank"> <img src="https://goreportcard.com/badge/github.com/atomicgo/cache?style=flat-square" alt="Go report"> </a> </p>

---

<p align="center"> <strong><a href="https://pkg.go.dev/atomicgo.dev/cache#section-documentation" target="_blank">Documentation</a></strong> | <strong><a href="https://github.com/atomicgo/atomicgo/blob/main/CONTRIBUTING.md" target="_blank">Contributing</a></strong> | <strong><a href="https://github.com/atomicgo/atomicgo/blob/main/CODE_OF_CONDUCT.md" target="_blank">Code of Conduct</a></strong> </p>

---

<p align="center"> <img src="https://raw.githubusercontent.com/atomicgo/atomicgo/main/assets/header.png" alt="AtomicGo"> </p> <p align="center"> <table> <tbody> </tbody> </table> </p> <h3 align="center"><pre>go get atomicgo.dev/cache</pre></h3> <p align="center"> <table> <tbody> </tbody> </table> </p> <!-- gomarkdoc:embed:start --> <!-- Code generated by gomarkdoc. DO NOT EDIT -->

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.

type Cache[T any] struct {
    Options Options
    // contains filtered or unexported fields
}

func New

func New[T any](options ...Options) *Cache[T]

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

<details><summary>Example</summary> <p>

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,
	})
}

</p> </details>

func (*Cache[T]) Close

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

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

<details><summary>Example</summary> <p>

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

</p> </details>

func (*Cache[T]) Contains

func (c *Cache[T]) Contains(key string) bool

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

<details><summary>Example</summary> <p>

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

</p> </details>

func (*Cache[T]) Delete

func (c *Cache[T]) Delete(key string)

Delete removes the key from the cache.

<details><summary>Example</summary> <p>

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

</p> </details>

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(key string) bool

Expired returns true if the key is expired.

<details><summary>Example</summary> <p>

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

</p> </details>

func (*Cache[T]) Get

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.

<details><summary>Example</summary> <p>

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

</p> </details>

func (*Cache[T]) GetEntry

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.

<details><summary>Example</summary> <p>

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

</p> </details>

func (*Cache[T]) GetExpiration

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

GetExpiration returns the Expiration time for a key.

<details><summary>Example</summary> <p>

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 exp