Understanding Caffeine Cache Expiration: TimeWheel Mechanism and Custom Expiration Strategies

The article introduces Caffeine's three standard expiration policies— expireAfterAccess , expireAfterWrite , and the custom expireAfter —and explains that the first two simply compare the current time with the element's last access or write timestamp, while the custom policy relies on a hierarchical TimeWheel to manage expirations.

When a cache is built with a custom expiration strategy, Caffeine creates a TimeWheel consisting of five levels of buckets (sizes 64, 64, 32, 4, 1). Each bucket is represented by a two‑dimensional array Node<K,V>[][] wheel , and each slot initially contains a sentinel node ( Sentinel ) that acts as a dummy head for a doubly‑linked list, eliminating null checks.

Elements are added to the wheel via the schedule method, which is invoked from the AddTask when a new entry is put into the cache and a custom expiration is configured. The method finds the appropriate bucket based on the element's variable expiration time and links the node into the bucket's list.

The advance method is called during the cache's maintenance phase. It records the current nanosecond timestamp, determines which wheel levels have progressed, and calls expire for each progressed level.

The expire routine iterates over the affected buckets, removes each node from its list, checks whether the node has truly expired (by comparing node.getVariableTime() with the current nanos ), and either evicts the entry or reschedules it into a lower‑resolution bucket for finer tracking.

In summary, only caches configured with expireAfter use the TimeWheel. When an entry is created, its absolute expiration time is stored in variableTime . As time advances, the wheel moves entries between levels, and expired entries are evicted, providing O(1) amortized cost for adding, removing, and firing expiration events.