mem_storage

Documentation

Index

• Variables
• type Config
  • func DefaultConfig() Config
• type MemStorage
  • func New(config Config) (*MemStorage, error)
  • func (s *MemStorage) BatchGet(keys []string) (map[string]*StoredItem, error)
  • func (s *MemStorage) BatchGetNoCopy(keys []string) (map[string]*StoredItem, error)
  • func (s *MemStorage) BatchSet(items map[string]*StoredItem) error
  • func (s *MemStorage) Clear() error
  • func (s *MemStorage) Close(ctx context.Context) error
  • func (s *MemStorage) Delete(key string, version int64) error
  • func (s *MemStorage) Get(key string) (*StoredItem, error)
  • func (s *MemStorage) GetNoCopy(key string) (*StoredItem, error)
  • func (s *MemStorage) GetSyncBuffer() ([]*SyncOperation, error)
  • func (s *MemStorage) Keys() []string
  • func (s *MemStorage) Name() string
  • func (s *MemStorage) Set(key string, item *StoredItem) error
  • func (s *MemStorage) Start(ctx context.Context) error
  • func (s *MemStorage) Stats() Stats
• type OpType
• type Stats
• type StoredItem
  • func (item *StoredItem) Clone() *StoredItem
  • func (item *StoredItem) CompareVersion(other *StoredItem) int
  • func (item *StoredItem) Copy() *StoredItem
  • func (item *StoredItem) DeepCopy() *StoredItem
  • func (item *StoredItem) IsExpired() bool
  • func (item *StoredItem) IsTombstone() bool
  • func (item *StoredItem) IsValid() bool
  • func (item *StoredItem) Reset()
  • func (item *StoredItem) ResolveConflict(other *StoredItem) bool
  • func (item *StoredItem) Size() int64
  • func (item *StoredItem) WithTTL(ttl time.Duration) *StoredItem
  • func (item *StoredItem) WithVersion(version int64) *StoredItem
• type SyncOperation

Variables

var (
	ErrNotFound        = errors.New("item not found")
	ErrExpired         = errors.New("item expired")
	ErrVersionMismatch = errors.New("version mismatch")
	ErrMemoryLimit     = errors.New("memory limit exceeded")
	ErrEmptyKey        = errors.New("empty key")
)

Errors

Types

type Config

type Config struct {
	// MaxMemoryMB limits total memory.
	// Zero or negative values are treated as "use conservative default" for SDK safety.
	MaxMemoryMB int64

	// ShardCount is number of shards (0 = auto: 2-4x CPU cores).
	ShardCount int

	CompressionEnabled bool

	// CompressionThreshold is min size to compress (bytes, default: 64).
	CompressionThreshold int

	// EvictThreshold is memory percentage to start eviction (default: 90).
	EvictThreshold int

	// EvictTarget is target memory percentage after eviction (default: 80).
	EvictTarget int

	// EvictBatchSize is number of keys to evict per batch (default: 10).
	EvictBatchSize int

	// AsyncEviction enables background async eviction (default: true).
	AsyncEviction bool
}

Config configures MemStorage.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns default configuration. Uses LZ4 compression for optimal balance between speed and compression ratio. Includes a conservative in-memory size limit suitable for long-running SDK usage.

type MemStorage

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

MemStorage provides distributed-ready in-memory storage.

func New

func New(config Config) (*MemStorage, error)

New creates a new MemStorage instance.

func (*MemStorage) BatchGet

func (s *MemStorage) BatchGet(keys []string) (map[string]*StoredItem, error)

BatchGet retrieves multiple keys efficiently.

func (*MemStorage) BatchGetNoCopy

func (s *MemStorage) BatchGetNoCopy(keys []string) (map[string]*StoredItem, error)

BatchGetNoCopy retrieves multiple keys without copying.

func (*MemStorage) BatchSet

func (s *MemStorage) BatchSet(items map[string]*StoredItem) error

BatchSet stores multiple key-value pairs efficiently.

func (*MemStorage) Clear

func (s *MemStorage) Clear() error

Clear removes all data.

func (*MemStorage) Close

func (s *MemStorage) Close(ctx context.Context) error

func (*MemStorage) Delete

func (s *MemStorage) Delete(key string, version int64) error

func (*MemStorage) Get

func (s *MemStorage) Get(key string) (*StoredItem, error)

Get retrieves key with automatic decompression. Returns deep copy, safe for modification.

func (*MemStorage) GetNoCopy

func (s *MemStorage) GetNoCopy(key string) (*StoredItem, error)

