tlru

README

tlru

Package tlru implements TLRU (Time Aware Least Recently Used) cache for Go.

Features:

• Uses generics for type-safety
• Memory-backed
• Safe for concurrent use
• No background threads

go get github.com/ammario/tlru@master

Examples

Basic example:

// This cache can store up to 100 values.
c := tlru.New[string](tlru.ConstantCost[int], 100)
c.Set("dog", 3.14, time.Second)

// 3.14, ~time.Now().Add(time.Second), true
v, deadline, ok := c.Get("dog")

Dynamic costs:

// This cache can store up to 100 bytes.
c := New[string](
    func(v string) int {
        return len(v)
    },
    100,
)
c.Set("some_key", "some value", time.Minute)

Eviction

Cache eviction occurs during:

• Calls to Set()
• Calls to Evict()
• Calls to Get() (for that key only)

Cache eviction is fast because the LRU and TTL indices are sorted. In most cases, a call to the evictor only touches a few entries. Calling Evict() directly is usually unnecessary.

Benchmarks

goos: darwin
goarch: amd64
pkg: github.com/ammario/tlru
cpu: VirtualApple @ 2.50GHz
Benchmark_TLRU_Get-10    	 7117467	       141.9 ns/op
Benchmark_TLRU_Set-10    	 1222298	       990.9 ns/op

Documentation

Overview

Package TLRU implements a basic in-memory TLRU cache.

Index

• func ConstantCost[T any](_ T) int
• type Cache
  • func New[K comparable, V any](cost Coster[V], costLimit int) *Cache[K, V]
  • func (l *Cache[K, V]) Delete(key K) int
  • func (l *Cache[K, V]) Do(key K, fn func() (V, error), ttl time.Duration) (V, error)
  • func (l *Cache[K, V]) Evict() int
  • func (l *Cache[K, V]) Get(key K) (v V, deadline time.Time, exists bool)
  • func (l *Cache[K, V]) Set(key K, v V, ttl time.Duration)
• type Coster

Functions

func ConstantCost

func ConstantCost[T any](_ T) int

ConstantCost always returns 1.

Types

type Cache

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

Cache implements a time aware least-frequently-used cache structure. When the cache exceeds a given cost limit, the oldest chunks of data are discarded.

func New

func New[K comparable, V any](cost Coster[V], costLimit int) *Cache[K, V]

New instantiates a ready-to-use LRU cache. It is safe for concurrent use. If cost is nil, a constant cost of 1 is assumed. Use -1 for costLimit to disable cost limiting.

func (*Cache[K, V]) Delete

func (l *Cache[K, V]) Delete(key K) int

Delete removes an entry from the cache, returning cost savings.

func (*Cache[K, V]) Do

func (l *Cache[K, V]) Do(key K, fn func() (V, error), ttl time.Duration) (V, error)

Do is a helper that retrieves a value from the cache, if it exists, and calls the provided function to compute the value if it does not.

The return signature omits deadline and exists for ergonomics.

func (*Cache[K, V]) Evict

func (l *Cache[K, V]) Evict() int

Evict removes all expired entries from the cache. Bear in mind Set and Delete will also evict entries, so most users should not call Evict directly.

func (*Cache[K, V]) Get

func (l *Cache[K, V]) Get(key K) (v V, deadline time.Time, exists bool)

Get retrieves a value from the cache, if it exists.

func (*Cache[K, V]) Set

func (l *Cache[K, V]) Set(key K, v V, ttl time.Duration)

Set adds a new value to the cache. Set may also be used to bump a value to the top of the cache.

type Coster

type Coster[T any] func(v T) int

Coster is a function that returns the approximate memory cost of a given value.