cache

Documentation

Overview

Package cache provides a thread-safe concurrent map implementation with sharding for improved performance in high-concurrency scenarios.

Index

• Constants
• type ConcurrentMap
  • func New[V any]() ConcurrentMap[string, V]
  • func NewStringer[K Stringer, V any]() ConcurrentMap[K, V]
  • func NewWithCustomShardingFunction[K comparable, V any](sharding func(key K) uint32) ConcurrentMap[K, V]
  • func (m ConcurrentMap[K, V]) Clear() error
  • func (m ConcurrentMap[K, V]) Count() int
  • func (m ConcurrentMap[K, V]) Get(key K) (V, bool)
  • func (m ConcurrentMap[K, V]) GetShard(key K) *ConcurrentMapShared[K, V]
  • func (m ConcurrentMap[K, V]) Has(key K) bool
  • func (m ConcurrentMap[K, V]) IsEmpty() bool
  • func (m ConcurrentMap[K, V]) Items() map[K]V
  • func (m ConcurrentMap[K, V]) IterBuffered() <-chan Tuple[K, V]
  • func (m ConcurrentMap[K, V]) IterCb(fn IterCb[K, V])
  • func (m ConcurrentMap[K, V]) Keys() []K
  • func (m ConcurrentMap[K, V]) MSet(data map[K]V)
  • func (m ConcurrentMap[K, V]) MarshalJSON() ([]byte, error)
  • func (m ConcurrentMap[K, V]) Pop(key K) (V, bool)
  • func (m ConcurrentMap[K, V]) Remove(key K) error
  • func (m ConcurrentMap[K, V]) RemoveCb(key K, cb RemoveCb[K, V]) bool
  • func (m ConcurrentMap[K, V]) Set(key K, value V)
  • func (m ConcurrentMap[K, V]) SetIfAbsent(key K, value V) bool
  • func (m *ConcurrentMap[K, V]) UnmarshalJSON(b []byte) error
  • func (m ConcurrentMap[K, V]) Upsert(key K, value V, cb UpsertCb[V]) V
• type ConcurrentMapShared
• type Item
  • func (item *Item) Expired() bool
  • func (item *Item) SetSize() error
  • func (item *Item) SizeKB() float64
  • func (item *Item) SizeMB() float64
  • func (item *Item) Touch()
  • func (item *Item) Valid() error
• type ItemPoolManager
  • func NewItemPoolManager() *ItemPoolManager
  • func (m *ItemPoolManager) Get() *Item
  • func (m *ItemPoolManager) Put(item *Item)
• type IterCb
• type RemoveCb
• type Stringer
• type Tuple
• type UpsertCb

Constants

const (
	ShardCount = 32
)

ShardCount is the number of shards.

Types

type ConcurrentMap

type ConcurrentMap[K comparable, V any] struct {
	// contains filtered or unexported fields
}

ConcurrentMap is a "thread" safe map of type string:Anything. To avoid lock bottlenecks this map is dived to several (ShardCount) map shards.

func New

func New[V any]() ConcurrentMap[string, V]

New creates a new concurrent map.

func NewStringer

func NewStringer[K Stringer, V any]() ConcurrentMap[K, V]

NewStringer creates a new concurrent map.

func NewWithCustomShardingFunction

func NewWithCustomShardingFunction[K comparable, V any](sharding func(key K) uint32) ConcurrentMap[K, V]

NewWithCustomShardingFunction creates a new concurrent map.

func (ConcurrentMap[K, V]) Clear

func (m ConcurrentMap[K, V]) Clear() error

Clear removes all items from map.

func (ConcurrentMap[K, V]) Count

func (m ConcurrentMap[K, V]) Count() int

Count returns the number of elements within the map.

func (ConcurrentMap[K, V]) Get

func (m ConcurrentMap[K, V]) Get(key K) (V, bool)

Get retrieves an element from map under given key.

func (ConcurrentMap[K, V]) GetShard

func (m ConcurrentMap[K, V]) GetShard(key K) *ConcurrentMapShared[K, V]

GetShard returns shard under given key.

func (ConcurrentMap[K, V]) Has

func (m ConcurrentMap[K, V]) Has(key K) bool

Has looks up an item under specified key.

func (ConcurrentMap[K, V]) IsEmpty

func (m ConcurrentMap[K, V]) IsEmpty() bool

IsEmpty checks if map is empty.

func (ConcurrentMap[K, V]) Items

func (m ConcurrentMap[K, V]) Items() map[K]V

Items returns all items as map[string]V.

func (ConcurrentMap[K, V]) IterBuffered

func (m ConcurrentMap[K, V]) IterBuffered() <-chan Tuple[K, V]

IterBuffered returns a buffered iterator which could be used in a for range loop.

func (ConcurrentMap[K, V]) IterCb

func (m ConcurrentMap[K, V]) IterCb(fn IterCb[K, V])

IterCb is a callback based iterator, cheapest way to read all elements in a map.

