timedmap

README

~ timedmap ~

A map which has expiring key-value pairs.

       

---

go get -u github.com/zekroTJA/timedmap/v2

---

Intro

This package allows to set values to a map which will expire and disappear after a specified time.

Here you can read the docs of this package, generated by pkg.go.dev.

[!IMPORTANT]
The package has been updated to v2 which will introduce breaking changes to v1.

• The package now requires a minimum Go version of v1.19.
• TimedMap and corresponding constructor function now take type parameters for key and value types for improved type safety.
• Sections have been removed in favor of performance and simplicity of the package.
• Previously deprecated functions have been removed.

If you experience issues with v1, please create an issue with the specific version mentioned. v1 will still receive updates for bugs and incosistencies alongside v2.

---

Usage Example

package main

import (
	"log"
	"time"

	"github.com/zekroTJA/timedmap/v2"
)

func main() {

	// Creates a new timed map which scans for
	// expired keys every 1 second
	tm := timedmap.New[string, int](1 * time.Second)

	// Add a key "hey" with the value 213, which should
	// expire after 3 seconds and execute the callback, which
	// prints that the key was expired
	tm.Set("hey", 213, 3*time.Second, func(v int) {
		log.Println("key-value pair of 'hey' has expired")
	})

	// Print key "hey" from timed map
	printKeyVal(tm, "hey")

	// Wait for 5 seconds
	// During this time the main thread is blocked, the
	// key-value pair of "hey" will be expired
	time.Sleep(5 * time.Second)

	// Printing value of key "hey" wil lfail because the
	// key-value pair does not exist anymore
	printKeyVal(tm, "hey")
}

func printKeyVal(tm *timedmap.TimedMap[string, int], key string) {
	d, ok := tm.GetValue(key)
	if !ok {
		log.Println("data expired")
		return
	}

	log.Printf("%v = %d\n", key, d)
}

Further examples, you can find in the examples directory.

If you want to see this package in a practcal use case scenario, please take a look at the rate limiter implementation of the REST API of myrunes.com, where I have used timedmap for storing client-based limiter instances:
https://github.com/myrunes/backend/blob/master/internal/ratelimit/ratelimit.go

---

Copyright (c) 2020 zekro Development (Ringo Hoffmann).
Covered by MIT licence.

Documentation

Index

• Variables
• type Callback
• type Element
• type TimedMap
  • func FromMap[TKey comparable, TVal any](m map[TKey]TVal, expiration time.Duration, cleanupTickTime time.Duration, ...) (*TimedMap[TKey, TVal], error)
  • func New[TKey comparable, TVal any](cleanupTickTime time.Duration, tickerChan ...<-chan time.Time) *TimedMap[TKey, TVal]
  • func (tm *TimedMap[TKey, TVal]) Contains(key TKey) bool
  • func (tm *TimedMap[TKey, TVal]) Flush()
  • func (tm *TimedMap[TKey, TVal]) GetExpires(key TKey) (time.Time, error)
  • func (tm *TimedMap[TKey, TVal]) GetValue(key TKey) (val TVal, ok bool)
  • func (tm *TimedMap[TKey, TVal]) Refresh(key TKey, d time.Duration) error
  • func (tm *TimedMap[TKey, TVal]) Remove(key TKey)
  • func (tm *TimedMap[TKey, TVal]) Set(key TKey, value TVal, expiresAfter time.Duration, cb ...Callback[TVal])
  • func (tm *TimedMap[TKey, TVal]) SetExpires(key TKey, d time.Duration) error
  • func (tm *TimedMap[TKey, TVal]) Size() int
  • func (tm *TimedMap[TKey, TVal]) Snapshot() map[TKey]TVal
  • func (tm *TimedMap[TKey, TVal]) StartCleanerExternal(initiator <-chan time.Time)
  • func (tm *TimedMap[TKey, TVal]) StartCleanerInternal(interval time.Duration)
  • func (tm *TimedMap[TKey, TVal]) StopCleaner()

Variables

var (
	// ErrKeyNotFound is returned when a key was
	// requested which is not present in the map.
	ErrKeyNotFound = errors.New("key not found")

	// ErrValueNoMap is returned when a value passed
	// expected was of another type.
	ErrValueNoMap = errors.New("value is not of type map")
)

Types

type Callback

type Callback[TVal any] func(value TVal)

Callback is a function which can be called when a key-value-pair has expired.

type Element

type Element[TVal any] struct {
	// contains filtered or unexported fields
}

Element contains the actual value as interface type, the time when the value expires and an array of callbacks, which will be executed when the Element expires.

type TimedMap

type TimedMap[TKey comparable, TVal any] struct {
	// contains filtered or unexported fields
}

