Apache Ignite Documentation

GridGain Developer Hub - Apache Ignitetm

Welcome to the Apache Ignite developer hub run by GridGain. Here you'll find comprehensive guides and documentation to help you start working with Apache Ignite as quickly as possible, as well as support if you get stuck.

 

GridGain also provides Community Edition which is a distribution of Apache Ignite made available by GridGain. It is the fastest and easiest way to get started with Apache Ignite. The Community Edition is generally more stable than the Apache Ignite release available from the Apache Ignite website and may contain extra bug fixes and features that have not made it yet into the release on the Apache website.

 

Let's jump right in!

 

Documentation     Ask a Question     Download

 

Javadoc     Scaladoc     Examples

Eviction Policies

Overview

Ignite supports two distinct data eviction types -

  1. page-based eviction for the off-heap memory data sets.
  2. entry-based eviction for the optional on-heap cache.

Off-Heap Memory

Configured eviction policy has no effect if Ignite persistence is enabled

Note that if Ignite Persistence is enabled, then the explicit page-based eviction setting has no effect because the oldest pages will be purged from memory automatically. This page) covers how the eviction works in this mode.

For data stored in off-heap memory, Ignite supports page-based eviction. Whenever the maximum memory size is reached, a page is evicted from the off-heap memory.

Page-based eviction can be set per data region. Ignite durable memory consists of one or more data regions configured by DataRegionConfiguration. By default, a region constantly grows until its maximum size is reached. To avoid possible region exhaustion, you may need to set one of the data page eviction modes - Random-LRU or Random-2-LRU via the DataRegionConfiguration.setPageEvictionMode(...) configuration parameter. The eviction modes track data pages usage and evict them based on a specific eviction algorithm.

Random-LRU

To enable the Random-LRU eviction algorithm, pass the DataPageEvictionMode.RANDOM_LRU value into the respective DataRegionConfiguration, as shown in the example below:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
  <!-- Durable memory configuration. -->
  <property name="dataStorageConfiguration">
    <bean class="org.apache.ignite.configuration.DataStorageConfiguration">
      <property name="dataRegionConfigurations">
        <list>
          <!--
              Defining a data region that will consume up to 20 GB of RAM.
          -->
          <bean class="org.apache.ignite.configuration.DataRegionConfiguration">
            <!-- Custom region name. -->
            <property name="name" value="20GB_Region"/>

            <!-- 500 MB initial size (RAM). -->
            <property name="initialSize" value="#{500L * 1024 * 1024}"/>

            <!-- 20 GB maximum size (RAM). -->
            <property name="maxSize" value="#{20L * 1024 * 1024 * 1024}"/>

            <!-- Enabling RANDOM_LRU eviction for this region.  -->
            <property name="pageEvictionMode" value="RANDOM_LRU"/>
          </bean>
        </list>
      </property>
    </bean>
  </property>
  
  <!-- The rest of the configuration. -->
</bean>
// Ignite configuration.
IgniteConfiguration cfg = new IgniteConfiguration();

// Durable Memory configuration.
DataStorageConfiguration storageCfg = new DataStorageConfiguration();

// Creating a new data region.
DataRegionConfiguration regionCfg = new DataRegionConfiguration();

// Region name.
regionCfg.setName("20GB_Region");

// 500 MB initial size (RAM).
regionCfg.setInitialSize(500L * 1024 * 1024);

// 20 GB max size (RAM).
regionCfg.setMaxSize(20L * 1024 * 1024 * 1024);

// Enabling RANDOM_LRU eviction for this region.
regionCfg.setPageEvictionMode(DataPageEvictionMode.RANDOM_LRU);

// Setting the data region configuration.
storageCfg.setDataRegionConfigurations(regionCfg);

// Applying the new configuration.
cfg.setDataStorageConfiguration(storageCfg);

Random-LRU algorithm works the following way:

  • Once a memory region defined by a memory policy is configured, an off-heap array is allocated to track the 'last usage' timestamp for every individual data page.
  • When a data page is accessed, its timestamp gets updated in the tracking array.
  • When it is time to evict a page, the algorithm randomly chooses 5 indexes from the tracking array and evicts the page with the oldest timestamp. If some of the indexes point to non-data pages (index or system pages), then the algorithm picks another page.

Random-2-LRU

