ttlmap

package module
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Jan 20, 2024 License: MIT Imports: 3 Imported by: 0

README

TtlMap

TtlMap is golang package that implements a time-to-live map such that after a given amount of time, items in the map are deleted.

  • The map key can be any comparable data type, via Generics.
  • Any data type can be used as a map value. Internally, interface{} is used for this.

Example

Full example using many data types

Small example:

package main

import (
	"fmt"
	"time"
	"github.com/jftuga/TtlMap"
)

func main() {
	maxTTL := time.Duration(time.Second * 4)        // a key's time to live in seconds
	startSize := 3                                  // initial number of items in map
	pruneInterval := time.Duration(time.Second * 1) // search for expired items every 'pruneInterval' seconds
	refreshLastAccessOnGet := true                  // update item's 'lastAccessTime' on a .Get()

	// any comparable data type such as int, uint64, pointers and struct types (if all field types are comparable)
	// can be used as the key type, not just string
	t := TtlMap.New[string](maxTTL, startSize, pruneInterval, refreshLastAccessOnGet)
	defer t.Close()

	// populate the TtlMap
	t.Put("myString", "a b c")
	t.Put("int_array", []int{1, 2, 3})
	fmt.Println("TtlMap length:", t.Len())

	// display all items in TtlMap
	all := t.All()
	for k, v := range all {
		fmt.Printf("[%9s] %v\n", k, v.Value)
	}
	fmt.Println()

	sleepTime := maxTTL + pruneInterval
	fmt.Printf("Sleeping %v seconds, items should be 'nil' after this time\n", sleepTime)
	time.Sleep(sleepTime)
	fmt.Printf("[%9s] %v\n", "myString", t.Get("myString"))
	fmt.Printf("[%9s] %v\n", "int_array", t.Get("int_array"))
	fmt.Println("TtlMap length:", t.Len())
}

Output:

$ go run small.go

TtlMap length: 2
[ myString] a b c
[int_array] [1 2 3]

Sleeping 5 seconds, items should be 'nil' after this time
[ myString] <nil>
[int_array] <nil>
TtlMap length: 0

API functions

  • New: initialize a TtlMap
  • Close: this stops the goroutine that checks for expired items; use with defer
  • Len: return the number of items in the map
  • Put: add a key/value
  • Get: get the current value of the given key; return nil if the key is not found in the map
  • GetNoUpdate: same as Get, but do not update the lastAccess expiration time
      • This ignores the refreshLastAccessOnGet parameter
  • All: returns a copy of all items in the map
  • Delete: delete an item; return true if the item was deleted, false if the item was not found in the map
  • Clear: remove all items from the map

Performance

  • Searching for expired items runs in O(n) time, where n = number of items in the TtlMap.
    • This inefficiency can be somewhat mitigated by increasing the value of the pruneInterval time.
  • In most cases you want pruneInterval > maxTTL; otherwise expired items will stay in the map longer than expected.

Acknowledgments

Disclosure Notification

This program was completely developed on my own personal time, for my own personal benefit, and on my personally owned equipment.

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Key

type Key interface {
	comparable
}

type TtlMap

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

func New

func New[K Key, V any](capacity uint, ttl time.Duration, pruneInterval time.Duration) (m *TtlMap[K, V])

func (*TtlMap[K, V]) Clear

func (m *TtlMap[K, V]) Clear()

func (*TtlMap[K, V]) Close

func (m *TtlMap[K, V]) Close()

func (*TtlMap[K, V]) Copy

func (m *TtlMap[K, V]) Copy() map[K]*item[V]

func (*TtlMap[K, V]) Delete

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

func (*TtlMap[K, V]) Get

func (m *TtlMap[K, V]) Get(key K) (value V, ok bool)

func (*TtlMap[K, V]) GetOrZero

func (m *TtlMap[K, V]) GetOrZero(key K) (value V)

func (*TtlMap[K, V]) Len

func (m *TtlMap[K, V]) Len() (size uint)

func (*TtlMap[K, V]) Put

func (m *TtlMap[K, V]) Put(key K, value V)

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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