GetNoCopy retrieves key without copying value.

func (*MemStorage) GetSyncBuffer

func (s *MemStorage) GetSyncBuffer() ([]*SyncOperation, error)

GetSyncBuffer returns pending sync operations from all shards.

func (*MemStorage) Keys

func (s *MemStorage) Keys() []string

Keys returns all keys (expensive, for monitoring only).

func (*MemStorage) Name

func (s *MemStorage) Name() string

lifecycle.Component implementation

func (*MemStorage) Set

func (s *MemStorage) Set(key string, item *StoredItem) error

Set stores key-value with conflict resolution.

Conflict resolution: last-write-wins using version comparison. Concurrent writes are resolved atomically per shard.

func (*MemStorage) Start

func (s *MemStorage) Start(ctx context.Context) error

func (*MemStorage) Stats

func (s *MemStorage) Stats() Stats

type OpType

type OpType int

OpType is operation type.

const (
	OpSet OpType = iota
	OpDelete
)

type Stats

type Stats struct {
	KeyCount         int64
	TotalBytes       int64
	CompressedBytes  int64
	OriginalBytes    int64
	CompressionRatio float64
	GetCount         int64
	SetCount         int64
	HitCount         int64
	MissCount        int64
	HitRate          float64
	EvictCount       int64
}

Stats returns storage statistics.

type StoredItem

type StoredItem struct {
	// Version is the HLC timestamp for conflict resolution.
	// Higher version wins in concurrent writes.
	Version int64

	// ExpireAt is the expiration timestamp (zero = no expiration).
	// Used for TTL management and tombstone cleanup.
	ExpireAt time.Time

	// Value is the stored data (immutable after creation).
	// Must be deep-copied when returned to callers.
	Value []byte

	// Key is the associated key (optional, for convenience).
	// May be empty if item is used without key context.
	Key string
}

StoredItem represents a key-value entry with versioning and TTL. Layout: - Version (8 bytes): Hot path for conflict resolution - ExpireAt (16 bytes): Expiration check - Value (24 bytes slice header): Frequently accessed - Key (16 bytes string header): Accessed less frequently

Memory layout: 64 bytes per item (cache line aligned)

func (*StoredItem) Clone

func (item *StoredItem) Clone() *StoredItem

Clone is an alias for DeepCopy for convenience.

func (*StoredItem) CompareVersion

func (item *StoredItem) CompareVersion(other *StoredItem) int

CompareVersion compares version with another item. Returns: -1 if item < other, 0 if equal, 1 if item > other

func (*StoredItem) Copy

func (item *StoredItem) Copy() *StoredItem

Copy creates a shallow copy (shares Value slice). Use DeepCopy for independent copies.

func (*StoredItem) DeepCopy

func (item *StoredItem) DeepCopy() *StoredItem

DeepCopy creates a full independent copy. Value slice is copied, safe for concurrent modification.

func (*StoredItem) IsExpired

func (item *StoredItem) IsExpired() bool

IsExpired checks if item has expired.

func (*StoredItem) IsTombstone

func (item *StoredItem) IsTombstone() bool

IsTombstone checks if item is a tombstone (deleted marker). Tombstone has empty value but valid version.

func (*StoredItem) IsValid

func (item *StoredItem) IsValid() bool

IsValid checks if item is valid (has value or is tombstone).

func (*StoredItem) Reset

func (item *StoredItem) Reset()

Reset clears all fields for object pool reuse.

func (*StoredItem) ResolveConflict

func (item *StoredItem) ResolveConflict(other *StoredItem) bool

ResolveConflict resolves conflict between two items using last-write-wins. Returns true if 'other' should replace 'item'.

Rules:

• Higher version wins
• If versions equal, prefer non-expired item
• If both expired/not-expired, keep existing (item)

func (*StoredItem) Size

func (item *StoredItem) Size() int64

Size returns approximate memory size in bytes. Includes struct overhead and value length.

func (*StoredItem) WithTTL

func (item *StoredItem) WithTTL(ttl time.Duration) *StoredItem

WithTTL returns a copy with TTL set. ttl <= 0 means no expiration.

func (*StoredItem) WithVersion

func (item *StoredItem) WithVersion(version int64) *StoredItem

WithVersion returns a copy with updated version.

type SyncOperation

type SyncOperation struct {
	Key    string
	OpType OpType
	Item   *StoredItem // nil for DELETE, contains Version and other fields
}

SyncOperation represents a single change for replication. Item already contains Version, so no need to duplicate.