Constructor Detail

Method Detail

• getOrPut

   final static <K extends Any, V extends Any> V getOrPut(Cache<K, V> $self, K key, SuspendFunction0<V> compute)

  Gets the value for the given key, or computes and stores it if not present.

  This suspending function provides a thread-safe way to implement the "check-then-act" pattern common in caching scenarios. If the key is not found, the compute function is called to generate the value, which is then stored in the cache.

  // Load user from database if not cached
  val user = cache.getOrPut("user123") {
      userRepository.findById("user123")
  }
  
  // Expensive computation with caching
  val result = cache.getOrPut("computation_$input") {
      performExpensiveComputation(input)
  }
  
  // API call with caching
  val response = cache.getOrPut("api_$endpoint") {
      httpClient.get(endpoint).body<ApiResponse>()
  }

  This function is not atomic - if multiple threads call it simultaneously with the same key, the compute function may be executed multiple times. For atomic behavior, consider using a loading cache with a configured loader function.

  Parameters:

  key - the key to look up

  compute - the suspending function to compute the value if not present

  Returns:

  the value associated with the key

• getOrDefault

   final static <K extends Any, V extends Any> V getOrDefault(Cache<K, V> $self, K key, V defaultValue)

  Gets the value for the given key, or returns the default value if not present.

  This is a safe alternative to Cache.get that avoids null checks by providing a fallback value when the key is not found in the cache.

  // Get user preferences with defaults
  val theme = prefsCache.getOrDefault("theme", "light")
  val fontSize = prefsCache.getOrDefault("fontSize", 14)
  
  // Configuration values with fallbacks
  val timeout = configCache.getOrDefault("timeout", Duration.ofSeconds(30))
  
  // Counters with zero default
  val visitCount = cache.getOrDefault("visits_$userId", 0)

  Parameters:

  key - the key to look up

  defaultValue - the value to return if the key is not present

  Returns:

  the value associated with the key, or the default value

• forEach

   final static <K extends Any, V extends Any> Unit forEach(Cache<K, V> $self, Function2<K, V, Unit> action)

  Performs the given action on each entry in the cache.

  This provides a convenient way to iterate over all cached entries, similar to the forEach function available on Kotlin collections. The iteration order is not guaranteed and may vary between calls.

  // Log all cached users
  userCache.forEach { userId, user ->
      logger.info("Cached user: $userId -> ${user.name}")
  }
  
  // Collect statistics
  var totalSize = 0L
  cache.forEach { _, value ->
      totalSize += value.size
  }
  
  // Validate cache contents
  cache.forEach { key, value ->
      require(value.isValid()) { "Invalid value for key: $key" }
  }

  This operation iterates over all entries in the cache, which may be expensive for large caches. Consider using streaming operations for better performance with large datasets.

  Parameters:

  action - the action to perform on each entry

• keysList

   final static <K extends Any, V extends Any> List<K> keysList(Cache<K, V> $self)

  Returns a list of all keys in the cache.

  This creates a snapshot of all keys currently in the cache. The returned list is independent of the cache and will not be affected by subsequent cache modifications.

  // Get all user IDs
  val allUserIds = userCache.keysList()
  
  // Check which keys are present
  val presentKeys = cache.keysList().filter { it.startsWith("active_") }
  
  // Bulk operations on keys
  val keysToRefresh = cache.keysList().filter { needsRefresh(it) }
  keysToRefresh.forEach { key -> refreshCacheEntry(key) }

  This operation creates a new list and copies all keys, which may be expensive for large caches. Use Cache.keys if you only need to iterate once.

  Returns:

  a list of all keys currently in the cache

