memorycache

README

MemoryCache

To the time to life, rather than to life in time.

中文

Description

Minimalist in-memory KV storage, powered by HashMap and Minimal Quad Heap.

Cache Elimination Policy:

• Set method cleans up overflowed keys
• Active cycle cleans up expired keys

Principle

• Storage Data Limit: Limited by maximum capacity
• Expiration Time: Supported
• Cache Eviction Policy: LRU
• Persistent: None
• Locking Mechanism: Slicing + Mutual Exclusion Locking
• HashMap, Heap and LinkedList (excluding user KVs) implemented in pointerless technology

Advantage

• Simple and easy to use
• High performance
• Low memory usage
• Use quadruple heap to maintain the expiration time, effectively reduce the height of the tree, and improve the insertion performance

Methods

• Set : Set key-value pair with expiring time. If the key already exists, the value will be updated. Also the expiration time will be updated.
• SetWithCallback : Set key-value pair with expiring time and callback function. If the key already exists, the value will be updated. Also the expiration time will be updated.
• Get : Get value by key. If the key does not exist, the second return value will be false.
• GetWithTTL : Get value by key. If the key does not exist, the second return value will be false. When return value, method will refresh the expiration time.
• Delete : Delete key-value pair by key.
• GetOrCreate : Get value by key. If the key does not exist, the value will be created.
• GetOrCreateWithCallback : Get value by key. If the key does not exist, the value will be created. Also the callback function will be called.

Example

package main

import (
	"fmt"
	"github.com/lxzan/memorycache"
	"time"
)

func main() {
	mc := memorycache.New[string, any](
		// Set the number of storage buckets, y=pow(2,x)
		memorycache.WithBucketNum(128),

		// Set bucket size, initial size and maximum capacity (single bucket)
		memorycache.WithBucketSize(1000, 10000),

		// Set the expiration time check period. 
		// If the number of expired elements is small, take the maximum value, otherwise take the minimum value.
		memorycache.WithInterval(5*time.Second, 30*time.Second),
	)

	mc.SetWithCallback("xxx", 1, time.Second, func(element *memorycache.Element[string, any], reason memorycache.Reason) {
		fmt.Printf("callback: key=%s, reason=%v\n", element.Key, reason)
	})

	val, exist := mc.Get("xxx")
	fmt.Printf("val=%v, exist=%v\n", val, exist)

	time.Sleep(2 * time.Second)

	val, exist = mc.Get("xxx")
	fmt.Printf("val=%v, exist=%v\n", val, exist)
}

Benchmark

• 1,000,000 elements

goos: linux
goarch: amd64
pkg: github.com/lxzan/memorycache/benchmark
cpu: AMD Ryzen 5 PRO 4650G with Radeon Graphics
BenchmarkMemoryCache_Set-8              16107153                74.85 ns/op           15 B/op          0 allocs/op
BenchmarkMemoryCache_Get-8              28859542                42.34 ns/op            0 B/op          0 allocs/op
BenchmarkMemoryCache_SetAndGet-8        27317874                63.02 ns/op            0 B/op          0 allocs/op
BenchmarkRistretto_Set-8                13343023               272.6 ns/op           120 B/op          2 allocs/op
BenchmarkRistretto_Get-8                19799044                55.06 ns/op           17 B/op          1 allocs/op
BenchmarkRistretto_SetAndGet-8          11212923               119.6 ns/op            30 B/op          1 allocs/op
BenchmarkTheine_Set-8                    3775975               322.5 ns/op            30 B/op          0 allocs/op
BenchmarkTheine_Get-8                   21579301                54.94 ns/op            0 B/op          0 allocs/op
BenchmarkTheine_SetAndGet-8              6265330               224.6 ns/op             0 B/op          0 allocs/op
PASS
ok      github.com/lxzan/memorycache/benchmark  53.498s

Documentation

Index

• Constants
• type CallbackFunc
• type Element
• type MemoryCache
  • func New[K comparable, V any](options ...Option) *MemoryCache[K, V]
  • func (c *MemoryCache[K, V]) Clear()
  • func (c *MemoryCache[K, V]) Delete(key K) (exist bool)
  • func (c *MemoryCache[K, V]) Get(key K) (v V, exist bool)
  • func (c *MemoryCache[K, V]) GetOrCreate(key K, value V, exp time.Duration) (v V, exist bool)
  • func (c *MemoryCache[K, V]) GetOrCreateWithCallback(key K, value V, exp time.Duration, cb CallbackFunc[*Element[K, V]]) (v V, exist bool)
  • func (c *MemoryCache[K, V]) GetWithTTL(key K, exp time.Duration) (v V, exist bool)
  • func (c *MemoryCache[K, V]) Len() int
  • func (c *MemoryCache[K, V]) Range(f func(K, V) bool)
  • func (c *MemoryCache[K, V]) Set(key K, value V, exp time.Duration) (exist bool)
  • func (c *MemoryCache[K, V]) SetWithCallback(key K, value V, exp time.Duration, cb CallbackFunc[*Element[K, V]]) (exist bool)
  • func (c *MemoryCache[K, V]) Stop()
