cache

Documentation

Index

• type LRU
  • func NewLRU(opts *LRUOpts) *LRU
  • func (lru *LRU) Lookup(ctx context.Context, url string, loadOnMiss pokeapi.CacheLoader) (any, error)
• type LRUOpts
• type Wrapper
  • func NewWrapper(getFn func(ctx context.Context, url string) (any, bool), ...) *Wrapper
  • func (w *Wrapper) Lookup(ctx context.Context, url string, loadOnMiss pokeapi.CacheLoader) (any, error)

Types

type LRU

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

LRU implements a Least-Recently-Used pokeapi.Cache. An LRU cache is a queue-like structure, with some extra semantics on Lookup & a map to allow for O(1) lookups:

- On Lookup, if a cache hit occurs, the entry is moved to the top of the list (it is now the youngest entry).

- On Put, the entry is moved to/inserted at the top of the list. If an insert causes the length of the list to exceed the cache capacity, the oldest entry is dropped. A Put occurs on the first call to pokeapi.CacheLookup.Hydrate on a pokeapi.CacheLookup returned by LRU.Lookup (as long as pokeapi.CacheLookup.Close has not yet been called).

If multiple cache lookups are opened for the same url, the LRU cache will ensure that they are not executed in parallel - instead ensuring these lookups occur one-after-another. Parallel cache lookups for multiple urls will be serviced as normal.

func NewLRU

func NewLRU(opts *LRUOpts) *LRU

NewLRU constructs a new LRU cache for use. It can hold at most `size` entries, and once that limit is exceeded the least-recently-used (read or written) cache entry will be evicted. If `size` <= 0, the default cache size of 50 will be used. A TTL may also be provided, and when it is expired cached items will be evicted after the first call to Lookup after they become too old.

func (*LRU) Lookup

func (lru *LRU) Lookup(
	ctx context.Context,
	url string,
	loadOnMiss pokeapi.CacheLoader,
) (any, error)

type LRUOpts

type LRUOpts struct {
	Size int // The maximum capacity of the cache. Default 50.

	Clock func() time.Time // Provide a custom time function - useful for testing
	TTL   time.Duration    // How long cached entries should be stored for. Default 0 (forever)

	// How long to wait between expiry runs. Default ~1 week. If set to 0, will
	// check for expired keys every Lookup. Only applies if TTL != 0.
	ExpiryDelay *time.Duration
}

type Wrapper

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

The Wrapper cache wraps a standard get/put cache and converts it to the transactional pokeapi.Cache interface. It's useful if you want to make use of the pokeapi.Client's concurrency guarantees.

func NewWrapper

func NewWrapper(
	getFn func(ctx context.Context, url string) (any, bool),
	putFn func(ctx context.Context, url string, value any),
) *Wrapper

NewWrapper accepts the Get and Put (or equivalent) method references of the cache it wraps and returns a pokeapi.Cache that loads and stores values from/to that cache.

Example usage:

r := NewRedisCache(redisConn, defaultTTL)
c := pokeapi.Client(
	&pokeapi.ClientOpts{
		Cache: cache.NewWrapper(r.Get, r.Put),
	}
)

It's worth noting that the url passed will be the raw url, query parameters included. Advanced cache implementations may choose to make use of this.

func (*Wrapper) Lookup

func (w *Wrapper) Lookup(
	ctx context.Context,
	url string,
	loadOnMiss pokeapi.CacheLoader,
) (any, error)