apache-ignite

1
// Licensed to the Apache Software Foundation (ASF) under one or more
2
// contributor license agreements.  See the NOTICE file distributed with
3
// this work for additional information regarding copyright ownership.
4
// The ASF licenses this file to You under the Apache License, Version 2.0
5
// (the "License"); you may not use this file except in compliance with
6
// the License.  You may obtain a copy of the License at
7
//
8
// http://www.apache.org/licenses/LICENSE-2.0
9
//
10
// Unless required by applicable law or agreed to in writing, software
11
// distributed under the License is distributed on an "AS IS" BASIS,
12
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
// See the License for the specific language governing permissions and
14
// limitations under the License.
15
= Eviction Policies
16

17
When link:persistence/native-persistence[Native Persistence] is off, Ignite holds all cache entries in the off-heap memory and allocates pages as new data comes in.
18
When a memory limit is reached and Ignite cannot allocate a page, some of the data must be purged from memory to avoid OutOfMemory errors.
19
This process is called _eviction_. Eviction prevents the system from running out of memory but at the cost of losing data and having to reload it when you need it again.
20

21
Eviction is used in following cases:
22

23
* for off-heap memory when link:persistence/native-persistence[Native Persistence] is off;
24
* for off-heap memory when Ignite is used with an link:persistence/external-storage[external storage];
25
* for link:configuring-caches/on-heap-caching[on-heap caches];
26
* for link:configuring-caches/near-cache[near caches] if configured.
27

28
When Native Persistence is on, a similar process — called _page replacement_ — is used to free up off-heap memory when Ignite cannot allocate a new page.
29
The difference is that the data is not lost (because it is stored in the persistent storage), and therefore you are less concerned about losing data than about efficiency.
30
Refer to the link:memory-configuration/replacement-policies[Replacement Policies] page for information about page replacement configuration.
31

32
== Off-Heap Memory Eviction
33

34
Off-heap memory eviction is implemented as follows.
35

36
When memory usage exceeds the preset limit, Ignite applies one of the preconfigured algorithms to select a memory page that is most suitable for eviction.
37
Then, each cache entry contained in the page is removed from the page.
38
However, if an entry is locked by a transaction, it is retained.
39
Thus, either the entire page or a large chunk of it is emptied and is ready to be reused.
40

41
image::images/off_heap_memory_eviction.png[Off-Heap Memory Eviction Mechanism]
42

43
By default, off-heap memory eviction is disabled, which means that the used memory constantly grows until it reaches its limit.
44
To enable eviction, specify the page eviction mode in the link:memory-configuration/data-regions/[data region configuration].
45
Note that off-heap memory eviction is configured per link:memory-configuration/data-regions[data region].
46
If you don't use data regions, you have to explicitly add default data region parameters in your configuration to be able to configure eviction.
47

48
By default, eviction starts when the overall RAM consumption by a region gets to 90%.
49
Use the `DataRegionConfiguration.setEvictionThreshold(...)` parameter if you need to initiate eviction earlier or later.
50

51
Ignite supports two page selection algorithms:
52

53
* Random-LRU
54
* Random-2-LRU
55

56
The differences between the two are explained below.
57

58
=== Random-LRU
59

60
To enable the Random-LRU eviction algorithm, configure the data region as shown below:
61

62
[tabs]
63
--
64
tab:XML[]
65
[source,xml]
66
----
67

68
include::code-snippets/xml/eviction.xml[tags=ignite-config;!discovery, indent=0]
69

70
<bean class="org.apache.ignite.configuration.IgniteConfiguration">
71
  <!-- Memory configuration. -->
72
  <property name="dataStorageConfiguration">
73
    <bean class="org.apache.ignite.configuration.DataStorageConfiguration">
74
      <property name="dataRegionConfigurations">
75
        <list>
76
          <!--
77
              Defining a data region that consumes up to 20 GB of RAM.
78
          -->
79
          <bean class="org.apache.ignite.configuration.DataRegionConfiguration">
80
            <!-- Custom region name. -->
81
            <property name="name" value="20GB_Region"/>
82

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

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

89
            <!-- Enabling RANDOM_LRU eviction for this region.  -->
90
            <property name="pageEvictionMode" value="RANDOM_LRU"/>
91
          </bean>
92
        </list>
93
      </property>
94
    </bean>
95
  </property>
96

97
  <!-- The rest of the configuration. -->
98
</bean>
99
----
100
tab:Java[]
101
[source,java]
102
----
103
include::{javaCodeDir}/EvictionPolicies.java[tag=randomLRU,indent=0]
104
----
105
tab:C#/.NET[]
106
[source,csharp]
107
----
108
include::code-snippets/dotnet/EvictionPolicies.cs[tag=randomLRU,indent=0]
109
----
110
tab:C++[unsupported]
111
--
112

113
Random-LRU algorithm works as follows:
114

115
* 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.
116
* When a data page is accessed, its timestamp gets updated in the tracking array.
117
* 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.
118

119
=== Random-2-LRU
120

121
To enable Random-2-LRU eviction algorithm, which is a scan-resistant version of Random-LRU, configure the data region, as shown in the example below:
122

123
[tabs]
124
--
125
tab:XML[]
126
[source,xml]
127
----
128
<bean class="org.apache.ignite.configuration.IgniteConfiguration">
129
  <!-- Memory configuration. -->
130
  <property name="dataStorageConfiguration">
131
    <bean class="org.apache.ignite.configuration.DataStorageConfiguration">
132
      <property name="dataRegionConfigurations">
133
        <list>
134
          <!--
135
              Defining a data region that consumes up to 20 GB of RAM.
136
          -->
137
          <bean class="org.apache.ignite.configuration.DataRegionConfiguration">
138
            <!-- Custom region name. -->
139
            <property name="name" value="20GB_Region"/>
140

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

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

147
            <!-- Enabling RANDOM_2_LRU eviction for this region.  -->
148
            <property name="pageEvictionMode" value="RANDOM_2_LRU"/>
149
          </bean>
150
        </list>
151
      </property>
152
    </bean>
153
  </property>
154

155
  <!-- The rest of the configuration. -->
156
</bean>
157
----
158
tab:Java[]
159
[source,java]
160
----
161
include::{javaCodeDir}/EvictionPolicies.java[tag=random2LRU,indent=0]
162
----
163
tab:C#/.NET[]
164
[source,csharp]
165
----
166
include::code-snippets/dotnet/EvictionPolicies.cs[tag=random2LRU,indent=0]
167
----
168
tab:C++[unsupported]
169
--
170

171
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.
172

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

175
== On-Heap Cache Eviction
176

177
Refer to the link:configuring-caches/on-heap-caching#configuring-eviction-policy[Configuring Eviction Policy for On-Heap Caches] section for the instruction on how to configure eviction policy for on-heap caches.
178