• valuesList

   final static <K extends Any, V extends Any> List<V> valuesList(Cache<K, V> $self)

  Returns a list of all values in the cache.

  This creates a snapshot of all values currently in the cache. The returned list is independent of the cache and will not be affected by subsequent cache modifications.

  // Get all cached users
  val allUsers = userCache.valuesList()
  
  // Analyze cached data
  val averageSize = cache.valuesList().map { it.size }.average()
  
  // Bulk validation
  val invalidValues = cache.valuesList().filter { !it.isValid() }
  if (invalidValues.isNotEmpty()) {
      logger.warn("Found ${invalidValues.size} invalid cached values")
  }

  This operation creates a new list and copies all values, which may be expensive for large caches. Use Cache.values if you only need to iterate once.

  Returns:

  a list of all values currently in the cache

• getDeferred

   final static <K extends Any, V extends Any> Deferred<V> getDeferred(Cache<K, V> $self, K key, CoroutineScope scope)

  Asynchronously gets the value for the given key as a Deferred.

  Parameters:

  scope - The coroutine scope to use for the async operation

• putDeferred

   final static <K extends Any, V extends Any> Deferred<Unit> putDeferred(Cache<K, V> $self, K key, V value, CoroutineScope scope)

  Asynchronously puts a value for the given key as a Deferred.

  Parameters:

  scope - The coroutine scope to use for the async operation

• removeDeferred

   final static <K extends Any, V extends Any> Deferred<V> removeDeferred(Cache<K, V> $self, K key, CoroutineScope scope)

  Asynchronously removes the value for the given key as a Deferred.

  Parameters:

  scope - The coroutine scope to use for the async operation

• clearDeferred

   final static <K extends Any, V extends Any> Deferred<Unit> clearDeferred(Cache<K, V> $self, CoroutineScope scope)

  Asynchronously clears the cache as a Deferred.

  Parameters:

  scope - The coroutine scope to use for the async operation

• getOrPutAsync

   final static <K extends Any, V extends Any> V getOrPutAsync(Cache<K, V> $self, K key, SuspendFunction1<K, V> compute)

  Suspending version of getOrPut using the cache's async loader if available.

• set

   final static <K extends Any, V extends Any> Unit set(Cache<K, V> $self, K key, V value)

  Sets the value for the given key using array access syntax.

  This operator overload allows you to use familiar array-like syntax for putting values into the cache, making cache operations feel more natural and Kotlin-idiomatic.

  // Array-like syntax for cache operations
  cache["user123"] = user
  cache["session_abc"] = sessionData
  cache["config_timeout"] = Duration.ofSeconds(30)
  
  // Equivalent to traditional put operations
  cache.put("user123", user)  // Traditional approach
  cache["user123"] = user     // Kotlin operator approach
  
  // Useful in DSL-like contexts
  fun setupUserCache(cache: Cache<String, User>) {
      cache["admin"] = adminUser
      cache["guest"] = guestUser
      cache["default"] = defaultUser
  }

  Parameters:

  key - key with which the specified value is to be associated

  value - value to be associated with the specified key

• contains

   final static <K extends Any, V extends Any> Boolean contains(Cache<K, V> $self, K key)

  Checks if the cache contains the given key using 'in' operator.

  This operator overload enables the use of Kotlin's 'in' operator to check for key presence, providing a more readable alternative to containsKey().

  // Natural 'in' operator usage
  if ("user123" in cache) {
      val user = cache["user123"]
      processUser(user)
  }
  
  // Equivalent to traditional containsKey
  if (cache.containsKey("user123")) {  // Traditional approach
      // ...
  }
  if ("user123" in cache) {            // Kotlin operator approach
      // ...
  }
  
  // Useful in filtering operations
  val existingKeys = requestedKeys.filter { it in cache }
  val missingKeys = requestedKeys.filterNot { it in cache }

  Parameters:

  key - the key to check for presence in the cache

  Returns:

  true if the cache contains the specified key

