timedmap

README

~ timedmap ~

A map which has expiring key-value pairs.

       

---

go get -u github.com/zekroTJA/timedmap

---

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.

---

Usage Example

package main

import (
	"log"
	"time"

	"github.com/zekroTJA/timedmap"
)

func main() {
	// Create a timed map with a cleanup timer interval of 1 second
	tm := timedmap.New(1 * time.Second)
	// Set value of key "hey" to 213, which will expire after 3 seconds
	tm.Set("hey", 213, 3*time.Second)
	// Print the value of "hey"
	printKeyVal(tm, "hey")
	// Block the main thread for 5 seconds
	// After this time, the key-value pair "hey": 213 has expired
	time.Sleep(5 * time.Second)
	// Now, this function should show that there is no key "hey"
	// in the map, because it has been expired
	printKeyVal(tm, "hey")
}

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

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

Further examples, you can find in the example 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 Section
• type TimedMap
  • func FromMap(m interface{}, expiration time.Duration, cleanupTickTime time.Duration, ...) (*TimedMap, error)
  • func New(cleanupTickTime time.Duration, tickerChan ...<-chan time.Time) *TimedMap
  • func (tm *TimedMap) Contains(key interface{}) bool
  • func (tm *TimedMap) Flush()
  • func (tm *TimedMap) GetExpires(key interface{}) (time.Time, error)
  • func (tm *TimedMap) GetValue(key interface{}) interface{}
  • func (tm *TimedMap) Ident() int
  • func (tm *TimedMap) Refresh(key interface{}, d time.Duration) error
  • func (tm *TimedMap) Remove(key interface{})
  • func (tm *TimedMap) Section(i int) Section
  • func (tm *TimedMap) Set(key, value interface{}, expiresAfter time.Duration, cb ...callback)
  • func (tm *TimedMap) SetExpire(key interface{}, d time.Duration) error
  • func (tm *TimedMap) SetExpires(key interface{}, d time.Duration) error
  • func (tm *TimedMap) Size() int
  • func (tm *TimedMap) Snapshot() map[interface{}]interface{}
  • func (tm *TimedMap) StartCleanerExternal(initiator <-chan time.Time)
  • func (tm *TimedMap) StartCleanerInternal(interval time.Duration)
  • func (tm *TimedMap) 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 Section

type Section interface {

	// Ident returns the current sections identifier
	Ident() int

	// Set appends a key-value pair to the map or sets the value of
	// a key. expiresAfter sets the expire time after the key-value pair
	// will automatically be removed from the map.
	Set(key, value interface{}, expiresAfter time.Duration, cb ...callback)

	// 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.
	GetValue(key interface{}) interface{}

	// GetExpires returns the expire 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.
	GetExpires(key interface{}) (time.Time, error)

	// SetExpires sets the expire time for a key-value
	// pair to the passed duration. If there is no value
	// to the key passed , this will return an error.
	SetExpires(key interface{}, d time.Duration) error

	// 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.
	Contains(key interface{}) bool

	// Remove deletes a key-value pair in the map.
	Remove(key interface{})

	// Refresh extends the expire time for a key-value pair
	// about the passed duration. If there is no value to
	// the key passed, this will return an error.
	Refresh(key interface{}, d time.Duration) error

	// Flush deletes all key-value pairs of the section
	// in the map.
	Flush()

	// Size returns the current number of key-value pairs
	// existent in the section of the map.
	Size() (i int)

	// Snapshot returns a new map which represents the
	// current key-value state of the internal container.
	Snapshot() map[interface{}]interface{}
}

Section defines a sectioned access wrapper of TimedMap.

type TimedMap

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

TimedMap contains a map with all key-value pairs, and a timer, which cleans the map in the set tick durations from expired keys.

func FromMap

func FromMap(
	m interface{},
	expiration time.Duration,
	cleanupTickTime time.Duration,
	tickerChan ...<-chan time.Time,
) (*TimedMap, error)

func New

func New(cleanupTickTime time.Duration, tickerChan ...<-chan time.Time) *TimedMap

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.

Optionally, you can also pass a custom <-chan time.Time which controls the cleanup cycle if you want to use a single syncronyzed timer or if you want to have more 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) Contains

func (tm *TimedMap) Contains(key interface{}) 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) Flush

func (tm *TimedMap) Flush()

Flush deletes all key-value pairs of the map.

func (*TimedMap) GetExpires

func (tm *TimedMap) GetExpires(key interface{}) (time.Time, error)

GetExpires returns the expire 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) GetValue

func (tm *TimedMap) GetValue(key interface{}) interface{}

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) Ident

func (tm *TimedMap) Ident() int

Ident returns the current sections ident. In the case of the root object TimedMap, this is always 0.

func (*TimedMap) Refresh

func (tm *TimedMap) Refresh(key interface{}, d time.Duration) error

Refresh extends the expire 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) Remove

func (tm *TimedMap) Remove(key interface{})

Remove deletes a key-value pair in the map.

func (*TimedMap) Section

func (tm *TimedMap) Section(i int) Section

Section returns a sectioned subset of the timed map with the given section identifier i.

func (*TimedMap) Set

func (tm *TimedMap) Set(key, value interface{}, expiresAfter time.Duration, cb ...callback)

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

func (*TimedMap) SetExpire

func (tm *TimedMap) SetExpire(key interface{}, d time.Duration) error

SetExpire is deprecated. Please use SetExpires instead.

func (*TimedMap) SetExpires

func (tm *TimedMap) SetExpires(key interface{}, d time.Duration) error

SetExpires sets the expire 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) Size

func (tm *TimedMap) Size() int

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

func (*TimedMap) Snapshot

func (tm *TimedMap) Snapshot() map[interface{}]interface{}

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

func (*TimedMap) StartCleanerExternal

func (tm *TimedMap) 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) StartCleanerInternal

func (tm *TimedMap) 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) StopCleaner

func (tm *TimedMap) 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.