Chapter 2. Eviction and Expiration

Eviction and expiration are strategies for preventing OutOfMemoryError exceptions in the Java heap space. In other words, eviction and expiration ensure that Red Hat JBoss Data Grid does not run out of memory.

2.1. Overview of Eviction and Expiration

Eviction
  • Removes unused entries from memory after the number of entries in the cache reaches a maximum limit.
  • The operation is local to a single cache instance. It removes entries from memory only.
  • Executes each time an entry is added or updated in the cache.
Expiration
  • Removes entries from memory after a certain amount of time.
  • The operation is cluster-wide. It removes entries from memory across all cache instances and also removes entries from the cache store.
  • Expiration operations are processed by threads that you can configure with the ExpirationManager interface.

2.2. Configuring Eviction

You configure Red Hat JBoss Data Grid to perform eviction with the <memory /> element in your cache configuration. Alternatively, you can use the MemoryConfigurationBuilder class to configure eviction programmatically.

2.2.1. Eviction Types

Eviction types define the maximum limit for entries in the cache.

COUNT
Measures the number of entries in the cache. When the count exceeds the maximum, JBoss Data Grid evicts unused entries.
MEMORY
Measures the amount of memory that all entries in the cache take up. When the total amount of memory exceeds the maximum, JBoss Data Grid evicts unused entries.

2.2.2. Storage Types

Storage types define how JBoss Data Grid stores entries in the cache.

Storage TypeDescriptionEviction TypePolicy

OBJECT

Stores entries as objects in the Java heap. This is the default storage type.

COUNT

TinyLFU

BINARY

Stores entries as bytes[] in the Java heap.

COUNT or MEMORY

TinyLFU

OFFHEAP

Stores entries as bytes[] in native memory outside the Java.

COUNT or MEMORY

LRU

Important

The BINARY and OFF-HEAP storage types both violate object equality. This occurs because equality is determined by the equivalence of the resulting bytes[] that the storage types generate instead of the object instances.

Note

Red Hat JBoss Data Grid includes the Caffeine caching library that implements a variation of the Least Frequently Used (LFU) cache replacement algorithm known as TinyLFU. For OFFHEAP JBoss Data Grid uses a custom implementation of the Least Recently Used (LRU) algorithm.

2.2.3. Adding the Memory Element

The <memory> element controls how Red Hat JBoss Data Grid stores entries in memory.

For example, as a starting point to configure eviction for a standalone cache, add the <memory> element as follows: 

<local-cache ...>
  <memory>
  </memory>
</local-cache>

2.2.4. Specifying the Storage Type

Define the storage type as a child element under <memory>, as follows:

OBJECT
<memory>
  <object/>
</memory>
BINARY
<memory>
  <binary/>
</memory>
OFFHEAP
<memory>
  <offheap/>
</memory>

2.2.5. Specifying the Eviction Type

Include the eviction attribute with the value set to COUNT or MEMORY.

OBJECT
<memory>
  <object/>
</memory>
Tip

The OBJECT storage type supports COUNT only so you do not need to explicitly set the eviction type.

BINARY
<memory>
  <binary eviction="COUNT"/>
</memory>
OFFHEAP
<memory>
  <offheap eviction="MEMORY"/>
</memory>

2.2.6. Setting the Cache Size

Include the size attribute with a value set to a number greater than zero.

  • For COUNT, the size attribute sets the maximum number of entries the cache can hold before eviction starts.
  • For MEMORY, the size attribute sets the maximum number of bytes the cache can take from memory before eviction starts. For example, a value of 10000000000 is 10 GB.
Tip

Try different cache sizes to determine the optimal setting. A cache size that is too large can cause Red Hat JBoss Data Grid to run out of memory. At the same time, a cache size that is too small wastes available memory.

OBJECT
<memory>
  <object size="100000"/>
</memory>
BINARY
<memory>
  <binary eviction="COUNT" size="100000"/>
</memory>
OFFHEAP
<memory>
  <offheap eviction="MEMORY" size="10000000000"/>
</memory>

2.2.7. Tuning the Off Heap Configuration

Include the address-count attribute when using OFFHEAP storage to prevent collisions that might decrease performance. This attribute specifies the number of pointers that are available in the hash map.