• plusAssign

   final static <K extends Any, V extends Any> Unit plusAssign(Cache<K, V> $self, Pair<K, V> pair)

  Adds a key-value pair to the cache using += operator.

  This operator overload allows adding entries using the += operator with Pair objects, providing a concise way to add multiple entries or use destructuring.

  // Add single entry with += operator
  cache += "user123" to user
  cache += "session_abc" to sessionData
  
  // Bulk operations with pairs
  val newEntries = listOf(
      "user1" to user1,
      "user2" to user2,
      "user3" to user3
  )
  newEntries.forEach { cache += it }
  
  // Using with destructuring
  val userData = loadUserData()
  cache += userData  // Where userData is a Pair<String, User>
  
  // In functional programming contexts
  userList.map { it.id to it }.forEach { cache += it }

  Parameters:

  pair - a Pair containing the key and value to be added

• minusAssign

   final static <K extends Any, V extends Any> Unit minusAssign(Cache<K, V> $self, K key)

  Removes a key from the cache using -= operator.

  This operator overload provides a concise way to remove entries from the cache using the -= operator, making removal operations more expressive.

  // Remove single entry with -= operator
  cache -= "user123"
  cache -= "expired_session"
  
  // Bulk removal operations
  val keysToRemove = listOf("user1", "user2", "user3")
  keysToRemove.forEach { cache -= it }
  
  // Conditional removal
  if (user.isExpired) {
      cache -= user.id
  }
  
  // In cleanup operations
  expiredKeys.forEach { cache -= it }

  Parameters:

  key - the key to be removed from the cache

• isEmpty

   final static <K extends Any, V extends Any> Boolean isEmpty(Cache<K, V> $self)

  Returns true if the cache is empty.

• isNotEmpty

   final static <K extends Any, V extends Any> Boolean isNotEmpty(Cache<K, V> $self)

  Returns true if the cache is not empty.

• containsValue

   final static <K extends Any, V extends Any> Boolean containsValue(Cache<K, V> $self, V value)

  Returns true if the cache contains the given value.

• asSequence

   final static <K extends Any, V extends Any> Sequence<Entry.Map<K, V>> asSequence(Cache<K, V> $self)

  Returns a sequence of all entries in the cache for lazy evaluation.

• toMap

   final static <K extends Any, V extends Any> Map<K, V> toMap(Cache<K, V> $self)

  Converts the cache to a regular Map.

• toMutableMap

   final static <K extends Any, V extends Any> Map<K, V> toMutableMap(Cache<K, V> $self)

  Converts the cache to a mutable Map.

• filterKeys

   final static <K extends Any, V extends Any> Map<K, V> filterKeys(Cache<K, V> $self, Function1<K, Boolean> predicate)

  Filters entries by key predicate.

• filterValues

   final static <K extends Any, V extends Any> Map<K, V> filterValues(Cache<K, V> $self, Function1<V, Boolean> predicate)

  Filters entries by value predicate.

• filter

   final static <K extends Any, V extends Any> Map<K, V> filter(Cache<K, V> $self, Function2<K, V, Boolean> predicate)

  Filters entries by key-value predicate.

• mapValues

   final static <K extends Any, V extends Any, R extends Any> Map<K, R> mapValues(Cache<K, V> $self, Function1<V, R> transform)

  Maps values to a new type.

• mapKeys

   final static <K extends Any, V extends Any, R extends Any> Map<R, V> mapKeys(Cache<K, V> $self, Function1<K, R> transform)

  Maps keys to a new type.

• map

   final static <K extends Any, V extends Any, R extends Any, S extends Any> Map<R, S> map(Cache<K, V> $self, Function2<K, V, Pair<R, S>> transform)

  Maps both keys and values to new types.

• putAll

   final static <K extends Any, V extends Any> Unit putAll(Cache<K, V> $self, Map<K, V> map)

  Puts all entries from the given map into the cache.

• removeAll

   final static <K extends Any, V extends Any> List<V> removeAll(Cache<K, V> $self, Collection<K> keys)

  Removes all entries with the given keys from the cache.

• retainAll

   final static <K extends Any, V extends Any> Unit retainAll(Cache<K, V> $self, Collection<K> keysToKeep)

  Retains only the entries with the given keys.

