| // Licensed to the Apache Software Foundation (ASF) under one or more |
| // contributor license agreements. See the NOTICE file distributed with |
| // this work for additional information regarding copyright ownership. |
| // The ASF licenses this file to You under the Apache License, Version 2.0 |
| // (the "License"); you may not use this file except in compliance with |
| // the License. You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| = On-Heap Caching |
| |
| Ignite uses off-heap memory to allocate memory regions outside of Java heap. However, you can enable on-heap caching by setting `CacheConfiguration.setOnheapCacheEnabled(true)`. |
| |
| On-heap caching is useful in scenarios when you do a lot of cache reads on server nodes that work with cache entries in link:data-modeling/data-modeling#binary-object-format[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. |
| |
| |
| [tabs] |
| -- |
| tab:XML[] |
| |
| [source,xml] |
| ---- |
| include::code-snippets/xml/on-heap-cache.xml[tags=ignite-config;!discovery,indent=0] |
| ---- |
| tab:Java[] |
| [source,java] |
| ---- |
| include::{javaCodeDir}/OnHeapCaching.java[tag=onHeap,indent=0] |
| ---- |
| tab:C#/.NET[] |
| [source,csharp] |
| ---- |
| include::code-snippets/dotnet/OnHeapCaching.cs[tag=onheap,indent=0] |
| ---- |
| tab:C++[unsupported] |
| -- |
| |
| |
| == Configuring Eviction Policy |
| |
| When on-heap caching is enabled, 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. |
| |
| NOTE: 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 case, `batchSize` entries are evicted. If eviction by memory size limit is enabled, then eviction starts when the size of cache entries in bytes becomes greater than the maximum memory size. |
| |
| NOTE: Batch eviction is supported only if maximum memory limit isn't set. |
| |
| Eviction policies are pluggable and are controlled via the `EvictionPolicy` interface. The implementation of eviction policy is notified of every cache change and defines the algorithm of choosing the entries to evict from the on-heap cache. |
| |
| === Least Recently Used (LRU) |
| |
| LRU eviction policy, based on the link:http://en.wikipedia.org/wiki/Cache_algorithms#Least_Recently_Used[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) is evicted first. |
| |
| NOTE: LRU eviction policy nicely fits most of the use cases for on-heap caching. Use it whenever in doubt. |
| |
| This eviction policy can be enabled in the cache configuration as shown in the example below. It supports batch eviction and eviction by memory size limit. |
| |
| [tabs] |
| -- |
| tab:XML[] |
| [source,xml] |
| ---- |
| <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> |
| ---- |
| tab:Java[] |
| [source,java] |
| ---- |
| include::{javaCodeDir}/EvictionPolicies.java[tag=LRU,indent=0] |
| ---- |
| tab:C#/.NET[] |
| [source,csharp] |
| ---- |
| include::code-snippets/dotnet/EvictionPolicies.cs[tag=LRU,indent=0] |
| ---- |
| tab:C++[unsupported] |
| -- |
| |
| |
| === First In First Out (FIFO) |
| |
| FIFO eviction policy, based on the https://en.wikipedia.org/wiki/FIFO_(computing_and_electronics)[First-In-First-Out (FIFO)] algorithm, ensures that the entry that has been in the on-heap cache for the longest time is evicted first. |
| It is different from `LruEvictionPolicy` because it ignores the order in which the entries are accessed. |
| |
| This eviction policy can be enabled in the cache configuration as shown in the example below. |
| It supports batch eviction and eviction by memory size limit. |
| |
| [tabs] |
| -- |
| tab:XML[] |
| [source,xml] |
| ---- |
| <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> |
| ---- |
| tab:Java[] |
| [source,java] |
| ---- |
| include::{javaCodeDir}/EvictionPolicies.java[tag=FIFO,indent=0] |
| ---- |
| tab:C#/.NET[] |
| [source,csharp] |
| ---- |
| include::code-snippets/dotnet/EvictionPolicies.cs[tag=FIFO,indent=0] |
| ---- |
| tab:C++[unsupported] |
| -- |
| |
| === Sorted |
| |
| Sorted eviction policy is similar to FIFO eviction policy with the difference that entries' order is defined by default or by a 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. You can provide your own comparator implementation which can use keys, values, or both for entries comparison. |
| |
| Enable sorted eviction policy in the cache configuration as shown below. It supports batch eviction and eviction by memory size limit. |
| |
| [tabs] |
| -- |
| tab:XML[] |
| [source,xml] |
| ---- |
| <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> |
| ---- |
| tab:Java[] |
| [source,java] |
| ---- |
| include::{javaCodeDir}/EvictionPolicies.java[tag=sorted,indent=0] |
| ---- |
| tab:C#/.NET[unsupported] |
| tab:C++[unsupported] |
| -- |