Chapter 10. Eviction

Eviction controls JBoss Cache's memory management by restricting how many nodes are allowed to be stored in memory, and for how long. Memory constraints on servers mean caches cannot grow indefinitely, so eviction needs to occur to prevent out of memory errors. Eviction is most often used alongside Chapter 9, Cache Loaders.

10.1. Design

Eviction in JBoss Cache is designed around four concepts:
  • 1. Collecting statistics
  • 2. Determining which nodes to evict
  • 3. How nodes are evicted
  • 4. Eviction threads.
In addition, Regions play a key role in eviction, as eviction is always configured on a per-region basis so that different subtrees in the cache can have different eviction characteristics.

10.1.1. Collecting Statistics

This is done on the caller's thread whenever anyone interacts with the cache. If eviction is enabled, an EvictionInterceptor is added to the interceptor chain and events are recorded in an event queue. Events are denoted by the EvictionEvent class. Event queues are held on specific Regions so each region has its own event queue.
This aspect of eviction is not configurable, except that the EvictionInterceptor is either added to the interceptor chain or not, depending on whether eviction is enabled.

10.1.2. Determining Which Nodes to Evict

An EvictionAlgorithm implementation processes the eviction queue to decide which nodes to evict. JBoss Cache ships with a number of implementations, including FIFOAlgorithm, LRUAlgorithm, LFUAlgorithm, etc. Each implementation has a corresponding EvictionAlgorithmConfig implementation with configuration details for the algorithm.
Custom EvictionAlgorithm implementations can be provided by implementing the interface or extending one of the provided implementations.
Algorithms are executed by calling its process() method and passing in the event queue to process. This is typically done by calling Region.processEvictionQueues(), which will locate the Algorithm assigned to the region.

10.1.3. How Nodes are Evicted

Once the EvictionAlgorithm decides which nodes to evict, it uses an implementation of EvictionActionPolicy to determine how to evict nodes. This is configurable on a per-region basis, and defaults to DefaultEvictionActionPolicy, which invokes Cache.evict() for each node that needs to be evicted.
JBoss Cache also ships with RemoveOnEvictActionPolicy, which calls Cache.removeNode() for each node that needs to be evicted, instead of Cache.evict().
Custom EvictionActionPolicy implementations can be used as well.

10.1.4. Eviction threads

By default, a single cache-wide eviction thread is used to periodically iterate through registered regions and call Region.processEvictionQueues() on each region. The frequency with which this thread runs can be configured using the wakeUpInterval attribute in the eviction configuration element, and defaults to 5000 milliseconds if not specified.
The eviction thread can be disabled by setting wakeUpInterval to 0. This can be useful if you have your own periodic maintenance thread running and would like to iterate through regions and call Region.processEvictionQueues() yourself.