webcache

README

webcache

Documentation

Overview

Package webcache is A simple LRU cache for storing documents ([]byte). When the size maximum is reached, items are evicted starting with the least recently used. This data structure is goroutine-safe (it has a lock around all operations).

Index

• Variables
• type Bucket
  • func NewBucket(capacity int64) *Bucket
  • func (c *Bucket) AddGroup(group string, maxAge time.Duration, getter Getter) error
  • func (c *Bucket) Delete(group, key string)
  • func (c *Bucket) Get(ctx context.Context, group, key, etag string) ([]byte, *CacheInfo, error)
  • func (c *Bucket) Set(group, key string, value []byte) *CacheInfo
  • func (c *Bucket) Stats() *CacheStats
• type CacheInfo
• type CacheManager
• type CacheStats
• type Config
• type Getter
• type WebCache
  • func NewWebCache(cfg *Config) *WebCache
  • func (c *WebCache) AddGroup(group string, maxAge time.Duration, getter Getter) error
  • func (c *WebCache) BucketStats() []*CacheStats
  • func (c *WebCache) Delete(group string, key string)
  • func (c *WebCache) Get(ctx context.Context, group, key, etag string) ([]byte, *CacheInfo, error)
  • func (c *WebCache) Set(group, key string, value []byte) *CacheInfo
  • func (c *WebCache) Stats() *CacheStats

Variables

var NeverExpire = time.Hour*24*365*10 ^ 11 // about 100 billion years

NeverExpire is used to indicate that you want data in the specified group to never expire. It's set to a very large duration to represent "never expire".

Types

type Bucket

type Bucket struct {
	sync.Mutex
	// contains filtered or unexported fields
}

Bucket is a simple LRU cache with Etag support

func NewBucket

func NewBucket(capacity int64) *Bucket

NewBucket creates a new Cache with a maximum size of capacity bytes.

func (*Bucket) AddGroup

func (c *Bucket) AddGroup(group string, maxAge time.Duration, getter Getter) error

AddGroup adds a new cache group with a getter function

func (*Bucket) Delete

func (c *Bucket) Delete(group, key string)

Delete the value indicated by the key, if it is present.

func (*Bucket) Get

func (c *Bucket) Get(ctx context.Context, group, key, etag string) ([]byte, *CacheInfo, error)

Get retrieves a value from the cache or nil if no value present.

func (*Bucket) Set

func (c *Bucket) Set(group, key string, value []byte) *CacheInfo

Set inserts some {key, value} into the cache.

func (*Bucket) Stats

func (c *Bucket) Stats() *CacheStats

Stats returns statistics about this Bucket

type CacheInfo

type CacheInfo struct {
	Expires time.Time
	Cost    time.Duration
	Etag    string
}

CacheInfo stores the etag of the cache entry, when it expires and the cost in time that the getter function took to create the content.

type CacheManager

type CacheManager interface {
	AddGroup(string, time.Duration, Getter) error
	Delete(string, string)
	Get(context.Context, string, string, string) ([]byte, *CacheInfo, error)
	Set(string, string, []byte) *CacheInfo
	Stats() *CacheStats
}

CacheManager is an interface for either a Bucket or WebCache

type CacheStats

type CacheStats struct {
	EtagHits    atomic.Int64
	CacheHits   atomic.Int64
	GetCalls    atomic.Int64
	GetDupes    atomic.Int64
	GetErrors   atomic.Int64
	GetMisses   atomic.Int64
	TrimEntries atomic.Int64
	TrimBytes   atomic.Int64
	Capacity    atomic.Int64
	Size        atomic.Int64
}

CacheStats keeps track of cache statistics

type Config

type Config struct {
	Capacity int64 `json:"capacity"`
	Buckets  int   `json:"buckets"`
}

Config contains values to construct a NewWebCache

type Getter

type Getter interface {
	Get(ctx context.Context, key string) ([]byte, error)
}

Getter defines an interface for retrieving emptty cache contents

type WebCache

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

WebCache is a sharded cache with a specified number of buckets.

func NewWebCache

func NewWebCache(cfg *Config) *WebCache

NewWebCache creates a new WebCache with a maximum size of capacity bytes.

func (*WebCache) AddGroup

func (c *WebCache) AddGroup(group string, maxAge time.Duration, getter Getter) error

AddGroup adds a new cache group with a getter function. A cache group is a set of cache entries that can be retrieved using the getter function.

func (*WebCache) BucketStats

func (c *WebCache) BucketStats() []*CacheStats

BucketStats returns statistics about all buckets

func (*WebCache) Delete

func (c *WebCache) Delete(group string, key string)

Delete removes the cache entry with the given key from the specified group, if it exists.

func (*WebCache) Get

func (c *WebCache) Get(ctx context.Context, group, key, etag string) ([]byte, *CacheInfo, error)

Get retrieves the cache entry with the given key from the specified group. It returns the cached data and its associated CacheInfo, or an error if the entry does not exist.

func (*WebCache) Set

func (c *WebCache) Set(group, key string, value []byte) *CacheInfo

Set inserts some {key, value} into the WebCache.

func (*WebCache) Stats

func (c *WebCache) Stats() *CacheStats

Stats returns the total stats of all the buckets