cachev2

Documentation

Overview

Package cachev2 provides a high-performance concurrent map implementation optimized for cache operations. The implementation uses sharding to minimize lock contention by dividing the map into multiple independent shards, each protected by its own read-write mutex.

The concurrent map stores string keys mapped to *cache.Item values and is designed to be thread-safe for concurrent read and write operations across multiple goroutines.

Key features:

• Sharded design with 32 shards to reduce lock contention
• FNV-1a hash function for efficient key distribution
• Thread-safe operations with optimized read/write locking
• Buffered iteration support for safe concurrent traversal
• Standard map operations: Set, Get, Has, Remove, Pop, Clear, Count

Example usage:

cm := cachev2.New()
cm.Set("key", &cache.Item{...})
if item, ok := cm.Get("key"); ok {
    // Process item
}

Index

• Constants
• type ConcurrentMap
  • func New() ConcurrentMap
  • func (cm *ConcurrentMap) Clear()
  • func (cm *ConcurrentMap) Count() int
  • func (cm *ConcurrentMap) Get(key string) (*Item, bool)
  • func (cm *ConcurrentMap) GetShard(key string) *ConcurrentMapShard
  • func (cm *ConcurrentMap) Has(key string) bool
  • func (cm *ConcurrentMap) IterBuffered() <-chan Tuple
  • func (cm *ConcurrentMap) Pop(key string) (*Item, bool)
  • func (cm *ConcurrentMap) Remove(key string)
  • func (cm *ConcurrentMap) Set(key string, value *Item)
• type ConcurrentMapShard
• type Item
  • func (it *Item) Expired() bool
  • func (it *Item) SetSize() error
  • func (it *Item) SizeKB() float64
  • func (it *Item) SizeMB() float64
  • func (it *Item) Touch()
  • func (it *Item) Valid() error
• type ItemPoolManager
  • func NewItemPoolManager() *ItemPoolManager
  • func (m *ItemPoolManager) Get() *Item
  • func (m *ItemPoolManager) Put(it *Item)
• type Sizer
• type Tuple

Constants

const (
	// ShardCount is the number of shards used by the map.
	ShardCount = 32
	// ShardCount32 is the number of shards used by the map pre-casted to uint32 to avoid performance issues.
	ShardCount32 uint32 = uint32(ShardCount)
)

Types

type ConcurrentMap

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

ConcurrentMap is a "thread" safe map of type string:*cache.Item. To avoid lock bottlenecks this map is divided into several (ShardCount) map shards.

func New

func New() ConcurrentMap

New creates a new concurrent map.

func (*ConcurrentMap) Clear

func (cm *ConcurrentMap) Clear()

Clear removes all items from map.

func (*ConcurrentMap) Count

func (cm *ConcurrentMap) Count() int

Count returns the number of items in the map.

func (*ConcurrentMap) Get

func (cm *ConcurrentMap) Get(key string) (*Item, bool)

Get retrieves an element from map under given key.

func (*ConcurrentMap) GetShard

func (cm *ConcurrentMap) GetShard(key string) *ConcurrentMapShard

GetShard returns shard under given key.

func (*ConcurrentMap) Has

func (cm *ConcurrentMap) Has(key string) bool

Has checks if key is present in the map.

func (*ConcurrentMap) IterBuffered

func (cm *ConcurrentMap) IterBuffered() <-chan Tuple

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

func (*ConcurrentMap) Pop

func (cm *ConcurrentMap) Pop(key string) (*Item, bool)

Pop removes an element from the map and returns it.

func (*ConcurrentMap) Remove

func (cm *ConcurrentMap) Remove(key string)

Remove removes the value under the specified key.

func (*ConcurrentMap) Set

func (cm *ConcurrentMap) Set(key string, value *Item)

Set sets the given value under the specified key.

type ConcurrentMapShard

type ConcurrentMapShard struct {
	sync.RWMutex
	// contains filtered or unexported fields
}

ConcurrentMapShard is a "thread" safe string to `*cache.Item` map shard.

type Item

type Item struct {
	Key         string        // key of the item
	Value       any           // value of the item
	LastAccess  time.Time     // last access time
	LastUpdated time.Time     // last write/version assignment time (distributed usage)
	Size        int64         // size in bytes
	Expiration  time.Duration // expiration duration
	AccessCount uint32        // number of times the item has been accessed
	Version     uint64        // logical version (monotonic per key)
	Origin      string        // originating node id (tiebreaker)
}

Item is a struct that represents an item in the cache (v2 optimized layout). It mirrors pkg/cache.Item behavior but with minor layout tweaks for locality.

func (*Item) Expired

func (it *Item) Expired() bool

Expired reports whether the item has expired.

func (*Item) SetSize

func (it *Item) SetSize() error

SetSize computes and sets Size using fast paths and pooled encoder/buffer. This preserves original behavior (size of serialized value) but reduces allocations.

func (*Item) SizeKB

func (it *Item) SizeKB() float64

SizeKB returns the size of the Item in kilobytes.

func (*Item) SizeMB

func (it *Item) SizeMB() float64

SizeMB returns the size of the Item in megabytes.

func (*Item) Touch

func (it *Item) Touch()

Touch updates last access time and increments access count.

func (*Item) Valid

func (it *Item) Valid() error

Valid returns an error if the item is invalid, nil otherwise. Semantics match pkg/cache.Item.Valid but without atomics.

type ItemPoolManager

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

ItemPoolManager manages Item object pools for memory efficiency (v2).

func NewItemPoolManager

func NewItemPoolManager() *ItemPoolManager

NewItemPoolManager creates a new ItemPoolManager with default configuration (v2).

func (*ItemPoolManager) Get

func (m *ItemPoolManager) Get() *Item

Get retrieves an Item from the pool (v2).

func (*ItemPoolManager) Put

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

Put returns an Item to the pool (v2).

type Sizer

type Sizer interface{ SizeBytes() int }

Sizer allows custom values to report their encoded size without serialization.

type Tuple

type Tuple struct {
	Key string
	Val Item
}

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