• removeIf

   final static <K extends Any, V extends Any> Integer removeIf(Cache<K, V> $self, Function2<K, V, Boolean> predicate)

  Removes all entries that match the given predicate.

• computeIfAbsent

   final static <K extends Any, V extends Any> V computeIfAbsent(Cache<K, V> $self, K key, Function1<K, V> compute)

  Computes a value for the given key if it's not present in the cache.

• computeIfPresent

   final static <K extends Any, V extends Any> V computeIfPresent(Cache<K, V> $self, K key, Function2<K, V, V> compute)

  Computes a new value for the given key if it's present in the cache.

• compute

   final static <K extends Any, V extends Any> V compute(Cache<K, V> $self, K key, Function2<K, V, V> compute)

  Computes a value for the given key regardless of whether it's present.

• merge

   final static <K extends Any, V extends Any> V merge(Cache<K, V> $self, K key, V value, Function2<V, V, V> merge)

  Merges the given value with the existing value for the key.

• replace

   final static <K extends Any, V extends Any> V replace(Cache<K, V> $self, K key, V value)

  Replaces the value for the given key if it exists.

• replace

   final static <K extends Any, V extends Any> Boolean replace(Cache<K, V> $self, K key, V oldValue, V newValue)

  Replaces the value for the given key if it equals the expected value.

• replaceAll

   final static <K extends Any, V extends Any> Unit replaceAll(Cache<K, V> $self, Function2<K, V, V> transform)

  Replaces all values using the given transformation function.

• getOrPutValue

   final static <K extends Any, V extends Any> V getOrPutValue(Cache<K, V> $self, K key, Function0<V> defaultValue)

  Gets the value for the key or puts and returns the default value.

• hitRatePercent

   final static Double hitRatePercent(CacheStats $self)

  Returns the hit rate as a percentage.

• missRatePercent

   final static Double missRatePercent(CacheStats $self)

  Returns the miss rate as a percentage.

• averageLoadTimeMillis

   final static Double averageLoadTimeMillis(CacheStats $self)

  Returns the average load time in milliseconds.

• formatted

   final static String formatted(CacheStats $self)

  Returns a formatted string representation of the cache statistics.

• getOrNull

   final static <K extends Any, V extends Any> Result<V> getOrNull(Cache<K, V> $self, K key)

  Safely gets a value, returning a Result.

• putOrNull

   final static <K extends Any, V extends Any> Result<Unit> putOrNull(Cache<K, V> $self, K key, V value)

  Safely puts a value, returning a Result.

• removeOrNull

   final static <K extends Any, V extends Any> Result<V> removeOrNull(Cache<K, V> $self, K key)

  Safely removes a value, returning a Result.

• ifContains

   final static <K extends Any, V extends Any> Unit ifContains(Cache<K, V> $self, K key, Function1<V, Unit> action)

  Executes the given action if the cache contains the key.

• ifNotContains

   final static <K extends Any, V extends Any> Unit ifNotContains(Cache<K, V> $self, K key, Function0<Unit> action)

  Executes the given action if the cache does not contain the key.

• cacheConfig

   final static <K extends Any, V extends Any> CacheConfig<K, V> cacheConfig(Function1<CacheConfigBuilder<K, V>, Unit> configure)

  Creates a cache configuration using a DSL-style builder.

  This function provides a Kotlin-idiomatic way to configure cache settings using a type-safe DSL (Domain Specific Language). It's more readable and less verbose than using the traditional builder pattern.

  // Basic cache configuration
  val config = cacheConfig<String, User> {
      maximumSize(1000L)
      expireAfterWrite(Duration.ofMinutes(30))
      recordStats(true)
  }
  
  // Advanced configuration with custom eviction and loaders
  val advancedConfig = cacheConfig<String, ApiResponse> {
      maximumSize(500L)
      expireAfterAccess(Duration.ofMinutes(10))
      refreshAfterWrite(Duration.ofMinutes(5))
  
      // Custom loader
      loader { key -> apiClient.fetchData(key) }
  
      // Custom eviction strategy
      evictionStrategy(LRUEvictionStrategy())
  
      // Event listeners
      listener(object : CacheEventListener<String, ApiResponse> {
          override fun onEvict(key: String, value: ApiResponse, reason: EvictionReason) {
              logger.info("Evicted $key due to $reason")
          }
          // ... other methods
      })
  }
  
  // Weight-based cache
  val weightedConfig = cacheConfig<String, LargeObject> {
      maximumWeight(1_000_000L)  // 1MB total
      weigher { _, value -> value.sizeInBytes }
      evictionStrategy(WeightBasedEvictionStrategy(1_000_000L))
  }

  • Type Safety: Full IDE support with auto-completion

  • Readability: Clean, declarative syntax

  • Flexibility: Easy to add conditional configuration

  • Kotlin Idiomatic: Feels natural in Kotlin codebases

  Parameters:

  configure - the configuration block that sets up the cache

  Returns:

  a configured CacheConfig instance

