timedmap

package module
v1.3.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 9, 2021 License: MIT Imports: 3 Imported by: 39

README

~ timedmap ~

A map which has expiring key-value pairs.

       

go get 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

Constants

This section is empty.

Variables

View Source
var (
	ErrKeyNotFound = errors.New("key not found")
)

Functions

This section is empty.

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

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 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 Timer, 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 somethign like that.

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 added in v1.2.0

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

Directories

Path Synopsis
examples
default command
sections command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL