kvutil

Documentation

Index

• Constants
• Variables
• func GetShardKey(key string, i int) string
• type Cache
  • func NewCache[K comparable, V Model](config *CacheConfig[K, V]) *Cache[K, V]
  • func (p *Cache[K, V]) Delete(ctx context.Context, pks ...K) error
  • func (p *Cache[K, V]) Get(ctx context.Context, pk K) (V, error)
  • func (p *Cache[K, V]) MGetMap(ctx context.Context, pks []K) (map[K]V, error)
  • func (p *Cache[K, V]) MGetSlice(ctx context.Context, pks []K) ([]V, error)
  • func (p *Cache[K, V]) MSetMap(ctx context.Context, models map[K]V, expiration time.Duration) error
  • func (p *Cache[K, V]) MSetSlice(ctx context.Context, models []V, expiration time.Duration) error
  • func (p *Cache[K, V]) Set(ctx context.Context, pk K, elem V, expiration time.Duration) error
• type CacheConfig
• type KVPair
• type Key
• type KeyFactory
  • func (kf *KeyFactory) NewKey(format string, argNames ...string) Key
  • func (kf *KeyFactory) SetPrefix(prefix string)
• type Loader
• type Model
• type ShardingCache
  • func NewShardingCache[K comparable, V ShardingModel](config *ShardingCacheConfig[K, V]) *ShardingCache[K, V]
  • func (p *ShardingCache[K, V]) Delete(ctx context.Context, deleteAllShards bool, pks ...K) error
  • func (p *ShardingCache[K, V]) Get(ctx context.Context, pk K) (V, error)
  • func (p *ShardingCache[K, V]) MGet(ctx context.Context, pks []K) (result map[K]V, errMap map[K]error, storageErr error)
  • func (p *ShardingCache[K, V]) MSet(ctx context.Context, models []V, expiration time.Duration) error
  • func (p *ShardingCache[K, V]) Set(ctx context.Context, pk K, elem V, expiration time.Duration) error
• type ShardingCacheConfig
• type ShardingData
• type ShardingModel
• type Storage

Constants

const DefaultBatchSize = 200

DefaultBatchSize is the default batch size for batch operations.

const DefaultLRUExpiration = time.Second

DefaultLRUExpiration is the default expiration time for data in LRU cache.

const DefaultLoaderBatchSize = 500

DefaultLoaderBatchSize is the default batch size for calling Loader.

Variables

var ErrDataNotFound = errors.New("data not found")

Functions

func GetShardKey

func GetShardKey(key string, i int) string

GetShardKey returns the shard key for given key and index of shard.

Types

type Cache

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

Cache encapsulates frequently used batching cache operations, such as MGet, MSet and Delete.

A Cache must not be copied after initialized.

func NewCache

func NewCache[K comparable, V Model](config *CacheConfig[K, V]) *Cache[K, V]

NewCache returns a new Cache instance.

func (*Cache[K, V]) Delete

func (p *Cache[K, V]) Delete(ctx context.Context, pks ...K) error

Delete deletes key values from Cache.

func (*Cache[K, V]) Get

func (p *Cache[K, V]) Get(ctx context.Context, pk K) (V, error)

Get queries Cache for a given pk.

If pk cannot be found either in the cache nor from the Loader, it returns an error ErrDataNotFound.

func (*Cache[K, V]) MGetMap

func (p *Cache[K, V]) MGetMap(ctx context.Context, pks []K) (map[K]V, error)

MGetMap queries Cache and returns the cached values as a map of type map[K]V.

func (*Cache[K, V]) MGetSlice

func (p *Cache[K, V]) MGetSlice(ctx context.Context, pks []K) ([]V, error)

MGetSlice queries Cache and returns the cached values as a slice of type []V.

func (*Cache[K, V]) MSetMap

func (p *Cache[K, V]) MSetMap(ctx context.Context, models map[K]V, expiration time.Duration) error

MSetMap writes the given models to Cache.

func (*Cache[K, V]) MSetSlice

func (p *Cache[K, V]) MSetSlice(ctx context.Context, models []V, expiration time.Duration) error

