Skip to content

Latest commit

 

History

History
694 lines (481 loc) · 25.8 KB

doc.MD

File metadata and controls

694 lines (481 loc) · 25.8 KB
Raw

freelru

import "github.com/fufuok/freelru"

Index

func MakeHasher

func MakeHasher[T comparable]() func(T) uint32

MakeHasher creates a fast hash function for the given comparable type. The only limitation is that the type should not contain interfaces inside based on runtime.typehash. Thanks to @puzpuzpuz for the idea in xsync.

type Cache

type Cache[K comparable, V any] interface {
    // SetLifetime sets the default lifetime of LRU elements.
    // Lifetime 0 means "forever".
    SetLifetime(lifetime time.Duration)

    // SetOnEvict sets the OnEvict callback function.
    // The onEvict function is called for each evicted lru entry.
    SetOnEvict(onEvict OnEvictCallback[K, V])

    // Len returns the number of elements stored in the cache.
    Len() int

    // AddWithLifetime adds a key:value to the cache with a lifetime.
    // Returns true, true if key was updated and eviction occurred.
    AddWithLifetime(key K, value V, lifetime time.Duration) (evicted bool)

    // Add adds a key:value to the cache.
    // Returns true, true if key was updated and eviction occurred.
    Add(key K, value V) (evicted bool)

    // Get retrieves an element from map under given key.
    Get(key K) (V, bool)

    // Peek retrieves an element from map under given key without updating the
    // "recently used"-ness of that key.
    Peek(key K) (V, bool)

    // Contains checks for the existence of a key, without changing its recent-ness.
    Contains(key K) bool

    // Remove removes an element from the map.
    // The return value indicates whether the key existed or not.
    Remove(key K) bool

    // Keys returns a slice of the keys in the cache, from oldest to newest.
    Keys() []K

    // Purge purges all data (key and value) from the LRU.
    Purge()

    // Metrics returns the metrics of the cache.
    Metrics() Metrics

    // ResetMetrics resets the metrics of the cache and returns the previous state.
    ResetMetrics() Metrics
}

type HashKeyCallback

HashKeyCallback is the function that creates a hash from the passed key.

type HashKeyCallback[K comparable] func(K) uint32

type LRU

LRU implements a non-thread safe fixed size LRU cache.

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

func New

func New[K comparable, V any](capacity uint32, hash HashKeyCallback[K]) (*LRU[K, V], error)

New constructs an LRU with the given capacity of elements. The hash function calculates a hash value from the keys.

func NewDefault

func NewDefault[K comparable, V any](capacity uint32, lifetime ...time.Duration) (*LRU[K, V], error)

NewDefault constructs an LRU with the given capacity of elements. The hash function calculates a hash value from the keys.

func NewWithSize

func NewWithSize[K comparable, V any](capacity, size uint32, hash HashKeyCallback[K]) (*LRU[K, V], error)

NewWithSize constructs an LRU with the given capacity and size. The hash function calculates a hash value from the keys. A size greater than the capacity increases memory consumption and decreases the CPU consumption by reducing the chance of collisions. Size must not be lower than the capacity.

func NewWithSizeDefault

func NewWithSizeDefault[K comparable, V any](capacity, size uint32, lifetime ...time.Duration) (*LRU[K, V], error)

NewWithSizeDefault constructs an LRU with the given capacity and size. The hash function calculates a hash value from the keys. A size greater than the capacity increases memory consumption and decreases the CPU consumption by reducing the chance of collisions. Size must not be lower than the capacity.

func (*LRU[K, V]) Add

func (lru *LRU[K, V]) Add(key K, value V) (evicted bool)

Add adds a key:value to the cache. Returns true, true if key was updated and eviction occurred.

func (*LRU[K, V]) AddWithLifetime

func (lru *LRU[K, V]) AddWithLifetime(key K, value V, lifetime time.Duration) (evicted bool)

AddWithLifetime adds a key:value to the cache with a lifetime. Returns true, true if key was updated and eviction occurred.

func (*LRU[K, V]) Contains

func (lru *LRU[K, V]) Contains(key K) (ok bool)

Contains checks for the existence of a key, without changing its recent-ness.

func (*LRU[K, V]) Get

func (lru *LRU[K, V]) Get(key K) (value V, ok bool)

Get looks up a key's value from the cache, setting it as the most recently used item.

func (*LRU[K, V]) Keys

func (lru *LRU[K, V]) Keys() []K

Keys returns a slice of the keys in the cache, from oldest to newest.

func (*LRU[K, V]) Len

func (lru *LRU[K, V]) Len() int

Len returns the number of elements stored in the cache.

func (*LRU[K, V]) Metrics