func (ConcurrentMap[K, V]) Keys

func (m ConcurrentMap[K, V]) Keys() []K

Keys returns all keys as []string.

func (ConcurrentMap[K, V]) MSet

func (m ConcurrentMap[K, V]) MSet(data map[K]V)

MSet Sets the given value under the specified key.

func (ConcurrentMap[K, V]) MarshalJSON

func (m ConcurrentMap[K, V]) MarshalJSON() ([]byte, error)

MarshalJSON reviles ConcurrentMap "private" variables to json marshal.

func (ConcurrentMap[K, V]) Pop

func (m ConcurrentMap[K, V]) Pop(key K) (V, bool)

Pop removes an element from the map and returns it.

func (ConcurrentMap[K, V]) Remove

func (m ConcurrentMap[K, V]) Remove(key K) error

Remove removes an element from the map.

func (ConcurrentMap[K, V]) RemoveCb

func (m ConcurrentMap[K, V]) RemoveCb(key K, cb RemoveCb[K, V]) bool

RemoveCb locks the shard containing the key, retrieves its current value and calls the callback with those params If callback returns true and element exists, it will remove it from the map Returns the value returned by the callback (even if element was not present in the map).

func (ConcurrentMap[K, V]) Set

func (m ConcurrentMap[K, V]) Set(key K, value V)

Set Sets the given value under the specified key.

func (ConcurrentMap[K, V]) SetIfAbsent

func (m ConcurrentMap[K, V]) SetIfAbsent(key K, value V) bool

SetIfAbsent sets the given value under the specified key if no value was associated with it.

func (*ConcurrentMap[K, V]) UnmarshalJSON

func (m *ConcurrentMap[K, V]) UnmarshalJSON(b []byte) error

UnmarshalJSON reverse process of Marshal.

func (ConcurrentMap[K, V]) Upsert

func (m ConcurrentMap[K, V]) Upsert(key K, value V, cb UpsertCb[V]) V

Upsert Insert or Update - updates existing element or inserts a new one using UpsertCb.

type ConcurrentMapShared

type ConcurrentMapShared[K comparable, V any] struct {
	sync.RWMutex // Read Write mutex, guards access to internal map.
	// contains filtered or unexported fields
}

ConcurrentMapShared is a "thread" safe string to anything map.

type Item

type Item struct {
	Key         string        // key of the item
	Value       any           // Value of the item
	Size        int64         // Size of the item, in bytes
	Expiration  time.Duration // Expiration duration of the item
	LastAccess  time.Time     // LastAccess time of the item
	AccessCount uint          // AccessCount of times the item has been accessed
}

Item is a struct that represents an item in the cache. It has a key, value, expiration duration, and a last access time field.

func (*Item) Expired

func (item *Item) Expired() bool

Expired returns true if the item has expired, false otherwise.

func (*Item) SetSize

func (item *Item) SetSize() error

SetSize stores the size of the Item in bytes.

func (*Item) SizeKB

func (item *Item) SizeKB() float64

SizeKB returns the size of the Item in kilobytes.

func (*Item) SizeMB

func (item *Item) SizeMB() float64

SizeMB returns the size of the Item in megabytes.

func (*Item) Touch

func (item *Item) Touch()

Touch updates the last access time of the item and increments the access count.

func (*Item) Valid

func (item *Item) Valid() error

Valid returns an error if the item is invalid, nil otherwise.

type ItemPoolManager

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

ItemPoolManager manages Item object pools for memory efficiency.

func NewItemPoolManager

func NewItemPoolManager() *ItemPoolManager

NewItemPoolManager creates a new ItemPoolManager with default configuration.

func (*ItemPoolManager) Get

func (m *ItemPoolManager) Get() *Item

Get retrieves an Item from the pool.

func (*ItemPoolManager) Put

func (m *ItemPoolManager) Put(item *Item)

Put returns an Item to the pool.

type IterCb

type IterCb[K comparable, V any] func(key K, v V)

IterCb is the iterator callbacalled for every key,value found in maps. RLock is held for all calls for a given shard therefore callback sess consistent view of a shard, but not across the shards.

type RemoveCb

type RemoveCb[K any, V any] func(key K, v V, exists bool) bool

RemoveCb is a callback executed in a map.RemoveCb() call, while Lock is held If returns true, the element will be removed from the map.

type Stringer

type Stringer interface {
	fmt.Stringer
	comparable
}

Stringer is the interface implemented by any value that has a String method,.

type Tuple

type Tuple[K comparable, V any] struct {
	Key K
	Val V
}

Tuple is used by the Iter & IterBuffered functions to wrap two variables together over a channel,.

type UpsertCb

type UpsertCb[V any] func(exist bool, valueInMap V, newValue V) V

UpsertCb callback to return new element to be inserted into the map It is called while lock is held, therefore it MUST NOT try to access other keys in same map, as it can lead to deadlock since Go sync.RWLock is not reentrant.