MSetSlice writes the given models to Cache.

func (*Cache[K, V]) Set

func (p *Cache[K, V]) Set(ctx context.Context, pk K, elem V, expiration time.Duration) error

Set writes a key value pair to Cache.

type CacheConfig

type CacheConfig[K comparable, V Model] struct {

	// Storage must return a Storage implementation which will be used
	// as the underlying key-value storage.
	Storage func(ctx context.Context) Storage

	// IDFunc returns the primary key of a Model object.
	IDFunc func(V) K

	// KeyFunc specifies the key function to use with the storage.
	KeyFunc Key

	// MGetBatchSize optionally specifies the batch size for one MGet
	// calling to storage. The default is 200.
	MGetBatchSize int

	// MSetBatchSize optionally specifies the batch size for one MSet
	// calling to storage. The default is 200.
	MSetBatchSize int

	// DeleteBatchSize optionally specifies the batch size for one Delete
	// calling to storage. The default is 200.
	DeleteBatchSize int

	// LRUCache optionally enables LRU cache, which may help to improve
	// the performance for high concurrency use-case.
	LRUCache lru.Interface[K, V]

	// LRUExpiration specifies the expiration time for data in LRU cache.
	// The default is one second.
	LRUExpiration time.Duration

	// Loader optionally specifies a function to load data from underlying
	// persistent storage when the data is missing from cache.
	Loader Loader[K, V]

	// LoaderBatchSize optionally specifies the batch size for calling
	// Loader. The default is 500.
	LoaderBatchSize int

	// CacheExpiration specifies the expiration time to cache the data to
	// Storage, when Loader is configured and data are loaded by Loader.
	// The default is zero, which means no expiration.
	CacheExpiration time.Duration

	// CacheLoaderResultAsync makes the Cache to save data from Loader
	// to Storage async, errors returned from Storage.MSet will be ignored.
	// The default is false, it reports errors to the caller.
	CacheLoaderResultAsync bool
}

CacheConfig configures a Cache instance.

type KVPair

type KVPair struct {
	K string
	V []byte
}

KVPair represents a key value pair to work with Cache.

type Key

type Key func(args ...any) string

Key is a function which formats arguments to a string key using predefined key format.

type KeyFactory

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

KeyFactory builds Key functions.

func (*KeyFactory) NewKey

func (kf *KeyFactory) NewKey(format string, argNames ...string) Key

NewKey creates a Key function.

If argNames are given (eg. arg1, arg2), it replace the placeholders of `{argN}` in format to "%v" as key arguments, else it uses a regular expression `\{[^{]*\}` to replace all placeholders of `{arg}` in format to "%v" as key arguments.

func (*KeyFactory) SetPrefix

func (kf *KeyFactory) SetPrefix(prefix string)

SetPrefix configures the Key functions created by the factory to add a prefix to all generated cache keys.

type Loader

type Loader[K comparable, V Model] func(ctx context.Context, pks []K) (map[K]V, error)

Loader loads data from underlying persistent storage.

type Model

type Model interface {
	encoding.BinaryMarshaler
	encoding.BinaryUnmarshaler
}

Model is the interface implemented by types that can be cached by Cache.

type ShardingCache

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

ShardingCache implements common cache operations for big cache value, it helps to split big value into shards according to ShardingCacheConfig.ShardingSize.

When saving data to cache storage, it checks length of the serialization result, if it does not exceed ShardingSize, it saves one key-value to storage, else it splits the serialization result to multiple shards and saves multiple key-values to storage.

When doing query, it first loads the first shard from storage and checks whether there are more shards, if yes, it builds the keys of other shards using the information in the first shard, then reads the other shards, and concat all data to deserialize the complete model.

A ShardingCache must not be copied after initialization.

func NewShardingCache

func NewShardingCache[K comparable, V ShardingModel](config *ShardingCacheConfig[K, V]) *ShardingCache[K, V]

NewShardingCache returns a new ShardingCache instance.

func (*ShardingCache[K, V]) Delete

func (p *ShardingCache[K, V]) Delete(ctx context.Context, deleteAllShards bool, pks ...K) error

Delete deletes key values from ShardingCache.