func (lru *LRU[K, V]) Metrics() Metrics

Metrics returns the metrics of the cache.

func (*LRU[K, V]) Peek

func (lru *LRU[K, V]) Peek(key K) (value V, ok bool)

Peek looks up a key's value from the cache, without changing its recent-ness.

func (*LRU[K, V]) PrintStats

func (lru *LRU[K, V]) PrintStats()

func (*LRU[K, V]) Purge

func (lru *LRU[K, V]) Purge()

Purge purges all data (key and value) from the LRU.

func (*LRU[K, V]) Remove

func (lru *LRU[K, V]) Remove(key K) (removed bool)

Remove removes the key from the cache. The return value indicates whether the key existed or not.

func (*LRU[K, V]) ResetMetrics

func (lru *LRU[K, V]) ResetMetrics() Metrics

ResetMetrics resets the metrics of the cache and returns the previous state.

func (*LRU[K, V]) SetLifetime

func (lru *LRU[K, V]) SetLifetime(lifetime time.Duration)

SetLifetime sets the default lifetime of LRU elements. Lifetime 0 means "forever".

func (*LRU[K, V]) SetOnEvict

func (lru *LRU[K, V]) SetOnEvict(onEvict OnEvictCallback[K, V])

SetOnEvict sets the OnEvict callback function. The onEvict function is called for each evicted lru entry.

type Metrics

Metrics contains metrics about the cache.

type Metrics struct {
    Inserts    uint64
    Collisions uint64
    Evictions  uint64
    Removals   uint64
    Hits       uint64
    Misses     uint64
    Capacity   uint32
    Lifetime   string
    Len        int
}

type OnEvictCallback

OnEvictCallback is the function type for Config.OnEvict.

type OnEvictCallback[K comparable, V any] func(K, V)

type ShardedLRU

ShardedLRU is a thread-safe, sharded, fixed size LRU cache. Sharding is used to reduce lock contention on high concurrency. The downside is that exact LRU behavior is not given (as for the LRU and SynchedLRU types).

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

func NewSharded

func NewSharded[K comparable, V any](capacity uint32, hash HashKeyCallback[K]) (*ShardedLRU[K, V], error)

NewSharded creates a new thread-safe sharded LRU hashmap with the given capacity.

func NewShardedDefault

func NewShardedDefault[K comparable, V any](capacity uint32, lifetime ...time.Duration) (*ShardedLRU[K, V], error)

NewShardedDefault creates a new thread-safe sharded LRU hashmap with the given capacity.

func NewShardedWithSize

func NewShardedWithSize[K comparable, V any](shards, capacity, size uint32, hash HashKeyCallback[K]) (*ShardedLRU[K, V], error)

func NewShardedWithSizeDefault

func NewShardedWithSizeDefault[K comparable, V any](shards, capacity, size uint32, lifetime ...time.Duration) (*ShardedLRU[K, V], error)

func (*ShardedLRU[K, V]) Add

func (lru *ShardedLRU[K, V]) Add(key K, value V) (evicted bool)

Add adds a key:value to the cache. Returns true, true if key was updated and eviction occurred.

func (*ShardedLRU[K, V]) AddWithLifetime

func (lru *ShardedLRU[K, V]) AddWithLifetime(key K, value V, lifetime time.Duration) (evicted bool)

AddWithLifetime adds a key:value to the cache with a lifetime. Returns true, true if key was updated and eviction occurred.

func (*ShardedLRU[K, V]) Contains

func (lru *ShardedLRU[K, V]) Contains(key K) (ok bool)

Contains checks for the existence of a key, without changing its recent-ness.

func (*ShardedLRU[K, V]) Get

func (lru *ShardedLRU[K, V]) Get(key K) (value V, ok bool)

Get looks up a key's value from the cache, setting it as the most recently used item.

func (*ShardedLRU[K, V]) Keys

func (lru *ShardedLRU[K, V]) Keys() []K

Keys returns a slice of the keys in the cache, from oldest to newest.

func (*ShardedLRU[K, V]) Len

func (lru *ShardedLRU[K, V]) Len() (length int)

Len returns the number of elements stored in the cache.

func (*ShardedLRU[K, V]) Metrics

func (lru *ShardedLRU[K, V]) Metrics() Metrics

Metrics returns the metrics of the cache.

func (*ShardedLRU[K, V]) Peek

func (lru *ShardedLRU[K, V]) Peek(key K) (value V, ok bool)

Peek looks up a key's value from the cache, without changing its recent-ness.

func (*ShardedLRU[K, V]) PrintStats

func (lru *ShardedLRU[K, V]) PrintStats()

func (*ShardedLRU[K, V]) Purge

func (lru *ShardedLRU[K, V]) Purge()

