ttl

README

TTL (Time To Live) Cache Implementation for Go

Overview

A TTL (Time To Live) cache is a data store where data is removed after a defined period of time to optimize memory performance.

Implementation

TTL Details

This TTL Cache implementation is designed for ease of use. There are two methods for setting TTL for a data element.

1. TTL is configured when the Cache is instantiated using ttl.NewCache which accepts a time.Duration parameter for the default TTL of the cache instance. Unless otherwise specified for a specific data element, this is the TTL for all data stored in the cache.

2. TTL for each data element can be configured using the cache.SetTTL meethod which accepts a time.Duration which will set a specific TTL for that piece of data when it's loaded into the cache.

TTL Extension

In order to optimize data access and retention an extension option was included as part of the implementation of the TTL cache. This can be enabled as part of the NewCache method. TTL Extension configures the cache so that when data is READ from the cache the timeout for that key/value pair is reset extending the life of that data in memory. This allows for regularly accessed data to be retained while less regularly accessed data is cleared from memory.

Usage

go get -u go.devnw.com/ttl@latest

Cache Creation

The NewCache method returns an instance of the ttl.Cache[K,V] type to hold the data.

// NOTE: The KeyType must adhere to the `comparable` constraint
cache := ttl.NewCache[KeyType, ValueType](
    // Context used in the application
    ctx,

    // `time.Duration` that configures the default
    // timeout for elements of the cache
    timeout,
    
    // boolean which configures whether or not the
    // timeout should be reset on READ
    extend,
)

Add Data to Cache

Adding to the cache uses a simple key/value pattern for setting data. There are two functions for adding data to the cache. The standard method Set uses the cache's configured default timeout.

err := cache.Set(ctx, key, value)

The SetTTL method uses the timeout (time.Duration) that is passed into the method for configuring how long the cache should hold the data before it's cleared from memory.

err := cache.SetTTL(ctx, key, value, timeout)

Get Data from Cache

Getting data from the cache follows a fairly standard pattern which is similar ot the sync.Map get method.

value, exists := cache.Get(ctx, key)

The Get method returns the value (if it exists) and a boolean which indicates if a value was retrieved from the cache.

Delete Data from Cache

As with Get, Delete uses a similar pattern to sync.Map.

cache.Delete(ctx, key)

This deletes the key from the map as well as shuts down the backend routines running that key's processing.

Benchmarks

To execute the benchmarks, run the following command:

    go test -bench=. ./...

To view benchmarks over time for the main branch of the repository they can be seen on our Benchmark Report Card.

Documentation

Overview

Package ttl implements a TTL cache which can be used to store values a specified timeout period. The cache implementation supports extending the timeout of regularly read values as well as storing custom TTL timeouts for specific key/value pairs with the `SetTTL` method.

Index

• type Cache
  • func NewCache[K comparable, V any](ctx context.Context, timeout time.Duration, extend bool) *Cache[K, V]
  • func (c *Cache[K, V]) Delete(ctx context.Context, key K)
  • func (c *Cache[K, V]) Get(ctx context.Context, key K) (V, bool)
  • func (c *Cache[K, V]) Set(ctx context.Context, key K, value V) error
  • func (c *Cache[K, V]) SetTTL(ctx context.Context, key K, value V, timeout time.Duration) error

Types

type Cache

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

Cache implements a TTL Cache which can be used to store values values a specified timeout period. If the value is read before the timeout period has passed, and the extend flag is set to true, the timeout period will be extended by the timeout period. This ensures that the value is not removed if it is regularly accessed within the timeout period.

func NewCache

func NewCache[K comparable, V any](
	ctx context.Context,
	timeout time.Duration,
	extend bool,
) *Cache[K, V]

NewCache creates a new TTL Cache using the a timeout for the default timeout of stored values and the extend value to determine if the cache lifetime of the set values should be extended upon read

func (*Cache[K, V]) Delete

func (c *Cache[K, V]) Delete(ctx context.Context, key K)

Delete removes the values associated with the passed key from the cache

func (*Cache[K, V]) Get

func (c *Cache[K, V]) Get(ctx context.Context, key K) (V, bool)

Get accesses the value for the Key provide

func (*Cache[K, V]) Set

func (c *Cache[K, V]) Set(ctx context.Context, key K, value V) error

Set sets the value for the key provided

func (*Cache[K, V]) SetTTL

func (c *Cache[K, V]) SetTTL(
	ctx context.Context,
	key K, value V,
	timeout time.Duration,
) error

SetTTL allows for direct control over the TTL of a specific Key in the cache which is passed as timeout in parameter three. This timeout can be `nil` which will keep the value permanently in the cache without expiration until it's deleted