Overview

Memory management can be achieved in three main ways:

• Setting a cache policy – using the ALL IN CACHE management policy or the Least Recently Used (LRU) management policy.
• Memory usage – using the <memory_usage> tag, which provides options for controlling the space memory utilization and allows you to evict Entries from the space.
• Exceeding Physical Memory Capacity – using an LRU Based Persistent Space or a Cluster of In-Memory Spaces with Hash-Based Load-Balancing Policy.

The space includes a dedicated thread that is responsible for clearing expired Entries – the lease manager. For more details, refer to the Lease Manager section.

Cache Policy

The space supports two cache management policies defined via the cache_policy tag:

<!-- 0 - LRU POLICY, 1 - ALL IN CACHE -->
<cache_policy>1</cache_policy>

• All IN CACHE (1) – the space uses only the available physical memory. In a persistent space, the memory is backed with the underlying database but the overall capacity of the space does not exceed the capacity of the available physical memory.

  When using the All IN CACHE, the cache size parameter is ignored.

• Least Recently Used (0) – the space evicts the "oldest" Entries from its memory. "Oldest" Entries are determined by the time they were written or updated to the space. In a persistent space mode, evicting an Entry means that an Entry would simply be removed from the space memory but would still be available through the underlying RDBMS. The space reloads this Entry back into the space memory only if it was requested by a specific read operation.
  Selecting the latter option makes the Cache Manager Size parameter irrelevant, because it indicates that all Entries should be saved in memory, regardless of their total size.

Defining Cache Size

When a persistent space (using the JDBC SA or an indexed file) is using LRU cache policy and the space has been restarted, it loads data from the underlying durable data source (RDBMS, indexed file) before being available for clients to access.

The default behavior is to load data up to 50% of the <cache_size> value.

When the <memory_usage> is true (evicting data from the space based on free heap size), is it recommended to have a large value for the <cache_size> property. This instructs the space engine to ignore the amount of Entries inside the space when launching the eviction mechanism. This ensures that the eviction is based only on heap size free memory.

The combination of the above (large <cache_size> and space restart) may lead to out of memory problems. To avoid this, configure the space-config.engine.initial_load to have a low value (5 below means 5% of the <cache_size> – default is 50%):

XML schema tag:

<space-config>
   <engine>
         <initial_load>5</initial_load>
</space-config>
   </engine>

XPATH property:

space-config.engine.initial_load=5

The space schema file does not include the <initial_load> tag by default. You should add it into the correct location.

The <initial_load_class> tag can also be added to the space schema. This tag specifies which class to load. For example:

<space-config>
   <engine>
      <initial_load_class>com.myCompany.myEntry</initial_load_class>
</space-config>
   </engine>

Setting <initial_load_class>_</initial_load_class> is the same as not having this element in the schema.

Memory Usage

The <memory_usage> tag provides options for controlling the space memory utilization and allows you to evict Entries from the space. Entries are evicted when the number of cached Entries reaches its maximum size or the memory use reaches its limit.
These are the default parameters given for memory usage. They should be in the following order:
high_watermark_percentage >= write_only_block_percentage >= write_only_check_percentage >= low_watermark_percentage

<space-config>
           <engine>
                <!--default cache size of Cache Manager-->
                <cache_size>5000000</cache_size>
                <!--0 - LRU POLICY, 1 - ALL IN CACHE , default value: 1 -->
                <cache_policy>0</cache_policy>
                <!--VM heap size threshold usage percentage-->
                <memory_usage>
                     <enabled>false</enabled>
                     <!--VM heap size max threshold usage percentage-->
                     <high_watermark_percentage>95</high_watermark_percentage>
                     <!--VM heap size lower threshold percentage for blocking write-type operations-->
                     <write_only_block_percentage>85</write_only_block_percentage>
                     <!--VM heap size upper threshold percentage for checking only write-type operations-->
                     <write_only_check_percentage>76</write_only_check_percentage>
                     <!--VM heap size min threshold usage percentage-->
                     <low_watermark_percentage>75</low_watermark_percentage>
                     <!--Amount of entries to be evicted each time we are above the high_watermark_percentage-->
                     <eviction_batch_size>500</eviction_batch_size>
                     <!--Number of retries to lower the memory level below the low_watermark_percentage-->
                     <retry_count>5</retry_count>
                     <!--If true GC will be called explicitly before trying to evict. Default Value:false-->
                     <explicit-gc>false</explicit-gc>               
                </memory_usage>
           </engine>
</space-config>

Element	XPath Property	Description	Default value
<cache_size>	space-config. engine.cache_size	Defines the maximum size of the cache.	100000
<high_watermark_percentage>	space-config. engine.memory_usage. high_watermark_percentage	Specifies a maximum threshold for memory use. If the space container's memory usage exceeds this threshold, a MemoryShortageException is thrown.	95
<low_watermark_percentage>	space-config. engine.memory_usage. low_watermark_percentage	Specifies the recommended lower threshold for the JVM heap size that should be occupied by the space container. When the system reaches the high_watermark_percentage, it evicts entries on an LRU basis, and attempts to reach this low_watermark_percentage. This process continues until there are no more Entries to be evicted, or memory use reaches the low_watermark_percentage.	75
<eviction_batch_size>	space-config. engine.memory_usage. eviction_batch_size	Specifies the amount of Entries to evict each time. This option is relevant only in LRU cache management policy.	500
<write_only_block_percentage>	space-config. engine.memory_usage. write_only_block_percentage	Specifies a lower threshold for blocking write-type operations. Above this level only read/take operations are allowed.	85
<write_only_check_percentage>	space-config. engine.memory_usage. write_only_check_percentage	Specifies an upper threshold for checking only write-type operations. Above this level all operations are checked.	76
<retry_count>	space-config. engine.memory_usage. retry_count	Number of retries to lower the memory level below the Low_watermark_percentage. If after all retries the memory level is still above write_only_block_percentage, a MemoryShortageException is thrown for that write request.	5
<explicit-gc>	space-config. engine.memory_usage. explicit-gc	If true, the garbage collector is be called explicitly before trying to evict. When using the LRU cache policy, explicit-gc=false means that the garbage collector might evict less Entries than the defined minimum (low watermark percentage). This tag is false by default because setting the garbage collector explicitly consumes a large amount of CPU, thus effecting performance. Therefore, it is recommended to define true only if you want to ensure that the minimum amount of Entries are evicted from the space (and not less than the minumum).	false

MemoryShortageException is only thrown when the JVM garbage collection and the eviction mechanism do not evict enough memory. This can happen if the low_watermark_percentage value is too high.

The space schema file does not have the above tag by default. You should add it into the correct location.

Exceeding Physical Memory Capacity

The overall space capacity is not necessarily limited to the capacity of its physical memory.
Currently there are two options for exceeding this limit, detailed below.

• Using an LRU Based Persistent Space – in this mode, all the space data is kept in the RDBMS and therefore the space capacity is dependent on the RDBMS capacity rather than the memory capacity. The space would maintain in memory a partial image of the persistent view on an LRU basis.
• Using Cluster of In-Memory Spaces with Hash-Based Load-Balancing Policy – in this mode, the space utilizes the physical memory of multiple machines using the space clustering mechanism.
  This means the application using the space would be able to access all the space instances transparently as if they were a single space with higher memory capacity.
  The clustered space provides means for virtualizing several physical space instances.
  With the hash-based load-balancing policy, the space proxy would multiplex the space operations (write, read, take, etc.) between those physical space entities. This means that each space entity would store only part of the information based on the Entry hash code. The space proxy would be able to fetch the Entry from the appropriate space instance through the same hash-based mechanism transparent to the application.