Purge purges all data (key and value) from the LRU.

func (*ShardedLRU[K, V]) Remove

func (lru *ShardedLRU[K, V]) Remove(key K) (removed bool)

Remove removes the key from the cache. The return value indicates whether the key existed or not.

func (*ShardedLRU[K, V]) ResetMetrics

func (lru *ShardedLRU[K, V]) ResetMetrics() Metrics

ResetMetrics resets the metrics of the cache and returns the previous state.

func (*ShardedLRU[K, V]) SetLifetime

func (lru *ShardedLRU[K, V]) SetLifetime(lifetime time.Duration)

SetLifetime sets the default lifetime of LRU elements. Lifetime 0 means "forever".

func (*ShardedLRU[K, V]) SetOnEvict

func (lru *ShardedLRU[K, V]) SetOnEvict(onEvict OnEvictCallback[K, V])

SetOnEvict sets the OnEvict callback function. The onEvict function is called for each evicted lru entry.

type SyncedLRU

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

func NewSynced

func NewSynced[K comparable, V any](capacity uint32, hash HashKeyCallback[K]) (*SyncedLRU[K, V], error)

NewSynced creates a new thread-safe LRU hashmap with the given capacity.

func NewSyncedDefault

func NewSyncedDefault[K comparable, V any](capacity uint32, lifetime ...time.Duration) (*SyncedLRU[K, V], error)

NewSyncedDefault creates a new thread-safe LRU hashmap with the given capacity.

func NewSyncedWithSize

func NewSyncedWithSize[K comparable, V any](capacity, size uint32, hash HashKeyCallback[K]) (*SyncedLRU[K, V], error)

func NewSyncedWithSizeDefault

func NewSyncedWithSizeDefault[K comparable, V any](capacity, size uint32, lifetime ...time.Duration) (*SyncedLRU[K, V], error)

func (*SyncedLRU[K, V]) Add

func (lru *SyncedLRU[K, V]) Add(key K, value V) (evicted bool)

Add adds a key:value to the cache. Returns true, true if key was updated and eviction occurred.

func (*SyncedLRU[K, V]) AddWithLifetime

func (lru *SyncedLRU[K, V]) AddWithLifetime(key K, value V, lifetime time.Duration) (evicted bool)

AddWithLifetime adds a key:value to the cache with a lifetime. Returns true, true if key was updated and eviction occurred.

func (*SyncedLRU[K, V]) Contains

func (lru *SyncedLRU[K, V]) Contains(key K) (ok bool)

Contains checks for the existence of a key, without changing its recent-ness.

func (*SyncedLRU[K, V]) Get

func (lru *SyncedLRU[K, V]) Get(key K) (value V, ok bool)

Get looks up a key's value from the cache, setting it as the most recently used item.

func (*SyncedLRU[K, V]) Keys

func (lru *SyncedLRU[K, V]) Keys() (keys []K)

Keys returns a slice of the keys in the cache, from oldest to newest.

func (*SyncedLRU[K, V]) Len

func (lru *SyncedLRU[K, V]) Len() (length int)

Len returns the number of elements stored in the cache.

func (*SyncedLRU[K, V]) Metrics

func (lru *SyncedLRU[K, V]) Metrics() Metrics

Metrics returns the metrics of the cache.

func (*SyncedLRU[K, V]) Peek

func (lru *SyncedLRU[K, V]) Peek(key K) (value V, ok bool)

Peek looks up a key's value from the cache, without changing its recent-ness.

func (*SyncedLRU[K, V]) PrintStats

func (lru *SyncedLRU[K, V]) PrintStats()

func (*SyncedLRU[K, V]) Purge

func (lru *SyncedLRU[K, V]) Purge()

Purge purges all data (key and value) from the LRU.

func (*SyncedLRU[K, V]) Remove

func (lru *SyncedLRU[K, V]) Remove(key K) (removed bool)

Remove removes the key from the cache. The return value indicates whether the key existed or not.

func (*SyncedLRU[K, V]) ResetMetrics

func (lru *SyncedLRU[K, V]) ResetMetrics() Metrics

ResetMetrics resets the metrics of the cache and returns the previous state.

func (*SyncedLRU[K, V]) SetLifetime

func (lru *SyncedLRU[K, V]) SetLifetime(lifetime time.Duration)

SetLifetime sets the default lifetime of LRU elements. Lifetime 0 means "forever".

func (*SyncedLRU[K, V]) SetOnEvict

func (lru *SyncedLRU[K, V]) SetOnEvict(onEvict OnEvictCallback[K, V])

SetOnEvict sets the OnEvict callback function. The onEvict function is called for each evicted lru entry.

Generated by gomarkdoc