Skip to content
/ ttl Public
generated from devnw/oss-template

TTL (Time To Live) Cache Implementation for Go

License

Notifications You must be signed in to change notification settings

devnw/ttl

TTL (Time To Live) Cache Implementation for Go

Build & Test Action Status Go Report Card codecov Go Reference License: Apache 2.0 PRs Welcome

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.