govault

Documentation

Overview

GoVault is a basic server-side [key, value] caching solution that caches pretty much any data type as values and comparable types as their keys. It has a well configured LRU(Least Recently Used) eviction policy. The LRU policy depends on the capacity of the cache set by the using the `New[key, value](maxMB)` function.

Index

• type Cache
  • func New[Key comparable, Value any](maxMB int64) *Cache[Key, Value]
  • func (c *Cache[Key, Value]) Delete(key Key)
  • func (c *Cache[Key, Value]) Get(key Key) (Value, bool)
  • func (c *Cache[Key, Value]) Set(key Key, value Value)

Examples

• Cache.Delete
• Cache.Get
• Cache.Set
• New

Types

type Cache

type Cache[Key comparable, Value any] struct {
	Mutex       sync.Mutex            // Used to synchronize reads and writes to the cache
	Store       map[Key]*list.Element // List of stored elements in-cache
	EvictList   *list.List            // List to track access order for LRU
	MaxSize     int64                 // Max memory size in bytes
	CurrentSize int64                 // Current memory usage in bytes
}

Cache is a generic in-memory cache with a memory limit (measured in bytes).

func New

func New[Key comparable, Value any](maxMB int64) *Cache[Key, Value]

`govault.New[key, value](maxMB)` Create a new cache. `k` is the key type, it can only be a comparable type `v` is the value type, it can be pretty much any type, no restarins. `maxMB` is the maximum capacity of that created cache in Megabytes. The cache follows LRU(Least Recently Used) policy to determine which value to eject once the cache exceeds the specified limit.

Example

package main

import (
	"fmt"

	"github.com/drmorax/govault"
)

func main() {

	cache := govault.New[string, []int](10)

	fmt.Printf("%d bytes which is 10 Megabytes", cache.MaxSize)
}

Output:

10485760 bytes which is 10 Megabytes

func (*Cache[Key, Value]) Delete

func (c *Cache[Key, Value]) Delete(key Key)

Delete removes a key from the cache.

Example

package main

import (
	"fmt"

	"github.com/drmorax/govault"
)

func main() {
	cache := govault.New[string, []int](10)

	cache.Set("key-1", []int{1, 2, 3, 4, 5})

	output, found := cache.Get("key-1")
	fmt.Print("\nkey-1: ", output, found)

	cache.Delete("key-1")

	output, found = cache.Get("key-1")
	fmt.Print("\nkey-1: ", output, found)
}

Output:

key-1: [1 2 3 4 5] true
key-1: [] false

func (*Cache[Key, Value]) Get

func (c *Cache[Key, Value]) Get(key Key) (Value, bool)

Get retrieves a value from the cache by key and updates its LRU status to be evicted last.

Example

package main

import (
	"fmt"

	"github.com/drmorax/govault"
)

func main() {
	cache := govault.New[string, []int](10)

	cache.Set("key-1", []int{1, 2, 3, 4, 5})

	output, found := cache.Get("key-1")

	if !found {
		fmt.Println("Key doesn't exist")
	}

	fmt.Println(output)
}

Output:

[1 2 3 4 5]

func (*Cache[Key, Value]) Set

func (c *Cache[Key, Value]) Set(key Key, value Value)

Set adds or updates a key-value pair in the cache. If the cache exceeds the memory limit, it evicts the least recently used item. Once a pair is set or updated, it would be moved to the top of the eviction list meaning it would be the last pair to be evicted from memory

Example

package main

import (
	"fmt"

	"github.com/drmorax/govault"
)

func main() {
	cache := govault.New[string, []int](10)

	value := []int{1, 2, 3, 4, 5}

	cache.Set("key-1", value)

	output, found := cache.Get("key-1")

	if !found {
		fmt.Println("Key doesn't exist")
	}

	fmt.Println(output)
}

Output:

[1 2 3 4 5]