• createCache

   final static <K extends Any, V extends Any> Cache<K, V> createCache(Function1<CacheConfigBuilder<K, V>, Unit> configure)

  Creates a cache with the given configuration.

• batch

   final static <K extends Any, V extends Any> Cache<K, V> batch(Cache<K, V> $self, Function1<Cache<K, V>, Unit> operations)

  Performs batch operations on the cache.

• measureTime

   final static <K extends Any, V extends Any, R extends Any> Pair<R, Long> measureTime(Cache<K, V> $self, Function1<Cache<K, V>, R> block)

  Executes the given block and measures the time taken.

• getAll

   final static <K extends Any, V extends Any> Map<K, V> getAll(Cache<K, V> $self, Collection<K> keys)

  Gets multiple values at once.

• getAllPresent

   final static <K extends Any, V extends Any> Map<K, V> getAllPresent(Cache<K, V> $self, Collection<K> keys)

  Gets multiple values at once, filtering out null values.

• find

   final static <K extends Any, V extends Any> Entry.Map<K, V> find(Cache<K, V> $self, Function2<K, V, Boolean> predicate)

  Finds the first entry that matches the given predicate.

• findAll

   final static <K extends Any, V extends Any> List<Entry.Map<K, V>> findAll(Cache<K, V> $self, Function2<K, V, Boolean> predicate)

  Finds all entries that match the given predicate.

• count

   final static <K extends Any, V extends Any> Integer count(Cache<K, V> $self, Function2<K, V, Boolean> predicate)

  Counts the number of entries that match the given predicate.

• any

   final static <K extends Any, V extends Any> Boolean any(Cache<K, V> $self, Function2<K, V, Boolean> predicate)

  Checks if any entry matches the given predicate.

• all

   final static <K extends Any, V extends Any> Boolean all(Cache<K, V> $self, Function2<K, V, Boolean> predicate)

  Checks if all entries match the given predicate.

• groupBy

   final static <K extends Any, V extends Any, R extends Any> Map<R, List<Entry.Map<K, V>>> groupBy(Cache<K, V> $self, Function2<K, V, R> keySelector)

  Groups entries by the result of the given function.

• partition

   final static <K extends Any, V extends Any> Pair<List<Entry.Map<K, V>>, List<Entry.Map<K, V>>> partition(Cache<K, V> $self, Function2<K, V, Boolean> predicate)

  Partitions entries into two lists based on the given predicate.

• minByOrNull

   final static <K extends Any, V extends Any, R extends Comparable<R>> Entry.Map<K, V> minByOrNull(Cache<K, V> $self, Function2<K, V, R> selector)

  Returns the minimum entry based on the given comparator.

• maxByOrNull

   final static <K extends Any, V extends Any, R extends Comparable<R>> Entry.Map<K, V> maxByOrNull(Cache<K, V> $self, Function2<K, V, R> selector)

  Returns the maximum entry based on the given comparator.

• summary

   final static <K extends Any, V extends Any> String summary(Cache<K, V> $self)

  Returns a summary of the cache contents.