Documentation
¶
Overview ¶
Package sharded implements a high‑throughput, zero‑allocation sharded map intended for in‑memory cache workloads. Hot paths (Get/Set/Remove) avoid allocations and keep critical sections short. Global counters are atomics so they can be read without locks.
Index ¶
- Constants
- type LRUMode
- type Map
- func (m *Map[V]) AddMem(key uint64, delta int64)
- func (m *Map[V]) Clear()
- func (m *Map[V]) EnqueueExpired(key uint64) bool
- func (m *Map[V]) EvictUntilWithinLimit(limit, backoff int64) (freed, evicted int64)
- func (m *Map[V]) Get(key uint64) (value V, ok bool)
- func (m *Map[V]) Len() int64
- func (m *Map[V]) Mem() int64
- func (m *Map[V]) NextQueuedWithExpiredTTL() (V, bool)
- func (m *Map[V]) NextShard() *Shard[V]
- func (m *Map[V]) PeekExpiredTTL() (V, bool)
- func (m *Map[V]) PickVictim(shardsSample, keysSample int64) (bestShard *Shard[V], victim V, ok bool)
- func (m *Map[V]) Remove(key uint64) (freedBytes int64, hit bool)
- func (m *Map[V]) Set(key uint64, value V)
- func (m *Map[V]) Shard(key uint64) *Shard[V]
- func (m *Map[V]) Touch(key uint64)
- func (m *Map[V]) UsingListing() bool
- func (m *Map[V]) UsingSampling() bool
- func (m *Map[V]) WalkShards(ctx context.Context, fn func(key uint64, shard *Shard[V]))
- func (m *Map[V]) WalkShardsConcurrent(ctx context.Context, concurrency int, fn func(key uint64, shard *Shard[V]))
- type Shard
- func (sh *Shard[V]) AddMem(delta int64)
- func (sh *Shard[V]) Clear() (freedBytes int64, items int64)
- func (sh *Shard[V]) DequeueExpired() (uint64, bool)
- func (sh *Shard[V]) EnqueueRefresh(key uint64) bool
- func (sh *Shard[V]) Get(key uint64) (value V, hit bool)
- func (sh *Shard[V]) ID() uint64
- func (sh *Shard[V]) Len() int64
- func (sh *Shard[V]) Remove(key uint64) (freedBytes int64, hit bool)
- func (sh *Shard[V]) RemoveUnlocked(key uint64) (freedBytes int64, hit bool)
- func (sh *Shard[V]) Set(key uint64, new V) (bytesDelta int64, lenDelta int64)
- func (sh *Shard[V]) Walk(ctx context.Context, fn func(uint64, V) bool, write bool)
- func (sh *Shard[V]) WalkR(ctx context.Context, fn func(uint64, V) bool)
- func (sh *Shard[V]) WalkW(ctx context.Context, fn func(uint64, V) bool)
- func (sh *Shard[V]) Weight() int64
- type Value
Constants ¶
const (
NumOfShards = 1024
)
Tunables.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Map ¶
type Map[V Value] struct { // contains filtered or unexported fields }
Map is a sharded concurrent map with precise global counters.
func NewMap ¶
NewMap creates the map and initializes shards. A lightweight gauge updater runs once per second and exits with ctx.
func (*Map[V]) Clear ¶ added in v1.4.0
func (m *Map[V]) Clear()
Clear wipes all shards and fixes global counters atomically.
func (*Map[V]) EnqueueExpired ¶ added in v1.7.0
EnqueueExpired tries to put key to its shard refresh queue.
func (*Map[V]) EvictUntilWithinLimit ¶ added in v1.6.0
func (*Map[V]) NextQueuedWithExpiredTTL ¶ added in v1.7.0
NextQueuedWithExpiredTTL tries to pop one queued key from up to 'probes' shards.
func (*Map[V]) PeekExpiredTTL ¶ added in v1.7.0
func (*Map[V]) PickVictim ¶ added in v1.6.0
func (*Map[V]) UsingListing ¶ added in v1.6.0
func (*Map[V]) UsingSampling ¶ added in v1.6.0
func (*Map[V]) WalkShards ¶
WalkShards applies fn to all shards synchronously (zero-alloc).
type Shard ¶
Shard is an independent segment of the sharded map. It keeps per-shard counters read with atomics so global readers can avoid locks.
func (*Shard[V]) Clear ¶ added in v0.9.7
Clear removes all entries and returns (freedBytes, itemsRemoved). Reservoirs are kept intact; stale keys are naturally validated&skipped.
func (*Shard[V]) DequeueExpired ¶ added in v1.7.0
DequeueExpired remove key from refresh bucket
func (*Shard[V]) EnqueueRefresh ¶ added in v1.7.0
EnqueueRefresh insert key into refresh bucket
func (*Shard[V]) RemoveUnlocked ¶ added in v1.6.0
RemoveUnlocked deletes a key when the shard is already exclusively locked.
func (*Shard[V]) WalkR ¶ added in v1.4.4
WalkR iterates (k,v) under a shared lock. The callback must be lightweight.
Source Files