cache

package
v1.20220411.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 11, 2022 License: MIT Imports: 8 Imported by: 0

Documentation

Overview

Package cache provides caching primitives for in-memory caches, including LRU eviction.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Cache 

type Cache interface {
	Has(key interface{}) bool
	GetOrSet(key interface{}, valueProvider func() (interface{}, error), options ...ValueOption) (interface{}, bool, error)
	Set(key, value interface{}, options ...ValueOption)
	Get(key interface{}) (interface{}, bool)
	Remove(key interface{}) (interface{}, bool)
}

Cache is a type that implements the cache interface.

type LRU 

type LRU interface {
	// Len returns the number of items in the queue.
	Len() int
	// Push should add a new value. The new minimum value should be returned by `Peek()` and `Pop()`.
	Push(*Value)
	// Pop should remove and return the minimum value, reordering the heap
	// to set a new minimum value.
	Pop() *Value
	// Peek should return (but not remove) the minimum value.
	Peek() *Value
	// Fix should update the LRU, replacing any existing values, reordering the heap.
	Fix(*Value)
	// Remove should remove a value with a given key, compacting the heap.
	Remove(interface{})
	// Consume should iterate through the values. If `true` is removed by the handler,
	// the current value will be removed and the handler will be called on the next value.
	Consume(func(*Value) bool)
	// Reset should remove all values from the LRU, leaving an empty LRU.
	Reset()
}

LRU is a type that implements the LRU methods.

type LRUHeap 

type LRUHeap struct {
	Values LRUHeapValues
}

LRUHeap is a fifo buffer that is backed by a pre-allocated array, instead of allocating a whole new node object for each element (which saves GC churn). Enqueue can be O(n), Dequeue can be O(1).

func NewLRUHeap 

func NewLRUHeap() *LRUHeap

NewLRUHeap creates a new, empty, LRU Heap.

func (*LRUHeap) Consume 

func (lrh *LRUHeap) Consume(consumer func(value *Value) bool)

Consume calls the consumer for each element in the buffer, while also dequeueing that entry. The consumer should return `true` if it should remove the item and continue processing. If `false` is returned, the current item will be left in place.

func (*LRUHeap) Fix 

func (lrh *LRUHeap) Fix(newValue *Value)

Fix updates a value by key.

func (*LRUHeap) Len 

func (lrh *LRUHeap) Len() int

Len returns the length of the queue (as it is currently populated). Actual memory footprint may be different.

func (*LRUHeap) Peek 

func (lrh *LRUHeap) Peek() *Value

Peek returns the oldest value but does not dequeue it.

func (*LRUHeap) Pop 

func (lrh *LRUHeap) Pop() *Value

Pop removes the first (oldest) element from the heap.

func (*LRUHeap) Push 

func (lrh *LRUHeap) Push(object *Value)

Push adds an element to the heap.

func (*LRUHeap) Remove 

func (lrh *LRUHeap) Remove(key interface{})

Remove removes a value by key.

func (*LRUHeap) Reset 

func (lrh *LRUHeap) Reset()

Reset removes all elements from the heap, leaving an empty heap.

type LRUHeapValues 

type LRUHeapValues []*Value

LRUHeapValues is an alias that allows for use of a Value array as a heap storage backend. It also implements sorting for other use cases.

func (LRUHeapValues) Len 

func (lruv LRUHeapValues) Len() int

Len returns the values length.

func (LRUHeapValues) Less 

func (lruv LRUHeapValues) Less(i, j int) bool

Less returns if two values are strictly less than eachother.

func (*LRUHeapValues) Pop 

func (lruv *LRUHeapValues) Pop() interface{}

Pop returns an item.

func (*LRUHeapValues) Push 

func (lruv *LRUHeapValues) Push(x interface{})

Push adds a new item.

func (LRUHeapValues) Swap 

func (lruv LRUHeapValues) Swap(i, j int)

Swap swaps values at the given positions.

type LRUQueue 

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

LRUQueue is a fifo buffer that is backed by a pre-allocated array, instead of allocating a whole new node object for each element (which saves GC churn). Enqueue can be O(n), Dequeue can be O(1).

func NewLRUQueue 

func NewLRUQueue() *LRUQueue

NewLRUQueue creates a new, empty, LRUQueue.

func (*LRUQueue) Capacity 

func (lru *LRUQueue) Capacity() int

Capacity returns the total size of the ring bufffer, including empty elements.

func (*LRUQueue) Clear 

func (lru *LRUQueue) Clear()

Clear removes all objects from the LRUQueue.

func (*LRUQueue) Consume 

func (lru *LRUQueue) Consume(consumer func(*Value) bool)

Consume calls the consumer for each element in the buffer. If the handler returns true, the element is popped and the handler is called on the next value.

func (*LRUQueue) Each 

func (lru *LRUQueue) Each(consumer func(*Value) bool)

Each iterates through the queue and calls the consumer for each element of the queue.

func (*LRUQueue) Fix 

func (lru *LRUQueue) Fix(value *Value)

Fix updates the queue given an update to a specific value.

func (*LRUQueue) Len 

func (lru *LRUQueue) Len() (len int)

Len returns the length of the ring buffer (as it is currently populated). Actual memory footprint may be different.

func (*LRUQueue) Peek 

func (lru *LRUQueue) Peek() *Value