To enable Random-2-LRU eviction algorithm, which is a scan-resistant version of Random-LRU, pass DataPageEvictionMode.RANDOM_2_LRU value to a respective DataRegionConfiguration, as shown in the example below:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
  <!-- Durable memory configuration. -->
  <property name="dataStorageConfiguration">
    <bean class="org.apache.ignite.configuration.DataStorageConfiguration">
      <property name="dataRegionConfigurations">
        <list>
          <!--
              Defining a data region that will consume up to 20 GB of RAM.
          -->
          <bean class="org.apache.ignite.configuration.DataRegionConfiguration">
            <!-- Custom region name. -->
            <property name="name" value="20GB_Region"/>

            <!-- 500 MB initial size (RAM). -->
            <property name="initialSize" value="#{500L * 1024 * 1024}"/>

            <!-- 20 GB maximum size (RAM). -->
            <property name="maxSize" value="#{20L * 1024 * 1024 * 1024}"/>

            <!-- Enabling RANDOM_2_LRU eviction for this region.  -->
            <property name="pageEvictionMode" value="RANDOM_2_LRU"/>
          </bean>
        </list>
      </property>
    </bean>
  </property>
  
  <!-- The rest of the configuration. -->
</bean>
// Ignite configuration.
IgniteConfiguration cfg = new IgniteConfiguration();

// Durable Memory configuration.
DataStorageConfiguration storageCfg = new DataStorageConfiguration();

// Creating a new data region.
DataRegionConfiguration regionCfg = new DataRegionConfiguration();

// Region name.
regionCfg.setName("20GB_Region");

// 500 MB initial size (RAM).
regionCfg.setInitialSize(500L * 1024 * 1024);

// 20 GB max size (RAM).
regionCfg.setMaxSize(20L * 1024 * 1024 * 1024);

// Enabling RANDOM_2_LRU eviction for this region.
regionCfg.setPageEvictionMode(DataPageEvictionMode.RANDOM_2_LRU);

// Setting the data region configuration.
storageCfg.setDataRegionConfigurations(regionCfg);

// Applying the new configuration.
cfg.setDataStorageConfiguration(storageCfg);

In Random-2-LRU the two most recent access timestamps are stored for every data page. At the time of eviction, the algorithm randomly chooses 5 indexes from the tracking array and the minimum between two latest timestamps is taken for further comparison with corresponding minimums of four other pages that are chosen as eviction candidates.

Random-LRU-2 outperforms LRU by resolving "one-hit wonder" problem - if a data page is accessed rarely but accidentally accessed once, it's protected from eviction for a long time.

Random-LRU vs. Random-2-LRU

In Random-LRU eviction mode the most recent access timestamp is stored for a data page whereas in Random-2-LRU mode two most recent access timestamps are stored for every data page.

Eviction Triggering

By default, a data page eviction algorithm is triggered when the overall RAM consumption by a region gets to 90%. Use DataRegionConfiguration.setEvictionThreshold(...) parameter if you need to initiate the eviction earlier or later.

Java Heap Cache

The durable memory allows storing hot cache entries in Java heap if on-heap caching feature is enabled via CacheConfiguration.setOnheapCacheEnabled(...). Once the on-heap cache is turned on, you can use one of the on-heap eviction policies to manage the growing on-heap cache.

Eviction policies control the maximum number of elements that can be stored in a cache's on-heap memory. Whenever the maximum on-heap cache size is reached, entries are evicted from Java heap.

The on-heap eviction policies remove the cache entries from Java heap only. The entries stored in the off-heap region of the memory are not affected.

Some eviction policies support batch eviction and eviction by memory size limit. If batch eviction is enabled, then eviction starts when cache size becomes batchSize elements greater than the maximum cache size. In this cases batchSize entries will be evicted. If eviction by memory size limit is enabled, then eviction starts when the size of cache entries in bytes become greater than the maximum memory size.

Batch eviction is supported only if maximum memory limit isn't set.

In Apache Ignite eviction policies are pluggable and are controlled via EvictionPolicy interface. An implementation of eviction policy is notified of every cache change and defines the algorithm of choosing the entries to evict from on-heap cache of the durable memory.

Least Recently Used (LRU)

LRU eviction policy, based on the Least Recently Used (LRU) algorithm, ensures that the least recently used entry (i.e. the entry that has not been touched for the longest time) gets evicted first.

LRU eviction policy nicely fits most of the use cases for on-heap caching. Use it whenever in doubt.

This eviction policy is implemented by LruEvictionPolicy and can be configured via CacheConfiguration. It supports batch eviction and eviction by memory size limit.

<bean class="org.apache.ignite.cache.CacheConfiguration">
  <property name="name" value="myCache"/>
  
  <!-- Enabling on-heap caching for this distributed cache. -->
  <property name="onheapCacheEnabled" value="true"/>
  
  <property name="evictionPolicy">
  	<!-- LRU eviction policy. -->
    <bean class="org.apache.ignite.cache.eviction.lru.LruEvictionPolicy">
    	<!-- Set the maximum cache size to 1 million (default is 100,000). -->
      <property name="maxSize" value="1000000"/>
    </bean>
  </property>
  
    ...
</bean>
CacheConfiguration cacheCfg = new CacheConfiguration();

cacheCfg.setName("cacheName");

// Enabling on-heap caching for this distributed cache.
cacheCfg.setOnheapCacheEnabled(true);

