lru

Documentation

Overview

Package lru implements a least recently used in-memory cache. It used a doubly linked list and purges items if the number of items in the cache exceeds the max, the total size of the cache in memory exceeds the given size, or the item expires.

Index

• Constants
• Variables
• type LRU
  • func NewBasic(maxSize uint64, maxEntries int) *LRU
  • func (c *LRU) Add(key string, value interface{}, exp time.Duration) error
  • func (c *LRU) Append(key string, value interface{}) error
  • func (c *LRU) CompareAndSwap(key string, value interface{}, exp time.Duration, cas uint64) (err error)
  • func (c *LRU) Decrement(key string, delta uint64) (uint64, error)
  • func (c *LRU) Del(key string) (err error)
  • func (c *LRU) Exists(key string) (exists bool)
  • func (c *LRU) Get(key string, dstVal interface{}) (err error)
  • func (c *LRU) GetItem(key string, dstVal interface{}) (cas uint64, err error)
  • func (c *LRU) Increment(key string, delta uint64) (uint64, error)
  • func (c *LRU) Len() int
  • func (c *LRU) Prepend(key string, value interface{}) error
  • func (c *LRU) Replace(key string, value interface{}) error
  • func (c *LRU) Set(key string, value interface{}, exp time.Duration) (err error)
  • func (c *LRU) SetItem(key string, value interface{}, exp time.Duration, cas uint64) (err error)
  • func (c *LRU) Touch(key string, exp time.Duration) error
• type ShardedLRU
  • func New() *ShardedLRU
  • func NewSharded(maxSize uint64, maxEntries uint64, shardCt uint64) *ShardedLRU
  • func (c *ShardedLRU) Add(key string, value interface{}, exp time.Duration) (err error)
  • func (c *ShardedLRU) Append(key string, value interface{}) (err error)
  • func (c *ShardedLRU) CompareAndSwap(key string, value interface{}, exp time.Duration, cas uint64) (err error)
  • func (c *ShardedLRU) Decrement(key string, delta uint64) (uint64, error)
  • func (c *ShardedLRU) Del(key string) (err error)
  • func (c *ShardedLRU) Exists(key string) bool
  • func (c *ShardedLRU) Get(key string, dstVal interface{}) (err error)
  • func (c *ShardedLRU) GetItem(key string, dstVal interface{}) (cas uint64, err error)
  • func (c *ShardedLRU) Increment(key string, delta uint64) (uint64, error)
  • func (c *ShardedLRU) Prepend(key string, value interface{}) (err error)
  • func (c *ShardedLRU) Replace(key string, value interface{}) (err error)
  • func (c *ShardedLRU) Set(key string, value interface{}, exp time.Duration) (err error)
  • func (c *ShardedLRU) SetItem(key string, value interface{}, exp time.Duration, cas uint64) (err error)
  • func (c *ShardedLRU) Touch(key string, exp time.Duration) (err error)

Constants

const (
	Byte     uint64 = 1
	Kilobyte        = Byte << 10
	Megabyte        = Kilobyte << 10
	Gigabyte        = Megabyte << 10
	Terabyte        = Gigabyte << 10
)

Sizes and defaults for the cache

Variables

var (

	// ErrCannotSetValue is returned when an previously set cache value pointer cannot be set.
	ErrCannotSetValue = errors.New("cannot set value of interface")

	// ErrCannotAssignValue is returned when a previously set cache value pointer cannot be
	// updated because the new value's type cannot be assigned to the previous value's type.
	ErrCannotAssignValue = errors.New("cannot assign value")
)

Types

type LRU

type LRU struct {
	// MaxEntries are the max number of cache entries. 0 is unlimited
	MaxEntries int
	// MaxSize is the max size, in bytes, of the total cache store in memory
	MaxSize uint64

	sync.RWMutex
	// contains filtered or unexported fields
}

LRU is a least recently used in-memory cache implementation

func NewBasic

func NewBasic(maxSize uint64, maxEntries int) *LRU

NewBasic creates a new LRU cache with the given number of max entries

func (*LRU) Add

func (c *LRU) Add(key string, value interface{}, exp time.Duration) error

Add adds the value to cache, but only if the key doesn't already exist.

func (*LRU) Append

func (c *LRU) Append(key string, value interface{}) error

Append appends the value to the current key value. The value to append must be a string, []byte or pointer to one of those types.

func (*LRU) CompareAndSwap

func (c *LRU) CompareAndSwap(key string, value interface{}, exp time.Duration, cas uint64) (err error)

CompareAndSwap writes the given item that was previously returned by Get, if the value was neither modified or evicted between the Get and the CompareAndSwap calls. The item's Key should not change between calls but all other item fields may differ. ErrCASConflict is returned if the value

was modified in between the calls. ErrNotStored is returned if the value

was evicted in between the calls.

func (*LRU) Decrement

func (c *LRU) Decrement(key string, delta uint64) (uint64, error)

Decrement decreases the key's value by delta. The expiration remains the same. The underlying value to increment must be a uint64 or pointer to a uint64.

func (*LRU) Del

func (c *LRU) Del(key string) (err error)

Del removes the key from the cache

