ttlcache

README

TTLCache - an in-memory cache with expiration

TTLCache was forked from ReneKroon/ttlcache to add extra functions not available in the original scope. The main differences are:

1. A cache count limiter

Documentation

Index

• Constants
• Variables
• type Cache
  • func NewCache() *Cache
  • func (cache *Cache) Close() error
  • func (cache *Cache) Count() int
  • func (cache *Cache) Get(key string) (interface{}, error)
  • func (cache *Cache) Purge() error
  • func (cache *Cache) Remove(key string) error
  • func (cache *Cache) Set(key string, data interface{}) error
  • func (cache *Cache) SetCacheSizeLimit(limit int)
  • func (cache *Cache) SetCheckExpirationCallback(callback CheckExpireCallback)
  • func (cache *Cache) SetExpirationCallback(callback ExpireCallback)
  • func (cache *Cache) SetLoaderFunction(loader LoaderFunction)
  • func (cache *Cache) SetNewItemCallback(callback ExpireCallback)
  • func (cache *Cache) SetTTL(ttl time.Duration) error
  • func (cache *Cache) SetWithTTL(key string, data interface{}, ttl time.Duration) error
  • func (cache *Cache) SkipTTLExtensionOnHit(value bool)
• type CheckExpireCallback
• type ExpireCallback
• type LoaderFunction

Constants

const (
	// ItemNotExpire Will avoid the item being expired by TTL, but can still be exired by callback etc.
	ItemNotExpire time.Duration = -1
	// ItemExpireWithGlobalTTL will use the global TTL when set.
	ItemExpireWithGlobalTTL time.Duration = 0
)

Variables

var (
	// ErrClosed is raised when operating on a cache where Close() has already been called.
	ErrClosed = errors.New("cache already closed")
	// ErrNotFound indicates that the requested key is not present in the cache
	ErrNotFound = errors.New("key not found")
)

Types

type Cache

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

Cache is a synchronized map of items that can auto-expire once stale

func NewCache

func NewCache() *Cache

NewCache is a helper to create instance of the Cache struct

func (*Cache) Close

func (cache *Cache) Close() error

Close calls Purge after stopping the goroutine that does ttl checking, for a clean shutdown. The cache is no longer cleaning up after the first call to Close, repeated calls are safe and return ErrClosed.

func (*Cache) Count

func (cache *Cache) Count() int

Count returns the number of items in the cache. Returns zero when the cache has been closed.

func (*Cache) Get

func (cache *Cache) Get(key string) (interface{}, error)

Get is a thread-safe way to lookup items Every lookup, also touches the item, hence extending it's life

func (*Cache) Purge

func (cache *Cache) Purge() error

Purge will remove all entries

func (*Cache) Remove

func (cache *Cache) Remove(key string) error

Remove removes an item from the cache if it exists, triggers expiration callback when set. Can return ErrNotFound if the entry was not present.

func (*Cache) Set

func (cache *Cache) Set(key string, data interface{}) error

Set is a thread-safe way to add new items to the map.

func (*Cache) SetCacheSizeLimit

func (cache *Cache) SetCacheSizeLimit(limit int)

SetCacheSizeLimit sets a limit to the amount of cached items. If a new item is getting cached, the closes item to being timed out will be replaced Set to 0 to turn off

func (*Cache) SetCheckExpirationCallback

func (cache *Cache) SetCheckExpirationCallback(callback CheckExpireCallback)

SetCheckExpirationCallback sets a callback that will be called when an item is about to expire in order to allow external code to decide whether the item expires or remains for another TTL cycle

func (*Cache) SetExpirationCallback

func (cache *Cache) SetExpirationCallback(callback ExpireCallback)

SetExpirationCallback sets a callback that will be called when an item expires

func (*Cache) SetLoaderFunction

func (cache *Cache) SetLoaderFunction(loader LoaderFunction)

SetLoaderFunction allows you to set a function to retrieve cache misses. The signature matches that of the Get function. Additional Get calls on the same key block while fetching is in progress (groupcache style).

func (*Cache) SetNewItemCallback

func (cache *Cache) SetNewItemCallback(callback ExpireCallback)

SetNewItemCallback sets a callback that will be called when a new item is added to the cache

func (*Cache) SetTTL

func (cache *Cache) SetTTL(ttl time.Duration) error

SetTTL sets the global TTL value for items in the cache, which can be overridden at the item level.

func (*Cache) SetWithTTL

func (cache *Cache) SetWithTTL(key string, data interface{}, ttl time.Duration) error

SetWithTTL is a thread-safe way to add new items to the map with individual ttl.

func (*Cache) SkipTTLExtensionOnHit

func (cache *Cache) SkipTTLExtensionOnHit(value bool)

SkipTTLExtensionOnHit allows the user to change the cache behaviour. When this flag is set to true it will no longer extend TTL of items when they are retrieved using Get, or when their expiration condition is evaluated using SetCheckExpirationCallback.

type CheckExpireCallback

type CheckExpireCallback func(key string, value interface{}) bool

CheckExpireCallback is used as a callback for an external check on item expiration

type ExpireCallback

type ExpireCallback func(key string, value interface{})

ExpireCallback is used as a callback on item expiration or when notifying of an item new to the cache

type LoaderFunction

type LoaderFunction func(key string) (data interface{}, ttl time.Duration, err error)

LoaderFunction can be supplied to retrieve an item where a cache miss occurs. Supply an item specific ttl or Duration.Zero