• type Option
  • func WithBucketNum(num int) Option
  • func WithBucketSize(size, cap int) Option
  • func WithCachedTime(enabled bool) Option
  • func WithDeleteLimits(num int) Option
  • func WithInterval(min, max time.Duration) Option
  • func WithSwissTable(enabled bool) Option
• type Reason

Constants

const (
	ReasonExpired = Reason(0) // 过期
	ReasonEvicted = Reason(1) // 被驱逐
	ReasonDeleted = Reason(2) // 被删除
)

Types

type CallbackFunc

type CallbackFunc[T any] func(element T, reason Reason)

type Element

type Element[K comparable, V any] struct {

	// 键
	Key K

	// 值
	Value V

	// 过期时间, 毫秒
	ExpireAt int64
	// contains filtered or unexported fields
}

type MemoryCache

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

func New

func New[K comparable, V any](options ...Option) *MemoryCache[K, V]

New 创建缓存数据库实例 Creating a Cached Database Instance

func (*MemoryCache[K, V]) Clear

func (c *MemoryCache[K, V]) Clear()

Clear 清空缓存 clear caches

func (*MemoryCache[K, V]) Delete

func (c *MemoryCache[K, V]) Delete(key K) (exist bool)

Delete 删除缓存 delete cache

func (*MemoryCache[K, V]) Get

func (c *MemoryCache[K, V]) Get(key K) (v V, exist bool)

Get 查询缓存 query cache

func (*MemoryCache[K, V]) GetOrCreate

func (c *MemoryCache[K, V]) GetOrCreate(key K, value V, exp time.Duration) (v V, exist bool)

GetOrCreate 如果存在, 刷新过期时间. 如果不存在, 创建一个新的. Get or create a value. If it exists, refreshes the expiration time. If it does not exist, creates a new one.

func (*MemoryCache[K, V]) GetOrCreateWithCallback

func (c *MemoryCache[K, V]) GetOrCreateWithCallback(key K, value V, exp time.Duration, cb CallbackFunc[*Element[K, V]]) (v V, exist bool)

GetOrCreateWithCallback 如果存在, 刷新过期时间. 如果不存在, 创建一个新的. Get or create a value with CallbackFunc. If it exists, refreshes the expiration time. If it does not exist, creates a new one.

func (*MemoryCache[K, V]) GetWithTTL

func (c *MemoryCache[K, V]) GetWithTTL(key K, exp time.Duration) (v V, exist bool)

GetWithTTL 获取. 如果存在, 刷新过期时间. Get a value. If it exists, refreshes the expiration time.

func (*MemoryCache[K, V]) Len

func (c *MemoryCache[K, V]) Len() int

Len 快速获取当前缓存元素数量, 不做过期检查. Quickly gets the current number of cached elements, without checking for expiration.

func (*MemoryCache[K, V]) Range

func (c *MemoryCache[K, V]) Range(f func(K, V) bool)

Range 遍历缓存 注意: 不要在回调函数里面操作 MemoryCache[K, V] 实例, 可能会造成死锁. Traverse the cache. Note: Do not manipulate MemoryCache[K, V] instances inside callback functions, as this may cause deadlocks.

func (*MemoryCache[K, V]) Set

func (c *MemoryCache[K, V]) Set(key K, value V, exp time.Duration) (exist bool)

Set 设置键值和过期时间. exp<=0表示永不过期. Set the key value and expiration time. exp<=0 means never expire.

func (*MemoryCache[K, V]) SetWithCallback

func (c *MemoryCache[K, V]) SetWithCallback(key K, value V, exp time.Duration, cb CallbackFunc[*Element[K, V]]) (exist bool)

SetWithCallback 设置键值, 过期时间和回调函数. 容量溢出和过期都会触发回调. Set the key value, expiration time and callback function. The callback is triggered by both capacity overflow and expiration.

func (*MemoryCache[K, V]) Stop

func (c *MemoryCache[K, V]) Stop()

type Option

type Option func(c *config)

func WithBucketNum

func WithBucketNum(num int) Option

WithBucketNum 设置存储桶数量 Setting the number of storage buckets

func WithBucketSize

func WithBucketSize(size, cap int) Option

WithBucketSize 设置初始化大小和最大容量. 超过最大容量会被清除. (单个存储桶) Set the initial size and maximum capacity. Exceeding the maximum capacity will be erased. (Single bucket)

func WithCachedTime

func WithCachedTime(enabled bool) Option

WithCachedTime 是否开启时间缓存 Whether to turn on time caching

func WithDeleteLimits

func WithDeleteLimits(num int) Option

WithDeleteLimits 设置每次TTL检查最大删除key数量. (单个存储桶) Set the maximum number of keys to be deleted per TTL check (single bucket)

func WithInterval

func WithInterval(min, max time.Duration) Option

WithInterval 设置TTL检查周期 设置过期时间检查周期. 如果过期元素较少, 取最大值, 反之取最小值. Setting the TTL check period If the number of expired elements is small, take the maximum value, otherwise take the minimum value.

func WithSwissTable

func WithSwissTable(enabled bool) Option

WithSwissTable 使用swiss table替代runtime map Using swiss table instead of runtime map

type Reason

type Reason uint8

Reason 回调函数触发原因