https://github.com/devnw/ttl
TTL (Time To Live) Cache Implementation for Go
https://github.com/devnw/ttl
cache caching go golang time-to-live ttl
Last synced: 7 days ago
JSON representation
TTL (Time To Live) Cache Implementation for Go
- Host: GitHub
- URL: https://github.com/devnw/ttl
- Owner: devnw
- License: apache-2.0
- Created: 2021-04-14T10:20:26.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2025-02-27T01:39:49.000Z (11 months ago)
- Last Synced: 2025-04-10T21:08:03.904Z (9 months ago)
- Topics: cache, caching, go, golang, time-to-live, ttl
- Language: Go
- Homepage:
- Size: 123 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# TTL (Time To Live) Cache Implementation for Go
[](https://github.com/devnw/ttl/actions)
[](https://goreportcard.com/report/go.devnw.com/ttl)
[](https://codecov.io/gh/devnw/ttl)
[](https://go.devnw.com/ttl)
[](https://opensource.org/licenses/Apache-2.0)
[](http://makeapullrequest.com)
## 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.
```go
// 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:
```bash
go test -bench=. ./...
```
To view benchmarks over time for the `main` branch of the repository they can
be seen on our [Benchmark Report Card].
[Benchmark Report Card]: https://devnw.github.io/ttl/dev/bench