cache

Documentation

Overview

Package cache provides a simple LRU cache featuring coupled linked list and map data structures to allow for easy lookups and ordered entries.

Index

• Constants
• Variables
• func HydrateParams(paramMap map[string]string, routePatternTemplates []string) []string
• func MemUsage() uint64
• func ToBytes(size uint64, unit string) (uint64, error)
• type CacheData
  • func NewCacheDataFromJSON(jsonData []byte) CacheData
  • func (data *CacheData) SetHeaders(ctx *fiber.Ctx)
• type CacheEntry
  • func (entry CacheEntry) Data() *CacheData
  • func (entry CacheEntry) Key() string
  • func (entry *CacheEntry) Next() *CacheEntry
  • func (entry *CacheEntry) Prev() *CacheEntry
  • func (entry *CacheEntry) SetNext(newEntry *CacheEntry) *CacheEntry
• type LRUCache
  • func New(capacity uint64, capacityUnit string) *LRUCache
  • func (cache *LRUCache) Bust(keys ...string)
  • func (cache *LRUCache) CachedKeys() []string
  • func (cache LRUCache) Entries() map[string]*CacheEntry
  • func (cache *LRUCache) EvictLRU() *CacheEntry
  • func (cache *LRUCache) Get(key string) *CacheData
  • func (cache LRUCache) LRU() *CacheEntry
  • func (cache LRUCache) MRU() *CacheEntry
  • func (cache *LRUCache) Match(patterns []string, paramMap map[string]string) []string
  • func (cache *LRUCache) MoveToMRU(entry *CacheEntry)
  • func (cache *LRUCache) Set(key string, data *CacheData)
  • func (cache *LRUCache) SetFirst(entry *CacheEntry) *CacheEntry
  • func (cache *LRUCache) Size() int
• type Set
  • func (set Set[T]) Add(elem T)
  • func (set Set[T]) Elements() []T
  • func (set Set[T]) Has(element T) bool
  • func (set Set[T]) Remove(element T)

Constants

const (
	B uint64 = 1 << (10 * iota)
	KB
	MB
	GB
	TB
)

Variables

var VALID_CAP_UNITS = []string{"B", "KB", "MB", "GB", "TB"}

Functions

func HydrateParams

func HydrateParams(paramMap map[string]string, routePatternTemplates []string) []string

HydrateParams rakes route patterns (strings to turn into regex) and a map of all route params in a route handler (ctx.AllParams()) and returns the routePattern with route params replaced with their arguments. Example: will replace /users/:id with /users/123 when given map[id:123]

func MemUsage

func MemUsage() uint64

MemUsage returns the current memory being used in bytes.

func ToBytes

func ToBytes(size uint64, unit string) (uint64, error)

Converts kb, mb, gb, tb to bytes. If the unit is not set, it will return the size passed into the function as if they are already in bytes.

Types

type CacheData

type CacheData struct {
	Headers map[string]string // we don't need to stringify headers
	Body    []byte            `json:"body"`
}

CacheData is used to represent the headers and body of an API response.

func NewCacheDataFromJSON

func NewCacheDataFromJSON(jsonData []byte) CacheData

NewCacheDataFromJSON takes marshaled json data (from cache) and returns it as hydrated CacheData. It is used when reading serialized data (headers and body) from the cache.

func (*CacheData) SetHeaders

func (data *CacheData) SetHeaders(ctx *fiber.Ctx)

SetHeaders will add all of the CacheData headers to the fiber context of a route handler. This is used when sending cached data to the client to make sure the headers are also the same as the original API response.

type CacheEntry

type CacheEntry struct {
	// contains filtered or unexported fields
}

CacheEntry is used to represent one entry in the LRUCache. It is like a node in a linked list.

func (CacheEntry) Data

func (entry CacheEntry) Data() *CacheData

Data returns the data of the entry encoded in whichever way it was saved in CacheData.

func (CacheEntry) Key

func (entry CacheEntry) Key() string

Key returns the key of the entry.

func (*CacheEntry) Next

func (entry *CacheEntry) Next() *CacheEntry

Next returns the next entry in the cache.

func (*CacheEntry) Prev

func (entry *CacheEntry) Prev() *CacheEntry

Prev returns the previous entry in the cache.

func (*CacheEntry) SetNext

func (entry *CacheEntry) SetNext(newEntry *CacheEntry) *CacheEntry

SetNext will insert a newEntry after the current entry in the linked list.

type LRUCache

type LRUCache struct {
	// contains filtered or unexported fields
}

LRUCache represents all entries in the cache, it's capacity limit, and the first and last entries.

func New

func New(capacity uint64, capacityUnit string) *LRUCache

New returns an LRUCache with the given capacity and optionally a unit to use memory-based cache limit. To use partial memory units, use whole units of lower size instead (e.g. 1.5kb == 1536b). TODO: handle the passed cap unit

func (*LRUCache) Bust

func (cache *LRUCache) Bust(keys ...string)

Bust will remove all entries saved under the given keys from the cache.

func (*LRUCache) CachedKeys

func (cache *LRUCache) CachedKeys() []string

CachedKeys returns a slice of the keys of all cached entries. NOTE: Does not always return keys in the order they were added.

func (LRUCache) Entries

func (cache LRUCache) Entries() map[string]*CacheEntry

func (*LRUCache) EvictLRU

func (cache *LRUCache) EvictLRU() *CacheEntry

EvictLRU removes the least recently used entry from the cache to make room for new entries.

func (*LRUCache) Get

func (cache *LRUCache) Get(key string) *CacheData

Get returns the CacheData of the entry saved under the given key.

func (LRUCache) LRU

func (cache LRUCache) LRU() *CacheEntry

func (LRUCache) MRU

func (cache LRUCache) MRU() *CacheEntry

func (*LRUCache) Match

func (cache *LRUCache) Match(patterns []string, paramMap map[string]string) []string

Match returns a slice of keys of the entries in the cache that match the given patterns. The patterns are hydrated with URL parameters from paramMap before being compiled as regex. If an empty slice of patterns is passed, all keys are returned (matching everything).

func (*LRUCache) MoveToMRU

func (cache *LRUCache) MoveToMRU(entry *CacheEntry)

MoveToMRU moves the given entry to the most recently used position in the cache. NOTE: Must be used on existing entry, cannot be used to add new entries.

func (*LRUCache) Set

func (cache *LRUCache) Set(key string, data *CacheData)

Set saves an entry with the given CacheData under the given key in the cache.

func (*LRUCache) SetFirst

func (cache *LRUCache) SetFirst(entry *CacheEntry) *CacheEntry

SetFirst sets the given entry as the first entry in the cache. This is used because it takes som special setup to add the first node to a linked list.

func (*LRUCache) Size

func (cache *LRUCache) Size() int

Size returns the number of entries currently saved in the cache.

type Set

type Set[T comparable] map[T]void

Set is like a slice with only unique values. It is used for finding unique cache entry keys matched by bust-patterns, because multiple patterns can match same key, and we don't need more than one to bust it from cache.

func (Set[T]) Add

func (set Set[T]) Add(elem T)

func (Set[T]) Elements

func (set Set[T]) Elements() []T

Elements returns a slice of all the elements of the set.

func (Set[T]) Has

func (set Set[T]) Has(element T) bool

Has returns true if the given element is in the set.

func (Set[T]) Remove

func (set Set[T]) Remove(element T)

Remove will delete the given element from the set.