Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jellydator/ttlcache
An in-memory cache with item expiration and generics
https://github.com/jellydator/ttlcache
cache generics golang ttl-cache
Last synced: 14 days ago
JSON representation
An in-memory cache with item expiration and generics
- Host: GitHub
- URL: https://github.com/jellydator/ttlcache
- Owner: jellydator
- License: mit
- Created: 2014-12-13T01:55:40.000Z (almost 10 years ago)
- Default Branch: v3
- Last Pushed: 2024-04-08T18:15:02.000Z (7 months ago)
- Last Synced: 2024-04-23T07:07:47.320Z (7 months ago)
- Topics: cache, generics, golang, ttl-cache
- Language: Go
- Homepage:
- Size: 245 KB
- Stars: 843
- Watchers: 14
- Forks: 113
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-go - ttlcache - An in-memory cache with item expiration and generics. (Database / Caches)
- awesome-go-extra - ttlcache - memory cache with item expiration and generics|474|76|5|2014-12-13T01:55:40Z|2022-08-08T22:02:49Z| (Generators / Caches)
README
## TTLCache - an in-memory cache with item expiration and generics
[](https://pkg.go.dev/github.com/jellydator/ttlcache/v3)
[](https://github.com/jellydator/ttlcache/actions/workflows/go.yml)
[](https://coveralls.io/github/jellydator/ttlcache?branch=master)
[](https://goreportcard.com/report/github.com/jellydator/ttlcache/v3)
## Features
- Simple API
- Type parameters
- Item expiration and automatic deletion
- Automatic expiration time extension on each `Get` call
- `Loader` interface that may be used to load/lazily initialize missing cache
- Thread Safe
items
- Event handlers (insertion and eviction)
- Metrics
## Installation
```
go get github.com/jellydator/ttlcache/v3
```
## Usage
The main type of `ttlcache` is `Cache`. It represents a single
in-memory data store.
To create a new instance of `ttlcache.Cache`, the `ttlcache.New()` function
should be called:
```go
func main() {
cache := ttlcache.New[string, string]()
}
```
Note that by default, a new cache instance does not let any of its
items to expire or be automatically deleted. However, this feature
can be activated by passing a few additional options into the
`ttlcache.New()` function and calling the `cache.Start()` method:
```go
func main() {
cache := ttlcache.New[string, string](
ttlcache.WithTTL[string, string](30 * time.Minute),
)
go cache.Start() // starts automatic expired item deletion
}
```
Even though the `cache.Start()` method handles expired item deletion well,
there may be times when the system that uses `ttlcache` needs to determine
when to delete the expired items itself. For example, it may need to
delete them only when the resource load is at its lowest (e.g., after
midnight, when the number of users/HTTP requests drops). So, in situations
like these, instead of calling `cache.Start()`, the system could
periodically call `cache.DeleteExpired()`:
```go
func main() {
cache := ttlcache.New[string, string](
ttlcache.WithTTL[string, string](30 * time.Minute),
)
for {
time.Sleep(4 * time.Hour)
cache.DeleteExpired()
}
}
```
The data stored in `ttlcache.Cache` can be retrieved, checked and updated with
`Set`, `Get`, `Delete`, `Has` etc. methods:
```go
func main() {
cache := ttlcache.New[string, string](
ttlcache.WithTTL[string, string](30 * time.Minute),
)
// insert data
cache.Set("first", "value1", ttlcache.DefaultTTL)
cache.Set("second", "value2", ttlcache.NoTTL)
cache.Set("third", "value3", ttlcache.DefaultTTL)
// retrieve data
item := cache.Get("first")
fmt.Println(item.Value(), item.ExpiresAt())
// check key
ok := cache.Has("third")
// delete data
cache.Delete("second")
cache.DeleteExpired()
cache.DeleteAll()
// retrieve data if in cache otherwise insert data
item, retrieved := cache.GetOrSet("fourth", "value4", WithTTL[string, string](ttlcache.DefaultTTL))
// retrieve and delete data
item, present := cache.GetAndDelete("fourth")
}
```
To subscribe to insertion and eviction events, `cache.OnInsertion()` and
`cache.OnEviction()` methods should be used:
```go
func main() {
cache := ttlcache.New[string, string](
ttlcache.WithTTL[string, string](30 * time.Minute),
ttlcache.WithCapacity[string, string](300),
)
cache.OnInsertion(func(ctx context.Context, item *ttlcache.Item[string, string]) {
fmt.Println(item.Value(), item.ExpiresAt())
})
cache.OnEviction(func(ctx context.Context, reason ttlcache.EvictionReason, item *ttlcache.Item[string, string]) {
if reason == ttlcache.EvictionReasonCapacityReached {
fmt.Println(item.Key(), item.Value())
}
})
cache.Set("first", "value1", ttlcache.DefaultTTL)
cache.DeleteAll()
}
```
To load data when the cache does not have it, a custom or
existing implementation of `ttlcache.Loader` can be used:
```go
func main() {
loader := ttlcache.LoaderFunc[string, string](
func(c *ttlcache.Cache[string, string], key string) *ttlcache.Item[string, string] {
// load from file/make an HTTP request
item := c.Set("key from file", "value from file")
return item
},
)
cache := ttlcache.New[string, string](
ttlcache.WithLoader[string, string](loader),
)
item := cache.Get("key from file")
}
```