clojure.core.cache

An LRU (Least-Recently-Used) cache is best suited for data subject to locality concerns, where recently accessed items are likely to be accessed again soon.

Advantages

• Simple and easy-to-understand logic.
• Reasonably fast and efficient.
• Performs better as cache size increases.
• Agile in adapting to changing access patterns.

Disadvantages

• Memory usage: Requires more historical data to track access order, making it more memory-intensive than simpler caches like FIFO.
• Access patterns: Performs poorly when elements are accessed occasionally but consistently while other elements are accessed very frequently for a short burst and then never again.
• Efficiency: Requires a larger cache size to achieve high efficiency.

The library provides two distinct namespaces that should not be mixed:

1. clojure.core.cache: Provides an API for immutable in-memory caches. You are responsible for managing the storage of these data structures, typically by wrapping them in a Clojure atom.

2. clojure.core.cache.wrapped: Provides the same API but operates on caches that are already wrapped in an atom. This is generally the more intuitive approach for most use cases. It includes specialized functions like lookup-or-miss to handle common caching patterns safely and efficiently.

Recommendation: Use clojure.core.cache.wrapped for straightforward application state management to avoid the complexity of manually managing immutable cache updates with swap!.

LIRS (Low Inter-Reference Recency Set) is a cache eviction policy that differs from LRU. While LRU relies solely on how recently an item was accessed, LIRS uses the access recency of other cache elements relative to any other block to determine eviction. This makes it more robust in certain access patterns where simple recency might lead to frequent cache misses (e.g., scanning patterns).

Refer to the LRU documentation to compare specific behaviors and the Basic Usage patterns to understand how to interact with the resulting immutable map.

The TTL cache eviction policy is simple and effective for data subject to temporal concerns (data that becomes invalid after a certain amount of time).

Advantages

• Simplicity: The logic is easy to understand.
• Performance: It is reasonably fast.
• Temporal Suitability: Works well for data where age is the primary concern.

Disadvantages

• Memory Overhead: The implementation is moderately memory intensive because it must track "age" information for items.
• Data Requirements: It requires more historical data to operate compared to other strategies.
• Efficiency: Cache size does not generally improve the efficiency of a TTL cache.

Always measure your system's specific characteristics to determine if TTL is the best eviction strategy for your use case.

In a FIFOCache, elements are evicted based on their insertion order. When the number of elements exceeds the :threshold, the element that has been in the cache the longest (the one at the front of the queue) is removed.

Example of eviction behavior:

1. Initialization: Create a cache with a threshold of 3 and seed it with {:a 1, :b 2, :c 3}.
2. Single Eviction: Adding one new element (:d 42) will cause the first element added (:a) to be evicted.
3. Multiple Evictions: Adding multiple elements will evict multiple older values in the order they were added.

;; Initialize with threshold 3
(def C (cache/fifo-cache-factory {:a 1, :b 2, :c 3} :threshold 3))

;; Adding :d 42 evicts :a
(assoc C :d 42)
;; => {:c 3, :b 2, :d 42}

;; Adding :x 36 and :z 138 evicts :b and :c
(assoc C :x 36 :z 138)
;; => {:z 138, :x 36, :b 2}

Since all core.cache types implement the CacheProtocol, you can compose multiple cache behaviors by nesting cache factories. This allows you to layer different eviction policies, such as combining a size-based eviction policy (like FIFO) with a time-based policy (like TTL).

To compose caches, pass the result of one cache factory as the seed data to another. The outer cache wraps the inner cache, applying its policy to the entries managed by the inner cache.

(def C (-> {:a 1 :b 2} 
       (fifo-cache-factory :threshold 2) 
       (ttl-cache-factory :ttl 5000)))

;; Within the TTL window, the cache evicts elements using FIFO policy:
(assoc C :c 42)
;;=> {:b 2, :c 42}

;; After the TTL window expires, expired elements are also evicted:
(assoc C :d 138)
;;=> {:d 138}

To use core.cache in a Leiningen project, add the following dependency to the :dependencies vector in your project.clj file. Replace the version string with the specific version you require.

[org.clojure/core.cache "1.0.217"]

The LU cache eviction policy is simple and effective in specific scenarios, but has trade-offs depending on your access patterns.

Advantages

• Performs well if access patterns remain stable over time.
• Logic is easy to understand and reason about.
• Reasonably fast performance.
• Works well with data subject to temporal locality concerns.

Disadvantages

• Performs poorly if access patterns change frequently.
• Requires historical access data to function effectively.
• Generally requires a larger cache size to achieve high efficiency compared to other strategies.

Recommendation: Always measure your system's specific access characteristics to determine if LU is the best eviction strategy for your use case.

For Maven-driven projects, add the following <dependency> block to the <dependencies> section of your pom.xml file. Replace the version tag with the specific version you require.

<dependency>
  <groupId>org.clojure</groupId>
  <artifactId>core.cache</artifactId>
  <version>1.0.217</version>
</dependency>