Apache Ignite

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

Memory Configuration

Durable Memory Configuration

By default, Ignite nodes consume up to 80% of the RAM available locally, and in most cases this is the only parameter you might need to change. To do this, change the size of the default memory region, as shown below:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">

<property name="memoryConfiguration">
  <bean class="org.apache.ignite.configuration.MemoryConfiguration">
    <!-- Set the size of default memory region to 4GB. -->
    <property name="defaultMemoryPolicySize" value="#{4L * 1024 * 1024 * 1024}"/>
  </bean>
</property>
  
<!-- The rest of the parameters -->
</bean>
IgniteConfiguration cfg = new IgniteConfiguration();

// Changing total RAM size to be used by Ignite Node.
MemoryConfiguration memCfg = new MemoryConfiguration();

// Setting the size of the default memory region to 4GB to achieve this.
memCfg.setDefaultMemoryPolicySize(4L * 1024 * 1024 * 1024);

cfg.setMemoryConfiguration(memCfg);

// Starting the node.
Ignition.start(cfg);

For more advanced tuning of the durable memory, refer to the following documentation sections:

Main Configuration Parameters

To alter the main durable memory settings such as page size, use org.apache.ignite.configuration.MemoryConfiguration that is passed via the IgniteConfiguration.setMemoryConfiguration(...) method. Below you can see some of the available parameters.

Parameter Name
Description
Default Value

setPageSize(...)

Sets default page size.

Usually, you change the parameter when an application generates a lot of the objects that don't fit into a single page.

2 KB

setDefaultMemoryPolicySize(...)

Sets the size of the default memory region which is created automatically.

If the proper is not set then the default region can consume up to 80% of RAM available on a local machine.

80% of RAM

setDefaultMemoryPolicyName(...)

Sets default memory policy's name. By default every cache is bound to a memory region instantiated with this policy.

Refer to memory policies section to learn more about memory policies.

default

setMemoryPolicies(...)

Sets a list of all memory policies available in the cluster.

Refer to memory policies section to learn more about memory policies.

An empty array. A configuration that is used to create the default region is not stored there.

setSystemCacheInitialSize(...)

Sets initial size of a memory region reserved for system cache.

40 MB

setSystemCacheMaxSize(...)

Sets maximum size of a memory region reserved for system cache.

The total size should not be less than 10 MB due to internal data structures overhead.

100 MB

setConcurrencyLevel(...)

Sets the number of concurrent segments in Apache Ignite internal page mapping tables

A total number of available CPUs times 4.

Refer to Ignite javadoc for a complete list of MemoryConfiguration parameters.

The following example shows how to change the page size and concurrency level using MemoryConfiguration:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
    <property name="memoryConfiguration">
        <bean class="org.apache.ignite.configuration.MemoryConfiguration">
            <!-- Set concurrency level -->
            <property name="concurrencyLevel" value="4"/>
                
            <!-- Set the page size to 4 KB -->
            <property name="pageSize" value="4096"/>
        </bean>
    </property>
  
  <!--- Additional settings ---->
</bean>
// Ignite configuration.
IgniteConfiguration cfg = new IgniteConfiguration();

// Page memory configuration.
MemoryConfiguration memCfg = new MemoryConfiguration();

// Altering the concurrency level.
memCfg.setConcurrencyLevel(4);

// Changing the page size to 4 KB.
memCfg.setPageSize(4096);
        
// Applying the new page memory configuration.
cfg.setMemoryConfiguration(memCfg);

Memory Policies

By default, the durable memory initiates a single expandable memory region that can take up to 80% of the RAM available on a local machine. However, there is a way to define multiple memory regions with various parameters and custom behavior relying on the memory policies' API.

Two or More Regions?

Refer to memory region documentation section to discover why you may need to have more than one region configured.

A memory policy is a set of configuration parameters, exposed through org.apache.ignite.configuration.MemoryPolicyConfiguration, like initial and maximum region size, an eviction policy and more.

For instance, to configure a 500 MB memory region with enabled data pages eviction, we need to define a memory policy like below:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
   <!-- Durable Memory configuration -->   
   <property name="memoryConfiguration">
      <bean class="org.apache.ignite.configuration.MemoryConfiguration">
        <!-- Defining a custom memory policy. -->
        <property name="memoryPolicies">
          <list>
            <!-- 500 MB total size and RANDOM_2_LRU eviction algorithm. -->
            <bean class="org.apache.ignite.configuration.MemoryPolicyConfiguration">
              <property name="name" value="500MB_Region"/>
              <!-- 100 MB initial size. -->
              <property name="initialSize" value="#{100 * 1024 * 1024}"/>
              <!-- 500 MB maximum size. -->
              <property name="maxSize" value="#{500 * 1024 * 1024}"/>
              <!-- Enabling data pages eviction. -->
              <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.
MemoryConfiguration memCfg = new MemoryConfiguration();

// Creating a custom memory policy for a new memory region.
MemoryPolicyConfiguration plCfg = new MemoryPolicyConfiguration();

// Policy/region name.
plCfg.setName("500MB_Region_Eviction");

// Setting initial size.
plCfg.setInitialSize(100L * 1024 * 1024);

// Setting maximum size.
plCfg.setMaxSize(500L * 1024 * 1024);

// Setting data pages eviction algorithm.
plCfg.setPageEvictionMode(DataPageEvictionMode.RANDOM_2_LRU);

// Applying the memory policy.
memCfg.setMemoryPolicies(plCfg);
        