func (*LRU) Exists

func (c *LRU) Exists(key string) (exists bool)

Exists returns true if the given key exists

func (*LRU) Get

func (c *LRU) Get(key string, dstVal interface{}) (err error)

Get fetches the key into the dstVal. It returns an error if the value doesn't exist.

func (*LRU) GetItem

func (c *LRU) GetItem(key string, dstVal interface{}) (cas uint64, err error)

GetItem is similar to Get() only it returns the items unique CAS identifier

func (*LRU) Increment

func (c *LRU) Increment(key string, delta uint64) (uint64, error)

Increment increases the key's value by delta. The exipration remains the same. The existing value must be a uint64 or a pointer to a uint64

func (*LRU) Len

func (c *LRU) Len() int

Len returns the number of items in the cache.

func (*LRU) Prepend

func (c *LRU) Prepend(key string, value interface{}) error

Prepend prepends the value to the current key value. The value to prepend must be a string, []byte or pointer to one of those types.

func (*LRU) Replace

func (c *LRU) Replace(key string, value interface{}) error

Replace replaces the current value for the key with the new value, but only if the key already exists. The expiration remains the same.

func (*LRU) Set

func (c *LRU) Set(key string, value interface{}, exp time.Duration) (err error)

Set sets the key/value pair

func (*LRU) SetItem

func (c *LRU) SetItem(key string, value interface{}, exp time.Duration, cas uint64) (err error)

SetItem sets the item with the given parameters. Use it if you need to specifiy the cas id for future CompareAndSwap actions. Otherwise it's easier to just use Set() instead.

func (*LRU) Touch

func (c *LRU) Touch(key string, exp time.Duration) error

Touch updates the expiry for the given key

type ShardedLRU

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

ShardedLRU is a LRU with keys split across shards for better performance

func New

func New() *ShardedLRU

New returns a new ShardedLRU with a up to a max of one Gigabyte of memory usage

func NewSharded

func NewSharded(maxSize uint64, maxEntries uint64, shardCt uint64) *ShardedLRU

NewSharded returns a new sharded LRU cache with a maximum in-memory size of maxSize, and total maxEntries spread over shardCt

func (*ShardedLRU) Add

func (c *ShardedLRU) Add(key string, value interface{}, exp time.Duration) (err error)

Add adds the value to cache, but only if the key doesn't already exist.

func (*ShardedLRU) Append

func (c *ShardedLRU) Append(key string, value interface{}) (err error)

Append appends the value to the current key value. The value to append must be a string, []byte or pointer to one of those types.

func (*ShardedLRU) CompareAndSwap

func (c *ShardedLRU) CompareAndSwap(key string, value interface{}, exp time.Duration, cas uint64) (err error)

CompareAndSwap writes the given item that was previously returned by Get, if the value was neither modified or evicted between the Get and the CompareAndSwap calls. The item's Key should not change between calls but all other item fields may differ. ErrCASConflict is returned if the value

was modified in between the calls. ErrNotStored is returned if the value

was evicted in between the calls.

func (*ShardedLRU) Decrement

func (c *ShardedLRU) Decrement(key string, delta uint64) (uint64, error)

Decrement decreases the key's value by delta. The expiration remains the same. The underlying value to increment must be a uint64 or pointer to a uint64.

func (*ShardedLRU) Del

func (c *ShardedLRU) Del(key string) (err error)

Del removes the key from the cache

func (*ShardedLRU) Exists

func (c *ShardedLRU) Exists(key string) bool

Exists returns true if the given key exists

func (*ShardedLRU) Get

func (c *ShardedLRU) Get(key string, dstVal interface{}) (err error)

Get fetches the key into the dstVal. It returns an error if the value doesn't exist.

func (*ShardedLRU) GetItem

func (c *ShardedLRU) GetItem(key string, dstVal interface{}) (cas uint64, err error)

GetItem is similar to Get() only it returns the items unique CAS identifier

func (*ShardedLRU) Increment

func (c *ShardedLRU) Increment(key string, delta uint64) (uint64, error)

Increment increases the key's value by delta. The exipration remains the same. The existing value must be a uint64 or a pointer to a uint64

func (*ShardedLRU) Prepend

func (c *ShardedLRU) Prepend(key string, value interface{}) (err error)

Prepend prepends the value to the current key value. The value to prepend must be a string, []byte or pointer to one of those types.

func (*ShardedLRU) Replace

func (c *ShardedLRU) Replace(key string, value interface{}) (err error)

Replace replaces the current value for the key with the new value, but only if the key already exists. The expiration remains the same.

func (*ShardedLRU) Set

func (c *ShardedLRU) Set(key string, value interface{}, exp time.Duration) (err error)

Set sets the key/value pair

func (*ShardedLRU) SetItem

func (c *ShardedLRU) SetItem(key string, value interface{}, exp time.Duration, cas uint64) (err error)

SetItem sets the item with the given parameters. Use it if you need to specifiy the cas id for future CompareAndSwap actions. Otherwise it's easier to just use Set() instead.

func (*ShardedLRU) Touch

func (c *ShardedLRU) Touch(key string, exp time.Duration) (err error)

Touch updates the expiry for the given key