ttlcache

README

Go TTL Cache

A Simple Cache That Expires Items.

When getting an item from the cache, the ttl is updated and reset to the current time. This helps prevent frequently accessed items from expiring.

This package uses the haxmap package for better performance.

Installation

  go get github.com/AspieSoft/go-ttlcache

Usage

import (
  "time"

  "github.com/AspieSoft/go-ttlcache"
)

var cache *ttlcache.Cache[string, interface{}]

func main(){
  // create a new cache with a time to live
  cache = ttlcache.New[string, interface{}](2 * time.Hour)

  // optional auto deletion interval (default: 1 hour)
  cache = ttlcache.New[string, interface{}](2 * time.Hour, 4 * time.Hour)

  cache.Set("Item1", 10)
  cache.Set("Item2", 20)

  if value, ok := cache.Get("Item1"); ok {
    // value = 10
  }

  cache.Len() // returns the number of items that have not expired

  cache.MapLen() // returns the total number of items actually stored in the cache (expired items may still be stored, but the ok value will return false if expired)

  if value, ok := cache.Get("Item2"); !ok {
    // Item2 has expired, but the cache may still hold this value and return it
  }

  // reset the cache expire time for an item to keep this value longer
  cache.Touch("Item2")

  // change the time to live
  cache.TTL(1 * time.Hour)

  // optional also change auto deletion interval
  cache.TTL(12 * time.Hour, 24 * time.Hour)

  // clear expired items from cache
  // this is done automatically on an interval, but you can run it manually if you want
  cache.ClearExpired()

  // clear items early if they were last accessed longer than a given time
  // this can be useful if you detect heavy memory usage, and need to shrink the cache sooner then usual
  cache.ClearEarly(2 * time.Hour)

  // remove the optional parameter to clear the entire cache
  cache.ClearEarly()

}

Documentation

Index

• type Cache
  • func New[T hashable, J any](ttl time.Duration, delInterval ...time.Duration) *Cache[T, J]

Types

type Cache

type Cache[T hashable, J any] struct {
	// Touch resets the cache expire time for an item to keep this value longer
	Touch func(key T)

	// Get returns the value of an item
	Get func(key T) (J, bool)

	// Set will either create a new value, or overwrite an existing one
	Set func(key T, value J)

	// Del will remove an item from the cache
	Del func(key T)

	// TTL will change the time to live for cache items before they expire
	// you can optionally change the delInterval for how often the cache will check to auto delete expired items
	TTL func(ttl time.Duration, delInterval ...time.Duration)

	// ForEach runs a function for each cache item in the list
	ForEach func(lambda func(key T, value J))

	// ForEachBreak is like ForEach, but will allow you to break the loop early
	// return `true` to continue the loop
	// return `false` to break the loop
	ForEachBreak func(lambda func(key T, value J) bool)

	// Len returns the number of cache items that have not expired
	Len func() uintptr

	// LenMap returns the number of cache items including those that have expired
	MapLen func() uintptr

	// Fillrate returns the fill rate of the map as a percentage integer
	// this method runs the direct function form haxmap https://github.com/alphadose/haxmap
	Fillrate func() uintptr

	// Grow resizes the hashmap to a new size, gets rounded up to next power of 2 To double the size of the hashmap use newSize 0 This function returns immediately, the resize operation is done in a goroutine No resizing is done in case of another resize operation already being in progress Growth and map bucket policy is inspired from https://github.com/cornelk/hashmap
	// this method runs the direct function form haxmap https://github.com/alphadose/haxmap
	Grow func(newSize uintptr)

	// ClearExpired clears the expired items from the cache
	// this function will automatically run on an interval unless you disable it
	ClearExpired func()

	// ClearEarly allows you to clear cache items before they expire
	// optionally set the `ttl` param to a time, and only items older than that time will be deleted
	ClearEarly func(ttl ...time.Duration)
	// contains filtered or unexported fields
}

func New

func New[T hashable, J any](ttl time.Duration, delInterval ...time.Duration) *Cache[T, J]