By default, it only deletes the first shards from storage, if the underlying storage is Redis, the other shards shall be evicted when they are expired. If the underlying storage does not support auto eviction, or the data does not expire, or user want to release storage space actively, deleteAllShards should be set to true, which indicates it to read the first shard from storage and checks whether there are more shards, it yes, it builds the keys of other shards using the information in the first shard, then deletes all shards from storage.

func (*ShardingCache[K, V]) Get

func (p *ShardingCache[K, V]) Get(ctx context.Context, pk K) (V, error)

Get queries ShardingCache for a given pk.

If pk cannot be found in the cache, it returns an error ErrDataNotFound.

func (*ShardingCache[K, V]) MGet

func (p *ShardingCache[K, V]) MGet(ctx context.Context, pks []K) (
	result map[K]V, errMap map[K]error, storageErr error)

MGet queries ShardingCache for multiple pks.

func (*ShardingCache[K, V]) MSet

func (p *ShardingCache[K, V]) MSet(ctx context.Context, models []V, expiration time.Duration) error

MSet serializes and writes multiple models to ShardingCache.

func (*ShardingCache[K, V]) Set

func (p *ShardingCache[K, V]) Set(ctx context.Context, pk K, elem V, expiration time.Duration) error

Set writes a key value pair to ShardingCache.

type ShardingCacheConfig

type ShardingCacheConfig[K comparable, V ShardingModel] struct {

	// Storage must return a Storage implementation which will be used
	// as the underlying key-value storage.
	Storage func(ctx context.Context) Storage

	// IDFunc returns the primary key of a ShardingModel object.
	IDFunc func(V) K

	// KeyFunc specifies the key function to use with the storage.
	KeyFunc Key

	// ShardingSize configures the maximum length of data in a shard.
	// When the serialization result of V is longer than ShardingSize,
	// the data will be split into shards to save to storage.
	//
	// ShardingSize must be greater than zero, else it panics.
	ShardingSize int

	// MGetBatchSize optionally specifies the batch size for one MGet
	// calling to storage. The default is 200.
	MGetBatchSize int

	// MSetBatchSize optionally specifies the batch size for one MSet
	// calling to storage. The default is 200.
	MSetBatchSize int

	// DeleteBatchSize optionally specifies the batch size for one Delete
	// calling to storage. The default is 200.
	DeleteBatchSize int
}

ShardingCacheConfig configures a ShardingCache instance.

type ShardingData

type ShardingData struct {
	TotalNum int32  `protobuf:"varint,1,opt,name=total_num,json=totalNum,proto3" json:"total_num,omitempty"`
	ShardNum int32  `protobuf:"varint,2,opt,name=shard_num,json=shardNum,proto3" json:"shard_num,omitempty"`
	Digest   []byte `protobuf:"bytes,3,opt,name=digest,proto3" json:"digest,omitempty"`
	Data     []byte `protobuf:"bytes,4,opt,name=data,json=data,proto3" json:"data,omitempty"`
}

ShardingData holds sharding information and partial data of a sharding.

Example:

// protobuf
message ShardingData {
	int32 total_num = 1;
	int32 shard_num = 2;
	bytes digest = 3;
	bytes data = 4;
}

type ShardingModel

type ShardingModel interface {
	Model

	// GetShardingData returns whether a model is a shard or a complete model.
	// When the returned bool value is false, the returned ShardingData
	// can be a zero value, and shall not be used.
	GetShardingData() (ShardingData, bool)

	// SetShardingData sets a shard data to a new model created when
	// doing serialization to split data into shards and save to storage.
	SetShardingData(data ShardingData)
}

ShardingModel is the interface implemented by types that can be cached by ShardingCache.

A ShardingModel implementation type should save ShardingData with it, and cna tell whether it's a shard or a complete model.

type Storage

type Storage interface {
	MGet(ctx context.Context, keys ...string) ([][]byte, error)
	MSet(ctx context.Context, kvPairs []KVPair, expiration time.Duration) error
	Delete(ctx context.Context, keys ...string) error
}

Storage is the interface which provides storage for Cache. Users may use any key-value storage to implement this.