Set the value of the address-count attribute to a number that is greater than the number of cache entries. By default address-count is 2^20, or 1048576. The parameter is always rounded up to a power of 2. 

<memory>
  <offheap eviction="MEMORY" size="10000000000" address-count="1048576"/>
</memory>

2.2.8. Setting the Eviction Strategy

Eviction strategies control how Red Hat JBoss Data Grid performs eviction. You set eviction strategies with the strategy attribute.

The default strategy is NONE, which disables eviction unless you explicitly configure it. For example, here are two configurations that have the same effect: 

<memory/>
<memory>
  <object strategy="NONE"/>
</memory>

When you configure eviction, you implicitly use the REMOVE strategy. For example, the following two configurations have the same effect: 

<memory>
  <object/>
</memory>
<memory>
  <object strategy="REMOVE"/>
</memory>

2.2.8.1. Eviction Strategies

StrategyDescription

NONE

JBoss Data Grid does not evict entries. This is the default setting unless you configure eviction.

REMOVE

JBoss Data Grid removes entries from memory so that the cache does not exceed the configured size. This is the default setting when you configure eviction.

MANUAL

JBoss Data Grid does not perform eviction. Eviction takes place manually by invoking the evict() method from the Cache API.

EXCEPTION

JBoss Data Grid does not write new entries to the cache if doing so would exceed the configured size. Instead of writing new entries to the cache, JBoss Data Grid throws a ContainerFullException.

2.2.9. Configuring Passivation

Passivation configures Red Hat JBoss Data Grid to write entries to a persistent cache store when it removes those entries from memory. In this way, passivation ensures that only a single copy of an entry is maintained, either in-memory or in a cache store but not both.

For more information, see Setting Up Passivation.

2.3. Configuring Expiration

You configure Red Hat JBoss Data Grid to perform expiration at either the entry or cache level.

If you configure expiration for the cache, all entries in that cache inherit that configuration. However, configuring expiration for specific entries takes precedence over configuration for the cache.

You configure expiration for a cache with the <expiration /> element. Alternatively, you can use the ExpirationConfigurationBuilder class to programmatically configure expiration for a cache.

You configure expiration for specific entries with the Cache API.

2.3.1. Expiration Parameters

Expiration parameters configure the amount of time entries can remain in the cache.

lifespan
Specifies how long entries can remain in the cache before they expire. The default value is -1, which is unlimited time.
max-idle
Specifies how long entries can remain idle before they expire. An entry in the cache is idle when no operation is performed with the key. The default value is -1, which is unlimited time.
interval
Specifies the amount of time between expiration operations. The default value is 60000.
Note

While expiration parameters, lifespan and max-idle, are replicated across the cluster, only the value of the lifespan parameter is replicated along with cache entries. For this reason, you should not use the max-idle parameter with clustered caches. For more information on the limitations of using max-idle in clusters, see Red Hat knowledgebase workaround.

2.3.2. Configuring Expiration

Configure Red Hat JBoss Data Grid to perform expiration for a cache as follows:

  1. Add the <expiration /> element 

    <expiration />

  2. Configure the lifespan attribute.

    Specify the amount of time, in milliseconds, that an entry can remain in memory as the value, for example: 

    <expiration lifespan="1000" />

  3. Configure the max-idle attribute.

    Specify the amount of time, in milliseconds, that an entry can remain idle as the value, for example: 

    <expiration lifespan="1000" max-idle="1000" />

  4. Configure the interval attribute.

    Specify the amount of time, in milliseconds, that Red Hat JBoss Data Grid waits between expiration operations, for example: 

    <expiration lifespan="1000" max-idle="1000" interval="120000" />
    Tip

    Set a value of -1 to disable periodic expiration.

2.3.3. Expiration Behavior

Red Hat JBoss Data Grid cannot always expire entries immediately when they reach the time limit. Instead, JBoss Data Grid marks entries as expired and removes them when:

  • Writing entries to the cache store.
  • The maintenance thread that processes expiration identifies entries as expired.

This behavior might indicate that JBoss Data Grid is not performing expiration as expected. However it is the case that the entries are marked as expired but not yet removed from either the memory or the cache store.

To ensure that users cannot receive expired entries, JBoss Data Grid returns null values for entries that are marked as expired but not yet removed.