Simple in-memory key-value cache supporting time-based and size-based evictions, cache loaders, event listeners, and unit testing capabilities with flexible expiration and eviction policies.
In-memory Cache for Kotlin Multiplatform.
Work in progress.
cache4k provides a simple in-memory key-value cache for Kotlin Multiplatform, with support for time-based (expiration) and size-based evictions.
Note that only the new Kotlin Native memory model is supported.
The following targets are currently supported:
Dependencies are hosted on Maven Central.
dependencies {
implementation("io.github.reactivecircus.cache4k:cache4k:x.y.z")
}
kotlin {
sourceSets {
commonMain {
dependencies {
implementation("io.github.reactivecircus.cache4k:cache4k:x.y.z")
}
}
}
}
To create a new Cache instance using Long for the key and String for the value:
val cache = Cache.Builder<Long, String>().build()
To start writing entries to the cache:
cache.put(1, "dog")
cache.put(2, "cat")
To read a cache entry by key:
cache.get(1) // returns "dog"
cache.get(2) // returns "cat"
cache.get(3) // returns null
To overwrite an existing cache entry:
cache.put(1, "dog")
cache.put(1, "bird")
cache.get(1) // returns "bird"
Cache provides an API for getting cached value by key and using the provided loader: suspend () -> Value lambda to compute and cache the value automatically if none exists.
runBlockingTest {
val cache = Cache.Builder<Long, User>().build()
val userId = 1L
val user = cache.get(userId) {
fetchUserById(userId) // potentially expensive call (might be a suspend function)
}
// value successfully computed by the loader will be cached automatically
assertThat(user).isEqualTo(cache.get(userId))
}
Note that loader is executed on the caller's coroutine context. Concurrent calls from multiple threads using the same key will be blocked. Assuming the 1st call successfully computes a new value, none of the loader from the other calls will be executed and the cached value computed by the first loader will be returned for those calls.
Any exceptions thrown by the loader will be propagated to the caller of this function.
By default, Cache has an unlimited number of entries which never expire. But a cache can be configured to support both time-based expirations and size-based evictions.
Expiration time can be specified for entries in the cache.
To set the maximum time an entry can live in the cache since the last access (also known as ** time-to-idle**), where "access" means reading the cache, adding a new cache entry, or ** replacing an existing entry with a new one**:
val cache = Cache.Builder<Long, String>()
.expireAfterAccess(24.hours)
.build()
An entry in this cache will be removed if it has not been read or replaced after 24 hours since it's been written into the cache.
To set the maximum time an entry can live in the cache since the last write (also known as ** time-to-live**), where "write" means adding a new cache entry or replacing an existing entry with a new one:
val cache = Cache.Builder<Long, String>()
.expireAfterWrite(30.minutes)
.build()
An entry in this cache will be removed if it has not been replaced after 30 minutes since it's been written into the cache.
Note that cache entries are not removed immediately upon expiration at exact time. Expirations are checked in each interaction with the cache.
To set the maximum number of entries to be kept in the cache:
val cache = Cache.Builder<Long, String>()
.maximumCacheSize(100)
.build()
Once there are more than 100 entries in this cache, the least recently used one will be removed, where "used" means reading the cache, adding a new cache entry, or replacing an existing entry with a new one.
To get a copy of the current cache entries as a Map:
val cache = Cache.Builder<Long, String>()
.build()
cache.put(1, "dog")
cache.put(2, "cat")
assertThat(cache.asMap())
.isEqualTo(mapOf(1L to "dog", 2L to "cat"))
Note that calling asMap() has no effect on the access expiry of the cache.
Cache entries can also be deleted explicitly.
To delete a cache entry for a given key:
val cache = Cache.Builder<Long, String>().build()
cache.put(1, "dog")
cache.invalidate(1)
assertThat(cache.get(1)).isNull()
To delete all entries in the cache:
cache.invalidateAll()
You can set an event listener as a lambda:
val cache1 = Cache.Builder<Long, String>()
.eventListener { event ->
println("onEvent: $event")
}
.build()
Or declare it as a class and share logic across many stores:
class FileDeleteEventListener : <> {
{
(event) {
CacheEvent.Created -> {}
CacheEvent.Updated -> event.oldValue.delete()
CacheEvent.Evicted -> event.value.delete()
CacheEvent.Expired -> event.value.delete()
CacheEvent.Removed -> event.value.delete()
}
}
}
fileDeleteEventListener = FileDeleteEventListener()
cache1 = Cache.Builder<, File>()
.eventListener(fileDeleteEventListener)
.build()
cache2 = Cache.Builder<, File>()
.eventListener(fileDeleteEventListener)
.build()
Cache entry event firing behaviors for mutative methods:
To test logic that depends on cache expiration, pass in a FakeTimeSource when building a Cache
so you can programmatically advance the reading of the time source:
@Test
fun cacheEntryEvictedAfterExpiration() {
private fakeTimeSource = FakeTimeSource()
cache = Cache.Builder<, String>()
.timeSource(fakeTimeSource)
.expireAfterWrite(minutes)
.build()
cache.put(, )
fakeTimeSource += minutes - nanoseconds
assertThat(cache.())
.isEqualTo()
fakeTimeSource += nanoseconds
assertThat(cache.())
.isNull()
}
The library was ported from a kotlin / JVM cache which I contributed to dropbox/Store to help unblock Store's multiplatform support ( it was reverted before the 1.0 release as multiplatform wasn't a priority). Many thanks to Store's owners and contributors for reviewing and improving the original implementation.
Copyright 2021 Yang Chen
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http:
Unless applicable law agreed to writing, software
distributed under the License distributed an BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express implied.
See the License the specific language governing permissions
limitations under the License.
YourKit supports open source projects with innovative and intelligent tools for monitoring and profiling Java and .NET applications. YourKit is the creator of YourKit Java Profiler, YourKit .NET Profiler, and YourKit YouMonitor.
| Initial value | Operation | New value | Event |
|---|
| {} | put(K, V) | {K: V} | Created(K, V) |
| {K: V1} | put(K, V2) | {K: V2} | Updated(K, V1, V2) |
| {K: V} | invalidate(K) | {} | Removed(K, V) |
| {K1: V1, K2: V2} | invalidateAll() | {} | Removed(K1, V1), Removed(K2, V2) |
| {K: V} | any operation, K expired | {} | Expired(K, V) |
| {K1: V1} | put(K2, V2), K1 evicted | {K2: V2} | Created(K2, V2), Evicted(K1, V1) |
Surfaced from shared tags and platforms — no rankings paid for.