TimedMap is a key-value map with lifetimes attached to values. Expired values are removed on access or via a cleanup coroutine, which can be enabled via the StartCleanerInternal method.

func FromMap

func FromMap[TKey comparable, TVal any](
	m map[TKey]TVal,
	expiration time.Duration,
	cleanupTickTime time.Duration,
	tickerChan ...<-chan time.Time,
) (*TimedMap[TKey, TVal], error)

FromMap creates a new TimedMap containing all entries from the passed map m. Each entry will get assigned the passed expiration duration.

func New

func New[TKey comparable, TVal any](cleanupTickTime time.Duration, tickerChan ...<-chan time.Time) *TimedMap[TKey, TVal]

New creates and returns a new instance of TimedMap. The passed cleanupTickTime will be passed to the cleanup ticker, which iterates through the map and deletes expired key-value pairs on each iteration.

Optionally, you can also pass a custom <-chan time.Time, which controls the cleanup cycle if you want to use a single synchronized timer or if you want to have more granular control over the cleanup loop.

When passing 0 as cleanupTickTime and no tickerChan, the cleanup loop will not be started. You can call StartCleanerInternal or StartCleanerExternal to manually start the cleanup loop. These both methods can also be used to re-define the specification of the cleanup loop when already running if you want to.

func (*TimedMap[TKey, TVal]) Contains

func (tm *TimedMap[TKey, TVal]) Contains(key TKey) bool

Contains returns true, if the key exists in the map. false will be returned, if there is no value to the key or if the key-value pair was expired.

func (*TimedMap[TKey, TVal]) Flush

func (tm *TimedMap[TKey, TVal]) Flush()

Flush deletes all key-value pairs of the map.

func (*TimedMap[TKey, TVal]) GetExpires

func (tm *TimedMap[TKey, TVal]) GetExpires(key TKey) (time.Time, error)

GetExpires returns the expiry time of a key-value pair. If the key-value pair does not exist in the map or was expired, this will return an error object.

func (*TimedMap[TKey, TVal]) GetValue

func (tm *TimedMap[TKey, TVal]) GetValue(key TKey) (val TVal, ok bool)

GetValue returns an interface of the value of a key in the map. The returned value is nil if there is no value to the passed key or if the value was expired.

func (*TimedMap[TKey, TVal]) Refresh

func (tm *TimedMap[TKey, TVal]) Refresh(key TKey, d time.Duration) error

Refresh extends the expiry time for a key-value pair about the passed duration. If there is no value to the key passed, this will return an error object.

func (*TimedMap[TKey, TVal]) Remove

func (tm *TimedMap[TKey, TVal]) Remove(key TKey)

Remove deletes a key-value pair in the map.

func (*TimedMap[TKey, TVal]) Set

func (tm *TimedMap[TKey, TVal]) Set(key TKey, value TVal, expiresAfter time.Duration, cb ...Callback[TVal])

Set appends a key-value pair to the map or sets the value of a key. expiresAfter sets the expiry time after the key-value pair will automatically be removed from the map.

func (*TimedMap[TKey, TVal]) SetExpires

func (tm *TimedMap[TKey, TVal]) SetExpires(key TKey, d time.Duration) error

SetExpires sets the expiry time for a key-value pair to the passed duration. If there is no value to the key passed , this will return an error.

func (*TimedMap[TKey, TVal]) Size

func (tm *TimedMap[TKey, TVal]) Size() int

Size returns the current number of key-value pairs existent in the map.

func (*TimedMap[TKey, TVal]) Snapshot

func (tm *TimedMap[TKey, TVal]) Snapshot() map[TKey]TVal

Snapshot returns a new map which represents the current key-value state of the internal container.

func (*TimedMap[TKey, TVal]) StartCleanerExternal

func (tm *TimedMap[TKey, TVal]) StartCleanerExternal(initiator <-chan time.Time)

StartCleanerExternal starts the cleanup loop controlled by the given initiator channel. This is useful if you want to have more control over the cleanup loop or if you want to sync up multiple TimedMaps.

If the cleanup loop is already running, it will be stopped and restarted using the new specification.

func (*TimedMap[TKey, TVal]) StartCleanerInternal

func (tm *TimedMap[TKey, TVal]) StartCleanerInternal(interval time.Duration)

StartCleanerInternal starts the cleanup loop controlled by an internal ticker with the given interval.

If the cleanup loop is already running, it will be stopped and restarted using the new specification.

func (*TimedMap[TKey, TVal]) StopCleaner

func (tm *TimedMap[TKey, TVal]) StopCleaner()

StopCleaner stops the cleaner go routine and timer. This should always be called after exiting a scope where TimedMap is used that the data can be cleaned up correctly.