cache

README

Cache

A minimalistic Time aware Least Recently Used (TLRU) cache implementation.

If you need something quick and simple to use in your tests, or you don't want to install another component just to keep some hot data in the memory, this package is for you.

It is not intended to be used as a storage. To keep your application from eating up your memory, you can set limit on number of items, or number of stored bytes.

Performance was not a major driving force behind this package, but there is not a lot going on so you can expect fair performance. Feel free to benchmark it and make a PR. ;)

A word about Time awareness: entries in the cache are not actively deleted based on TTL. The TTL of an entry is evaluated upon accessing the entry; expired entries are deleted only on an attempt to retrieve them. In other words, if nothing fetches an entry, it will only be deleted when it becomes the least recently used entry, which is inevitable eventually. As a result of this, the cache is only time aware in terms of keeping stale data inaccessible for fetch requests, but it's not actively freeing up memory.

Installation

go get github.com/zgiber/cache

Usage

See the examples directory.

Documentation

Index

• Variables
• func MaxBytesLimit(b uint) cacheOption
• func MaxItemLimit(l uint) cacheOption
• type Cache
• type MemCache
  • func NewMemCache(opts ...cacheOption) *MemCache
  • func (m *MemCache) Delete(key string) error
  • func (m *MemCache) Fetch(key string) ([]byte, error)
  • func (m *MemCache) Set(key string, value []byte, exp time.Duration) error

Variables

var (
	// ErrNotFound is returned when the cache
	// is consulted for an item which does not
	// exist in it.
	ErrNotFound = errors.New("not found")

	// DefaultBytesLimit is the initial capacity of
	// the memcache in terms of total bytes stored.
	// It can be set by using the MaxBytesLimit option
	// with a different value during initialization.
	DefaultBytesLimit = uint(64 * 1024 * 1024) // 64MB

	// DefaultItemLimit is the initial capacity of
	// the memcache in terms of total items stored.
	// It can be set by using the MaxItemLimit option
	// with a different value during initialization.
	DefaultItemLimit = uint(64 * 1024 * 4) // ~256K items
)

Functions

func MaxBytesLimit

func MaxBytesLimit(b uint) cacheOption

MaxBytesLimit sets the maximum total size of items the cache can hold. When this limit is exceeded, the least accessed item gets deleted from the cache.

func MaxItemLimit

func MaxItemLimit(l uint) cacheOption

MaxItemLimit sets the maximum number of items the cache can hold. When this limit is exceeded, the least accessed item gets deleted from the cache.

Types

type Cache

type Cache interface {
	Fetch(key string) ([]byte, error)
	Set(key string, value []byte, exp time.Duration) error
	Delete(key string) error
}

Cache is the interface for basic cache impementations

type MemCache

type MemCache struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

func NewMemCache

func NewMemCache(opts ...cacheOption) *MemCache

NewMemCache returns an in-memory implementation of the Cache interface.

func (*MemCache) Delete

func (m *MemCache) Delete(key string) error

Delete removes an item from the cache.

func (*MemCache) Fetch

func (m *MemCache) Fetch(key string) ([]byte, error)

Fetch retrieves an item from the cache. Frequently accessed items are less likely to be evicted.

func (*MemCache) Set

func (m *MemCache) Set(key string, value []byte, exp time.Duration) error

Set writes an item in the cache.