Peek returns but does not remove the first element.

func (*LRUQueue) PeekBack 

func (lru *LRUQueue) PeekBack() *Value

PeekBack returns but does not remove the last element.

func (*LRUQueue) Pop 

func (lru *LRUQueue) Pop() *Value

Pop removes the first (oldest) element from the LRUQueue.

func (*LRUQueue) Push 

func (lru *LRUQueue) Push(object *Value)

Push adds an element to the "back" of the LRUQueue.

func (*LRUQueue) Remove 

func (lru *LRUQueue) Remove(key interface{})

Remove removes an item from the queue by its key.

func (*LRUQueue) Reset 

func (lru *LRUQueue) Reset()

Reset removes all elements from the heap, leaving an empty heap.

func (*LRUQueue) TrimExcess 

func (lru *LRUQueue) TrimExcess()

TrimExcess trims the excess space in the ringbuffer.

type LocalCache 

type LocalCache struct {
	sync.RWMutex
	Data    map[interface{}]*Value
	LRU     LRU
	Sweeper *async.Interval
}

LocalCache is a memory LocalCache.

func New 

func New(options ...LocalCacheOption) *LocalCache

New returns a new LocalLocalCache. It defaults to 500ms sweep intervals and an LRU queue for invalidation.

func (*LocalCache) Get 

func (lc *LocalCache) Get(key interface{}) (value interface{}, hit bool)

Get gets a value based on a key.

func (*LocalCache) GetOrSet 

func (lc *LocalCache) GetOrSet(key interface{}, valueProvider func() (interface{}, error), options ...ValueOption) (value interface{}, hit bool, err error)

GetOrSet gets a value by a key, and in the case of a miss, sets the value from a given value provider lazily. Hit indicates that the provider was not called.

func (*LocalCache) Has 

func (lc *LocalCache) Has(key interface{}) (has bool)

Has returns if the key is present in the LocalCache.

func (*LocalCache) NotifyStarted 

func (lc *LocalCache) NotifyStarted() <-chan struct{}

NotifyStarted returns the underlying started signal.

func (*LocalCache) NotifyStopped 

func (lc *LocalCache) NotifyStopped() <-chan struct{}

NotifyStopped returns the underlying stopped signal.

func (*LocalCache) Remove 

func (lc *LocalCache) Remove(key interface{}) (value interface{}, hit bool)

Remove removes a specific key.

func (*LocalCache) Reset 

func (lc *LocalCache) Reset()

Reset removes all items from the cache, leaving an empty cache.

Reset will call the removed handler for any elements currently in the cache with a removal reason `Removed`. This will be done outside the critical section.

func (*LocalCache) Set 

func (lc *LocalCache) Set(key, value interface{}, options ...ValueOption)

Set adds a LocalCache item.

func (*LocalCache) Start 

func (lc *LocalCache) Start() error

Start starts the sweeper.

func (*LocalCache) Stats 

func (lc *LocalCache) Stats() (stats Stats)

Stats returns the LocalCache stats.

Stats include the number of items held, the age of the items, and the size in bytes represented by each of the items (not including) the fields of the cache itself like the LRU queue.

func (*LocalCache) Stop 

func (lc *LocalCache) Stop() error

Stop stops the sweeper.

func (*LocalCache) Sweep 

func (lc *LocalCache) Sweep(ctx context.Context) error

Sweep checks keys for expired ttls. If any values are configured with 'OnSweep' handlers, they will be called outside holding the critical section.

type LocalCacheOption 

type LocalCacheOption func(*LocalCache)

LocalCacheOption is a local cache option.

func OptLRU 

func OptLRU(lruImplementation LRU) LocalCacheOption

OptLRU sets the LRU implementation.

func OptSweepInterval 

func OptSweepInterval(d time.Duration) LocalCacheOption

OptSweepInterval sets the local cache sweep interval.

type Locker 

type Locker interface {
	sync.Locker
	RLock()
	RUnlock()
}

Locker is a cache type that supports external control of locking for both exclusive and reader/writer locks.

type RemovalReason 

type RemovalReason int

RemovalReason is a reason for removal. 

const (
	Expired RemovalReason = iota
	Removed RemovalReason = iota
)

RemovalReasons

func (RemovalReason) String 

func (rr RemovalReason) String() string

String returns a string representation of the removal reason.

type Stats 

type Stats struct {
	Count     int
	SizeBytes int
	MaxAge    time.Duration
}

Stats represents cached statistics.

type Value 

type Value struct {
	Timestamp time.Time
	Expires   time.Time
	Key       interface{}
	Value     interface{}
	OnRemove  func(interface{}, RemovalReason)
}

Value is a cached item.

type ValueOption 

type ValueOption func(*Value)

ValueOption is an option for a cache value.

func OptValueExpires 

func OptValueExpires(expires time.Time) ValueOption

OptValueExpires sets the ttl for the value.

func OptValueOnRemove 

func OptValueOnRemove(handler func(interface{}, RemovalReason)) ValueOption

OptValueOnRemove sets the on remove handler.

func OptValueTTL 

func OptValueTTL(d time.Duration) ValueOption

OptValueTTL sets the ttl for the value.

func OptValueTimestamp 

func OptValueTimestamp(t time.Time) ValueOption

OptValueTimestamp sets the timestamp for the value.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.