Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Cache ¶
type Cache[K comparable, V any] interface { // Put inserts or replaces the value associated with key. Put(key K, value V) // Get returns the value and whether key is present. Get(key K) (V, bool) // Delete removes key if present. Delete(key K) // Stats returns the cache counters and configured capacity. Stats() Stats }
Cache stores values by key and exposes hit, miss, and entry counters.
func NewNonExpiringMapCache ¶
func NewNonExpiringMapCache[K comparable, V any](capacity int) Cache[K, V]
func NewShardedSieve ¶ added in v1.0.0
func NewShardedSieve[K comparable, V any](totalCapacity int, shards int, shardFn func(key K) uint64) Cache[K, V]
NewShardedSieve creates a sharded second-chance cache with the supplied total capacity distributed across shards. The shardFn maps keys to hash values; only the low bits are used. A nil shardFn routes every key to one shard. A capacity of zero or less yields a single shard of capacity one, matching NewSieve.
func NewSieve ¶
func NewSieve[K comparable, V any](capacity int) Cache[K, V]
NewSieve creates a new Sieve cache with the supplied capacity.
If `capacity` is less than or equal to zero, a capacity of one is used to prevent function calls from panicking. The returned value implements the `Cache[K,V]` interface.
type NonExpiringMapCache ¶
type NonExpiringMapCache[K comparable, V any] struct { // contains filtered or unexported fields }
NonExpiringMapCache
func (*NonExpiringMapCache[K, V]) Delete ¶
func (s *NonExpiringMapCache[K, V]) Delete(key K)
func (*NonExpiringMapCache[K, V]) Get ¶
func (s *NonExpiringMapCache[K, V]) Get(key K) (V, bool)
func (*NonExpiringMapCache[K, V]) Put ¶
func (s *NonExpiringMapCache[K, V]) Put(key K, value V)
func (*NonExpiringMapCache[K, V]) Stats ¶
func (s *NonExpiringMapCache[K, V]) Stats() Stats
type ShardedSieve ¶ added in v1.0.0
type ShardedSieve[K comparable, V any] struct { // contains filtered or unexported fields }
ShardedSieve distributes a fixed total capacity over independent Sieve shards. Lookups, insertions and statistics touch only the shard selected by the caller's hash function, so concurrent access spreads lock and counter traffic across shards instead of serializing on a single mutex and a single set of statistic words.
The shard count is rounded up to a power of two and then capped at the largest power of two not exceeding the total capacity, so every shard holds at least one entry and the sum of shard capacities equals the requested total. Eviction (second chance) operates within each shard; entries do not migrate between shards.
func (*ShardedSieve[K, V]) Delete ¶ added in v1.0.0
func (s *ShardedSieve[K, V]) Delete(key K)
Delete removes the entry identified by key from the key's shard.
func (*ShardedSieve[K, V]) Get ¶ added in v1.0.0
func (s *ShardedSieve[K, V]) Get(key K) (V, bool)
Get retrieves the value associated with key from the key's shard.
func (*ShardedSieve[K, V]) Put ¶ added in v1.0.0
func (s *ShardedSieve[K, V]) Put(key K, value V)
Put adds or updates the value associated with key in the key's shard.
func (*ShardedSieve[K, V]) Stats ¶ added in v1.0.0
func (s *ShardedSieve[K, V]) Stats() Stats
Stats returns aggregated statistics across all shards. The returned value snapshots the shard counters at the moment of the call.
type Sieve ¶
type Sieve[K comparable, V any] struct { // contains filtered or unexported fields }
Sieve implements a clock‑hand (second‑chance) cache with a fixed capacity. It is safe for concurrent use by multiple goroutines.
The cache maintains:
- a map (`store`) from keys to entries for O(1) lookups,
- a doubly‑linked list (`queue`) that orders entries from most recently inserted (front) to least recently inserted (back),
- a “hand” pointer that walks the list during eviction, giving each entry a second chance if it has been visited since the previous sweep.
Statistics about cache usage are collected in the embedded `stats` field.
func (*Sieve[K, V]) Delete ¶
func (s *Sieve[K, V]) Delete(key K)
Delete removes the entry identified by `key` from the cache.
If the entry being removed is currently pointed to by the clock hand, the hand is moved one step backward so that eviction can continue correctly. The method records a deletion in the statistics.
The operation holds an exclusive lock for the duration of the removal.
func (*Sieve[K, V]) Get ¶
Get retrieves the value associated with `key`.
If the key is present, the entry’s visited flag is set, a hit is recorded, and the cached value is returned with `true`. If the key is absent, a miss is recorded and the zero value of V is returned with `false`.
The operation holds a read lock while accessing the map.
func (*Sieve[K, V]) Put ¶
func (s *Sieve[K, V]) Put(key K, value V)
Put adds or updates the value associated with `key`.
If the key already exists, its value is replaced and the entry is marked as visited (so it will survive the next eviction sweep). If the key is new, a fresh entry is inserted, possibly triggering an eviction when the cache is full.
The operation holds an exclusive lock for the duration of the update.
type Stats ¶
type Stats struct {
// Capacity is the configured maximum entry count.
Capacity int
// contains filtered or unexported fields
}
Stats holds shared atomic cache counters and a fixed entry capacity. Copying Stats shares the counters; Combined produces independent counters.
func (Stats) Combined ¶
Combined snapshots and sums two sets of counters into independent statistics.
func (Stats) Miss ¶
func (s Stats) Miss()
Miss atomically records one lookup without a cached entry.
Source Files