// Applying the new page memory configuration.
cfg.setMemoryConfiguration(memCfg);

Ignite cache can be mapped to this region (see the following configuration example). To achieve this, the name of the policy has to be passed as a parameter to org.apache.ignite.configuration.CacheConfiguration.setMemoryPolicyName(...) method:

<bean class="org.apache.ignite.configuration.IgniteConfiguration">
    <!-- Durable Memory and other configuration parameters. -->
    <!-- ....... -->
  
    <property name="cacheConfiguration">
       <list>
           <!-- Cache that is mapped to non-default memory region. -->
           <bean class="org.apache.ignite.configuration.CacheConfiguration">
              <!--
                   Setting a memory policy name to bind to a specific region.
               -->
               <property name="memoryPolicyName" value="500MB_Region"/>
               <!-- Cache unique name. -->
               <property name="name" value="SampleCache"/>
             
               <!-- Additional cache configuration parameters -->
           </bean>
       </list>
    </property>
    
    <!-- The rest of the configuration. -->
    <!-- ....... -->
</bean>  
// Ignite configuration.
IgniteConfiguration cfg = new IgniteConfiguration();

// Durable Memory configuration and the rest of the configuration.
// ....

// Creating a cache configuration.
CacheConfiguration cacheCfg = new CacheConfiguration();

// Setting a memory policy name to bind to a specific memory region.
cacheCfg.setMemoryPolicyName("500MB_Region_Eviction");
        
// Setting the cache name.
cacheCfg.setName("SampleCache");

// Applying the cache configuration.
cfg.setCacheConfiguration(cacheCfg);

Once an Ignite cluster is started with this configuration, the durable memory will allocate 256 MB (default initial size) region that can grow up to 500 MB. That new region will coexist with the default memory region and all the data, as well as indexes for SampleCache will reside in that region. The rest of the caches you might have in your deployment will be bound to the default memory region unless you map them to another region explicitly, as shown above.

If the overall memory usage goes beyond the maximum size parameter, then an out of memory exception will be thrown. To avoid this, do one or combination of the following:

  • Enable Ignite Persistent Store that keeps all the data on disk helping the durable memory to store only hot data in RAM.
  • Use one of eviction algorithms available. Note, that the eviction will be enabled by default only if the Ignite Persistent Store is used, otherwise it will be disabled.
  • Set the maximy size to a bigger value.

Changing Default Memory Policy

The default memory region is instantiated with parameters of the default memory policy prepared by org.apache.ignite.configuration.MemoryConfiguration.createDefaultPolicyConfig() method. If you need to change some of the parameters, follow the steps below:

  • Create a new memory policy with a custom name and parameters.
  • Pass the name of the policy to org.apache.ignite.configuration.MemoryConfiguration. setDefaultMemoryPolicyName(...) method.

Refer to memory policies example and to the configuration file used by the example to see how to configure and use multiple memory regions in your cluster.

Configuration Parameters

org.apache.ignite.configuration.MemoryPolicyConfiguration supports the following parameters:

Parameter Name
Description
Default Value

setName(...)

Unique memory policy name.

Required parameter.

setInitialSize(...)

Sets initial size of the memory region defined by this memory policy. When the used memory size exceeds this value, new chunks of memory will be allocated until maximum size is reached.

256 MB

setMaxSize(...)

Sets maximum size of the memory region defined by this memory policy.

The total size should not be less than 10 MB due to the internal data structures overhead.

If the overall memory usage goes beyond this parameter an out of memory exception will be thrown. To avoid this, enable Ignite Persistent Store or use an eviction algorithm described below, or set the default size to a bigger value.

80% of RAM

setSwapFilePath(...)

A path to the memory-mapped file the memory region defined by this memory policy will be mapped to. Having this path set, allows relying on swapping capabilities of an underlying operating system for the region.

Disabled by default.

setPageEvictionMode(...)

Sets one of the data pages eviction algorithms available for usage. Refer to eviction policies for more details.

Disabled by default.

setEvictionThreshold(...)

A threshold for memory pages eviction initiation. For instance, if the threshold is 0.9 it means that the page memory will start the eviction only after 90% of the memory region (defined by this policy) is occupied.

0.9

setEmptyPagesPoolSize(...)

Specifies the minimal number of empty pages to be present in reuse lists for this memory policy. This parameter ensures that Apache Ignite will be able to successfully evict old data entries when the size of a (key, value) pair is slightly larger than page size / 2.

Increase this parameter if a cache can contain very big entries (total size of pages in this pool should be enough to contain largest cache entry).

100

setMetricsEnabled(...)

Enables memory metrics aggregation for this region. Refer to Memory & Cache Metrics for more details.

false

On-Heap Caching

Ignite Durable Memory is an off-heap memory that allocates all the memory regions outside of Java heap and stores cache entries there. However, you can enable on-heap caching for the cache entries by setting org.apache.ignite.configuration.CacheConfiguration.setOnheapCacheEnabled(...) to true.

On-heap caching is useful for scenarios when you do a lot of cache reads on server nodes that work with cache entries in the binary form or invoke cache entries' deserialization. For instance, this might happen when a distributed computation or deployed service gets some data from caches for further processing.

On-Heap Cache Size

To manage the on-heap cache size and avoid its constant growth, make sure to enable one of available cache entries based eviction policies.

Performance Tips

The performance suggestions are listed in Durable Memory Tuning documentation section.

Example

For more information on how to configure and use multiple memory regions in your cluster, refer to the memory policies example and to the configuration file used in the example.

Memory Configuration

Durable Memory Configuration