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 (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()
Constants ¶
This section is empty.
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") )
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)
// 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 New ¶
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 ¶
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) GetExpires ¶
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 ¶
Ident returns the current sections ident. In the case of the root object TimedMap, this is always 0.
func (*TimedMap) Refresh ¶
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 ¶
Section returns a sectioned subset of the timed map with the given section identifier i.
func (*TimedMap) Set ¶
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
SetExpire is deprecated. Please use SetExpires instead.
func (*TimedMap) SetExpires ¶ added in v1.4.0
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) Snapshot ¶ added in v1.4.0
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 ¶ added in v1.4.0
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 ¶ added in v1.4.0
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.
Source Files
Directories