Summary: Setting Space cache policy, memory usage, and rules for exceeding physical memory capacity.
Overview
The Memory Management facility is used to assist the client in avoiding a situation where a space server gets into an out-of-memory failure scenario. Based on the configured cache policy, the memory manager protects the space (and the application, in the case it is running collocated with the space) from consuming memory beyond a defined threshold.
The client/Application is expected to have some business logic that will handle org.openspaces.core.SpaceMemoryShortageException that might be thrown (when using the openspaces API). When the legacy IJSpace interface is used, com.j_spaces.core.MemoryShortageException will be thrown instead. Without such a business logic, the space server or a client local cache may eventually exhaust all their parent process available memory resources.
Most of the considerations described in this topic are also relevant for the client application when running a Local Cache that is running in LRU Cache policy.
The space memory can be managed using the following:
Eviction policy - You can set the policy to run ALL IN CACHE or LRU (Least Recently Used).
Memory Manager - Provides options for controlling the JVM that is hosting the space memory utilization. It allows you to define thresholds for situations where the memory becomes over-utilized.
Cache Eviction Policies
The space supports two cache eviction policies: LRU-Cache Policy (code 0) and ALL IN CACHE-Cache Policy (code 1) defined via the the space-config.engine.cache_policy property. See below example how you can configure it:
ALL IN CACHE-Cache Policy - Assuming the JVM hosting the space instance has enough heap to hold all data in memory.
LRU-Cache Policy - Assuming the JVM hosting the space instance does not have enough heap to hold all data in memory. By default ALL IN CACHE policy is used for in memory data grid,and LRU-Cache Policy is used for persistent space with external data source.
Calculating the Available Memory
Both the ALL_IN_CACHE and LRU cache policies calculating the JVM process available memory to determine if there is a need to throw SpaceMemoryShortageException or to start and evict objects. Calculating the available memory is performed when the following operations are called: abort, changeReplicationState, clear, commit, count, getReplicationStatus, getRuntimeInfo, getSpacePump, getTemplatesInfo, joinReplicationGroup, leaveReplicationGroup, notify, prepare, prepareAndCommit, read, readMultiple, execute, replace, spaceCopy, update, updateMultiple, write.
Before throwing SpaceMemoryShortageException or MemoryShortageException the local cache/local view/space performs an explicit garbage collection call (system.gc), allowing the JVM to reclaim any unused heap memory. This activity may happen at the client side when running a local cache or a local view or at the space side (JVM hosting the GSC).
The explicit garbage collection call reduces the probability throwing SpaceMemoryShortageException or MemoryShortageException in case the JVM does have some available memory left. Still, such a call might impact the client side (when running local cache/view) or space side responsiveness since during the garbage collection activity no JVM thread will manage to perform its activity. With a client or space using large heap size this might introduce a long pause.
To avoid such a behavior you should add one of the following into your client or space side JVM parameters list: -XX:+DisableExplicitGC -XX:+ExplicitGCInvokesConcurrent
Handling Large JVM Heap Size
When configuring the JVM to use large heap size (over 10GB) it is recommended to use the following values:
These values represent 400MB difference between the high_watermark_percentage and the low_watermark_percentage when having 10GB max heap size. The above values will make sure the memory manager will not waste memory, but throw MemoryShortageException when running in ALL_IN_CACHE or evict objects when running in LRU cache policy mode when the absolute amount of JVM available memory is low.
With large JVM heap size it is recommended to use the CMS Garbage collector. This will avoid long Garbage collector pauses.
Memory Manager Activity when Initializing the Space
In this phase of the space life cycle, the space checks for the amount of available memory. This is relevant when the space performs a warm start, such as ExternalDataSource.initialLoad(), or in a persistent space using SA with RDBMS or an embedded H2 database.
Memory Manager and Transient Objects
Transient Objects are specified using the @SpaceClass (persist=false) decoration. You may specify transient decoration at the class or object level (field method level decoration). When using transient objects, note that they are:
Included in the free heap size calculation.
Included in the count of total objects (for max cache size).
Not evicted when running in LRU cache policy mode.
You may use the transient object option to prevent the space from evicting objects you are not interested to be removed from the space when running in LRU cache policy mode.
Memory Manager Parameters
The following properties used to control the memory manager.
Property
Description
Default value
Supported with Cache Policy
space-config.engine.cache_size
Defines the maximum size of the space cache. This is the total number of space objects across all space class instances, within a single space. This parameter is ignored when running an ALL_IN_CACHE cache policy.
Specifies a maximum threshold for memory use. If the space container's memory usage exceeds this threshold, a com.j_spaces.core.MemoryShortageException is thrown.
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 objects on an LRU basis, and attempts to reach this low_watermark_percentage. This process continues until there are no more objects to be evicted, or until memory use reaches the low_watermark_percentage.
Specifies an upper threshold for checking only write-type operations. Above this level, all operations are checked.
76
ALL_IN_CACHE
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 the space-config.engine.memory_usage.write_only_block_percentage, a com.j_spaces.core.MemoryShortageException is thrown for that write request.
5
LRU
space-config.engine.memory_usage.explicit-gc
If true, the garbage collector is called explicitly before trying to evict.
When using the LRU cache policy, space-config.engine.memory_usage.explicit-gc=false means that the garbage collector might evict less objects 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 affecting performance. Therefore, it is recommended that you define true, only if you want to ensure that the minimum amount of objects are evicted from the space (and not less than the minimum).
false
LRU
space-config.engine.memory_usage.retry_yield_time
Time (in milliseconds) to wait after evicting a batch of objects, and before measuring the current memory utilization.
50
LRU
space-config.engine.initial_load
a persistent space running in LRU cache policy mode is started/deployed, it loads data from the underlying data source before being available for clients to access. The default behavior is to load data up to 50% of the space-config.engine.cache_size value. See the Reloading Data section for details.
50
LRU
A com.j_spaces.core.MemoryShortageException or an org.openspaces.core.SpaceMemoryShortageException are thrown only when the JVM garbage collection and the eviction mechanism do not evict enough memory. This can happen if the space-config.engine.memory_usage.low_watermark_percentage value is too high.
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:
Using an LRU and External Data Source - in this mode, all the space data is kept in the database and therefore the space capacity is dependent on the database capacity rather than the memory capacity. The space maintains in memory, a partial image of the persistent view in an LRU basis.
Using Partitioned Space - in this mode, the space utilizes the physical memory of multiple JVMs. This means the application using the space is able to access all the space instances transparently, as if they were a single space with higher memory capacity.