store

Documentation

Index

• Constants
• type Entry
  • func (e *Entry) IsExpired() bool
• type Store
  • func New() *Store
  • func NewWithShards(shardCount int) *Store
  • func (s *Store) Delete(key string) bool
  • func (s *Store) Expire(key string, ttl time.Duration) bool
  • func (s *Store) ForEach(fn func(key string, value []byte, ttl time.Duration) bool)
  • func (s *Store) Get(key string) ([]byte, bool)
  • func (s *Store) Keys() []string
  • func (s *Store) Len() int
  • func (s *Store) Set(key string, value []byte, ttl time.Duration)
  • func (s *Store) ShardStats() []int
  • func (s *Store) Stats() StoreStats
• type StoreStats
  • func (s *StoreStats) Snapshot() StoreStats
• type Sweeper
  • func NewSweeper(store *Store, interval time.Duration) *Sweeper
  • func (sw *Sweeper) Start()
  • func (sw *Sweeper) Stop()

Constants

const (
	// DefaultShardCount is the number of shards used to reduce lock contention.
	DefaultShardCount = 256
)

const (
	// DefaultSweepInterval is how often the background sweeper checks a shard.
	DefaultSweepInterval = 100 * time.Millisecond
)

Types

type Entry

type Entry struct {
	Value     []byte
	ExpiresAt time.Time // Zero value means no expiry.
	CreatedAt time.Time
}

Entry represents a single cached value with metadata.

func (*Entry) IsExpired

func (e *Entry) IsExpired() bool

IsExpired returns true if the entry has a TTL and it has passed.

type Store

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

Store is a sharded in-memory key-value store with TTL support. It distributes keys across multiple shards to minimize lock contention.

func New

func New() *Store

New creates a new Store with the default number of shards.

func NewWithShards

func NewWithShards(shardCount int) *Store

NewWithShards creates a new Store with the specified number of shards. shardCount should be a power of 2 for efficient masking.

func (*Store) Delete

func (s *Store) Delete(key string) bool

Delete removes a key from the store. Returns true if the key existed.

func (*Store) Expire

func (s *Store) Expire(key string, ttl time.Duration) bool

Expire updates the TTL on an existing key. Returns true if the key was found. A ttl of 0 removes the expiry (makes the key persistent).

func (*Store) ForEach

func (s *Store) ForEach(fn func(key string, value []byte, ttl time.Duration) bool)

ForEach iterates over all non-expired entries, calling fn for each one. The callback receives a copy of the value. If fn returns false, iteration stops.

func (*Store) Get

func (s *Store) Get(key string) ([]byte, bool)

Get retrieves the value for a key. Returns the value, whether it exists, and any error. Performs lazy expiry — expired entries are deleted on access.

func (*Store) Keys

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

Keys returns all non-expired keys in the store. This is intended for debugging — it scans all shards.

func (*Store) Len

func (s *Store) Len() int

Len returns the count of non-expired entries.

func (*Store) Set

func (s *Store) Set(key string, value []byte, ttl time.Duration)

Set stores a key-value pair with an optional TTL. If ttl is 0, the entry never expires. Overwrites any existing entry for the key.

func (*Store) ShardStats

func (s *Store) ShardStats() []int

ShardStats returns per-shard item counts (for debugging/metrics).

func (*Store) Stats

func (s *Store) Stats() StoreStats

Stats returns a snapshot of the store's operational metrics.

type StoreStats

type StoreStats struct {
	Hits        uint64
	Misses      uint64
	Sets        uint64
	Deletes     uint64
	Expirations uint64
	// contains filtered or unexported fields
}

StoreStats tracks operational metrics for the store.

func (*StoreStats) Snapshot

func (s *StoreStats) Snapshot() StoreStats

Snapshot returns a copy of the current stats.

type Sweeper

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

Sweeper runs a background goroutine that actively expires stale entries. It uses a Redis-inspired approach: sample random keys from each shard and delete expired ones. If the expiry rate is high, repeat immediately.

func NewSweeper

func NewSweeper(store *Store, interval time.Duration) *Sweeper

NewSweeper creates a new TTL sweeper for the given store.

func (*Sweeper) Start

func (sw *Sweeper) Start()

Start begins the background sweep goroutine.

func (*Sweeper) Stop

func (sw *Sweeper) Stop()

Stop signals the sweeper to stop and waits for it to finish.