ttlmap

README

ttlmap-go

This is sync.Map with generics and automatic expiration of entries. It's useful for implementing time-bound caches.

Features:

• Guarantees that entries live at least as long as a set timeout
• Thread-safe (using Go's sync.Map internally)
• Generics!
• No dependencies
• No close method, can be forgotten and GC'd anytime
• No footguns, API cannot be misused
• Full test coverage

This is yet another TTL map because existing implementations did not quite fit my need. If you need timeouts per item, then also check out mailgun's implementation! It takes a bit of a different approach, e.g. deletes on access or upon reaching a capacity limit.

Usage

import "github.com/mologie/ttlmap-go"

m := ttlmap.New[string, string](1 * time.Second)

m.Store("a", "foo")
time.Sleep(2 * time.Second)

m.Store("b", "bar")
time.Sleep(2 * time.Second)

if _, ok := m.Load("a"); ok {
	panic("unreachable")
} else {
	println("entry a does not exist, because b's write scheduled cleanup")
}

if _, ok := m.Load("b"); ok {
	println("entry b still exists despite having expired, because no write happened after it")
} else {
	panic("unreachable")
}

See cmd/ttlmap-demo/main.go for a more elaborate demo involving Reaper, which cleans up entries during periods without write activity.

License

This library is provided under the terms of the MIT license.

Documentation

Index

• type Option
  • func WithExpirationCallback[K comparable, V any](f func(key K, value V)) Option[K, V]
• type Reaper
  • func NewReaper[K comparable, V any](m *TTLMap[K, V]) *Reaper
  • func NewReaperWithInterval[K comparable, V any](m *TTLMap[K, V], d time.Duration) *Reaper
  • func (b *Reaper) Close()
• type TTLMap
  • func New[K comparable, V any](timeout time.Duration, options ...Option[K, V]) *TTLMap[K, V]
  • func (m *TTLMap[K, V]) CleanNow()
  • func (m *TTLMap[K, V]) Delete(key K)
  • func (m *TTLMap[K, V]) Load(key K) (value V, ok bool)
  • func (m *TTLMap[K, V]) LoadAndDelete(key K) (value V, loaded bool)
  • func (m *TTLMap[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool)
  • func (m *TTLMap[K, V]) Range(f func(key K, value V) bool)
  • func (m *TTLMap[K, V]) Store(key K, value V)

Types

type Option

type Option[K, V any] func(*TTLMap[K, V])

func WithExpirationCallback

func WithExpirationCallback[K comparable, V any](f func(key K, value V)) Option[K, V]

type Reaper

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

Reaper regularly expunges expired entries from a TTLMap

func NewReaper

func NewReaper[K comparable, V any](m *TTLMap[K, V]) *Reaper

NewReaper creates a new Reaper that will clean the map with a reasonable default interval.

func NewReaperWithInterval

func NewReaperWithInterval[K comparable, V any](m *TTLMap[K, V], d time.Duration) *Reaper

NewReaperWithInterval creates a new Reaper that will clean the map with a custom interval.

func (*Reaper) Close

func (b *Reaper) Close()

type TTLMap

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

TTLMap provides a thread-safe map which eventually deletes its entries after timeout, as long as there are occasional writes to the map. Its semantics are otherwise identical to sync.Map. A TTLMap must not be copied after first use. When writes are very seldom, then Reaper may be used for periodic cleanup.

func New

func New[K comparable, V any](timeout time.Duration, options ...Option[K, V]) *TTLMap[K, V]

func (*TTLMap[K, V]) CleanNow

func (m *TTLMap[K, V]) CleanNow()

CleanNow synchronously cleans up most expired entries. Entries that are inserted and expire while CleanNow is running may be skipped. If a concurrent CleanNow is already running, CleanNow returns immediately without performing any work.

func (*TTLMap[K, V]) Delete

func (m *TTLMap[K, V]) Delete(key K)

func (*TTLMap[K, V]) Load

func (m *TTLMap[K, V]) Load(key K) (value V, ok bool)

func (*TTLMap[K, V]) LoadAndDelete

func (m *TTLMap[K, V]) LoadAndDelete(key K) (value V, loaded bool)

func (*TTLMap[K, V]) LoadOrStore

func (m *TTLMap[K, V]) LoadOrStore(key K, value V) (actual V, loaded bool)

func (*TTLMap[K, V]) Range

func (m *TTLMap[K, V]) Range(f func(key K, value V) bool)

func (*TTLMap[K, V]) Store

func (m *TTLMap[K, V]) Store(key K, value V)