// Set the maximum cache size to 1 million (default is 100,000).
cacheCfg.setEvictionPolicy(new LruEvictionPolicy(1000000));

IgniteConfiguration cfg = new IgniteConfiguration();

cfg.setCacheConfiguration(cacheCfg);

// Start Ignite node.
Ignition.start(cfg);

First In First Out (FIFO)

FIFO eviction policy, based on the First-In-First-Out (FIFO) algorithm, ensures that entry that has been in the on-heap cache for the longest time will be evicted first. It is different from LruEvictionPolicy because it ignores the access order of entries.

This eviction policy is implemented by FifoEvictionPolicy and can be configured via CacheConfiguration. It supports batch eviction and eviction by memory size limit.

<bean class="org.apache.ignite.cache.CacheConfiguration">
  <property name="name" value="myCache"/>
  
  <!-- Enabling on-heap caching for this distributed cache. -->
  <property name="onheapCacheEnabled" value="true"/>
  
  <property name="evictionPolicy">
  	<!-- FIFO eviction policy. -->
    <bean class="org.apache.ignite.cache.eviction.fifo.FifoEvictionPolicy">
    	<!-- Set the maximum cache size to 1 million (default is 100,000). -->
      <property name="maxSize" value="1000000"/>
    </bean>
  </property>
  
    ...
</bean>
CacheConfiguration cacheCfg = new CacheConfiguration();

cacheCfg.setName("cacheName");

// Enabling on-heap caching for this distributed cache.
cacheCfg.setOnheapCacheEnabled(true);

// Set the maximum cache size to 1 million (default is 100,000).
cacheCfg.setEvictionPolicy(new FifoEvictionPolicy(1000000));

IgniteConfiguration cfg = new IgniteConfiguration();

cfg.setCacheConfiguration(cacheCfg);

// Start Ignite node.
Ignition.start(cfg);

Sorted

Sorted eviction policy is similar to FIFO eviction policy with the difference that entries' order is defined by default or by user defined comparator and ensures that the minimal entry (i.e. the entry that has an integer key with the smallest value) gets evicted first.

The default comparator uses cache entries' keys for comparison that imposes a requirement for keys to implement the Comparable interface. User can provide their own comparator implementation which can use keys, values or both for entries comparison.

This eviction policy is implemented by SortedEvictionPolicy and can be configured via CacheConfiguration. It supports batch eviction and eviction by memory size limit.

<bean class="org.apache.ignite.cache.CacheConfiguration">
  <property name="name" value="myCache"/>
  
  <!-- Enabling on-heap caching for this distributed cache. -->
  <property name="onheapCacheEnabled" value="true"/>
  
  <property name="evictionPolicy">
  	<!-- Sorted eviction policy. -->
    <bean class="org.apache.ignite.cache.eviction.sorted.SortedEvictionPolicy">
      <!--
      Set the maximum cache size to 1 million (default is 100,000) 
      and use default comparator.
      -->
      <property name="maxSize" value="1000000"/>
    </bean>
  </property>
  
  ...
</bean>
CacheConfiguration cacheCfg = new CacheConfiguration();

cacheCfg.setName("cacheName");

// Enabling on-heap caching for this distributed cache.
cacheCfg.setOnheapCacheEnabled(true);

// Set the maximum cache size to 1 million (default is 100,000).
cacheCfg.setEvictionPolicy(new SortedEvictionPolicy(1000000));

IgniteConfiguration cfg = new IgniteConfiguration();

cfg.setCacheConfiguration(cacheCfg);

// Start Ignite node.
Ignition.start(cfg);

Random

Random eviction policy randomly chooses entries to evict. This eviction policy is mainly used for debugging and benchmarking purposes.

This eviction policy is implemented by RandomEvictionPolicy and can be configured via CacheConfiguration.

<bean class="org.apache.ignite.cache.CacheConfiguration">
  <property name="name" value="myCache"/>
  
  <!-- Enabling on-heap caching for this distributed cache. -->
  <property name="onheapCacheEnabled" value="true"/>
  
  <property name="evictionPolicy">
  	<!-- Random eviction policy. -->
    <bean class="org.apache.ignite.cache.eviction.random.RandomEvictionPolicy">       	<!-- Set the maximum cache size to 1 million (default is 100,000). -->
      <property name="maxSize" value="1000000"/>
    </bean>
  </property>
  
    ...
</bean>
CacheConfiguration cacheCfg = new CacheConfiguration();

cacheCfg.setName("cacheName");

// Enabling on-heap caching for this distributed cache.
cacheCfg.setOnheapCacheEnabled(true);

// Set the maximum cache size to 1 million (default is 100,000).
cacheCfg.setEvictionPolicy(new RandomEvictionPolicy(1000000));

IgniteConfiguration cfg = new IgniteConfiguration();

cfg.setCacheConfiguration(cacheCfg);

// Start Ignite node.
Ignition.start(cfg);

Eviction Policies