cache

Documentation

Index

• func Deserialize(data []byte, dest interface{}) error
• func EstimateSize(key string, value []byte) int64
• func Serialize(value interface{}) ([]byte, error)
• type Entry
  • func (e *Entry) IsExpired() bool
  • func (e *Entry) TTL() time.Duration
• type LRUList
  • func NewLRUList() *LRUList
  • func (l *LRUList) Len() int
  • func (l *LRUList) MoveToFront(el *list.Element)
  • func (l *LRUList) PushFront(e *Entry) *list.Element
  • func (l *LRUList) Remove(el *list.Element)
  • func (l *LRUList) RemoveOldest() *Entry
• type Shard
  • func NewShard(maxSize int64) *Shard
  • func (s *Shard) Delete(key string) bool
  • func (s *Shard) DeleteExpired() int
  • func (s *Shard) Exists(key string) bool
  • func (s *Shard) Get(key string) ([]byte, bool)
  • func (s *Shard) Incr(key string, delta int64, ttl time.Duration) (int64, error)
  • func (s *Shard) Len() int
  • func (s *Shard) Set(key string, value []byte, ttl time.Duration)
  • func (s *Shard) TTL(key string) time.Duration

Functions

func Deserialize

func Deserialize(data []byte, dest interface{}) error

Deserialize decodes msgpack bytes into dest. If dest is *[]byte, the raw bytes are copied directly.

func EstimateSize

func EstimateSize(key string, value []byte) int64

EstimateSize returns an approximate memory footprint for a cache entry.

func Serialize

func Serialize(value interface{}) ([]byte, error)

Serialize encodes a value to msgpack bytes. If the value is already []byte, it is returned as-is.

Types

type Entry

type Entry struct {
	Key       string
	Value     []byte
	ExpiresAt time.Time
	Size      int64
	Element   *list.Element
}

Entry represents a single cache item.

func (*Entry) IsExpired

func (e *Entry) IsExpired() bool

IsExpired returns true if the entry has a TTL and it has passed.

func (*Entry) TTL

func (e *Entry) TTL() time.Duration

TTL returns the remaining time-to-live. Returns -1 if there is no expiry, 0 if expired.

type LRUList

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

LRUList is a thin wrapper around container/list for LRU ordering. The front of the list is the most recently used, the back is the least.

func NewLRUList

func NewLRUList() *LRUList

NewLRUList creates a new empty LRU list.

func (*LRUList) Len

func (l *LRUList) Len() int

Len returns the number of elements in the list.

func (*LRUList) MoveToFront

func (l *LRUList) MoveToFront(el *list.Element)

MoveToFront moves the element to the front (most recently used).

func (*LRUList) PushFront

func (l *LRUList) PushFront(e *Entry) *list.Element

PushFront inserts an entry at the front (most recently used).

func (*LRUList) Remove

func (l *LRUList) Remove(el *list.Element)

Remove removes the element from the list.

func (*LRUList) RemoveOldest

func (l *LRUList) RemoveOldest() *Entry

RemoveOldest removes and returns the least recently used entry. Returns nil if the list is empty.

type Shard

type Shard struct {
	Size    int64
	MaxSize int64 // 0 = unlimited

	// Callbacks invoked when entries are evicted or expired.
	// These are called while the shard lock is NOT held.
	OnEvict  func(key string, value []byte)
	OnExpire func(key string, value []byte)
	// contains filtered or unexported fields
}

Shard is a single partition of the cache, protected by its own mutex.

func NewShard

func NewShard(maxSize int64) *Shard

NewShard creates a new shard with the given memory limit.

func (*Shard) Delete

func (s *Shard) Delete(key string) bool

Delete removes a key from the shard. Returns true if the key existed.

func (*Shard) DeleteExpired

func (s *Shard) DeleteExpired() int

DeleteExpired removes all expired entries from this shard. Returns the number of entries removed.

func (*Shard) Exists

func (s *Shard) Exists(key string) bool

Exists checks if a key exists and is not expired.

func (*Shard) Get

func (s *Shard) Get(key string) ([]byte, bool)

Get retrieves the raw value for a key. Returns nil, false on miss or expiry. Promotes the entry in the LRU list on hit.

func (*Shard) Incr

func (s *Shard) Incr(key string, delta int64, ttl time.Duration) (int64, error)

Incr atomically increments a counter stored as int64. If the key does not exist, it is initialized to 0 before incrementing.

func (*Shard) Len

func (s *Shard) Len() int

Len returns the number of items in this shard.

func (*Shard) Set

func (s *Shard) Set(key string, value []byte, ttl time.Duration)

Set stores a serialized value with the given TTL. Overwrites existing entries.

func (*Shard) TTL

func (s *Shard) TTL(key string) time.Duration

TTL returns the remaining time-to-live for a key. Returns -1 if no expiry, 0 if missing or expired.