You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ignite.apache.org by ag...@apache.org on 2017/04/18 09:00:49 UTC
[37/50] [abbrv] ignite git commit: Fixed memory policies example and
improved page memory related documentation.
Fixed memory policies example and improved page memory related documentation.
Project: http://git-wip-us.apache.org/repos/asf/ignite/repo
Commit: http://git-wip-us.apache.org/repos/asf/ignite/commit/56e83a82
Tree: http://git-wip-us.apache.org/repos/asf/ignite/tree/56e83a82
Diff: http://git-wip-us.apache.org/repos/asf/ignite/diff/56e83a82
Branch: refs/heads/ignite-4985
Commit: 56e83a82430c5e608f61fd9770b744e2df28f1d2
Parents: 90bd8b5
Author: Denis Magda <dm...@gridgain.com>
Authored: Mon Apr 17 17:27:14 2017 -0700
Committer: Denis Magda <dm...@gridgain.com>
Committed: Mon Apr 17 17:27:14 2017 -0700
----------------------------------------------------------------------
examples/config/example-memory-policies.xml | 14 +--
.../datagrid/MemoryPoliciesExample.java | 16 ++--
.../configuration/CacheConfiguration.java | 4 +-
.../configuration/DataPageEvictionMode.java | 33 ++++---
.../configuration/MemoryConfiguration.java | 87 +++++++++++++-----
.../MemoryPolicyConfiguration.java | 96 +++++++++++++++-----
6 files changed, 178 insertions(+), 72 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/ignite/blob/56e83a82/examples/config/example-memory-policies.xml
----------------------------------------------------------------------
diff --git a/examples/config/example-memory-policies.xml b/examples/config/example-memory-policies.xml
index 9390a20..121b8a5 100644
--- a/examples/config/example-memory-policies.xml
+++ b/examples/config/example-memory-policies.xml
@@ -53,12 +53,12 @@
</bean>
<!--
- Memory region of 10 MBs in size with an eviction enabled.
+ Memory region of 20 MBs in size with an eviction enabled.
-->
<bean class="org.apache.ignite.configuration.MemoryPolicyConfiguration">
- <property name="name" value="10MB_Region_Eviction"/>
- <!-- 10 MB memory region. -->
- <property name="size" value="#{10 * 1024 * 1024}"/>
+ <property name="name" value="20MB_Region_Eviction"/>
+ <!-- 20 MB memory region. -->
+ <property name="size" value="#{20 * 1024 * 1024}"/>
<!-- Enabling eviction for this memory region -->
<property name="pageEvictionMode" value="RANDOM_2_LRU"/>
</bean>
@@ -68,9 +68,9 @@
'swapFilePath' parameter.
-->
<bean class="org.apache.ignite.configuration.MemoryPolicyConfiguration">
- <property name="name" value="5MB_Region_Swapping"/>
- <!-- 5 MB memory region. -->
- <property name="size" value="#{5 * 1024 * 1024}"/>
+ <property name="name" value="15MB_Region_Swapping"/>
+ <!-- 15 MB memory region. -->
+ <property name="size" value="#{15 * 1024 * 1024}"/>
<!-- Setting a name of the swapping file. -->
<property name="swapFilePath" value="memoryPolicyExampleSwap"/>
</bean>
http://git-wip-us.apache.org/repos/asf/ignite/blob/56e83a82/examples/src/main/java/org/apache/ignite/examples/datagrid/MemoryPoliciesExample.java
----------------------------------------------------------------------
diff --git a/examples/src/main/java/org/apache/ignite/examples/datagrid/MemoryPoliciesExample.java b/examples/src/main/java/org/apache/ignite/examples/datagrid/MemoryPoliciesExample.java
index 3f27d3e..52cda5f 100644
--- a/examples/src/main/java/org/apache/ignite/examples/datagrid/MemoryPoliciesExample.java
+++ b/examples/src/main/java/org/apache/ignite/examples/datagrid/MemoryPoliciesExample.java
@@ -43,11 +43,11 @@ public class MemoryPoliciesExample {
/** Name of the default memory policy defined in 'example-memory-policies.xml'. */
public static final String POLICY_DEFAULT = "Default_Region";
- /** Name of the memory policy that creates a memory region limited by 10 MB with eviction enabled */
- public static final String POLICY_10MB_EVICTION = "10MB_Region_Eviction";
+ /** Name of the memory policy that creates a memory region limited by 20 MB with eviction enabled */
+ public static final String POLICY_20MB_EVICTION = "20MB_Region_Eviction";
/** Name of the memory policy that creates a memory region mapped to a memory-mapped file. */
- public static final String POLICY_5MB_MEMORY_MAPPED_FILE = "5MB_Region_Swapping";
+ public static final String POLICY_15MB_MEMORY_MAPPED_FILE = "15MB_Region_Swapping";
/**
* Executes example.
@@ -66,19 +66,19 @@ public class MemoryPoliciesExample {
*/
CacheConfiguration<Integer, Integer> firstCacheCfg = new CacheConfiguration<>("firstCache");
- firstCacheCfg.setMemoryPolicyName(POLICY_10MB_EVICTION);
+ firstCacheCfg.setMemoryPolicyName(POLICY_20MB_EVICTION);
firstCacheCfg.setCacheMode(CacheMode.PARTITIONED);
firstCacheCfg.setAtomicityMode(CacheAtomicityMode.TRANSACTIONAL);
CacheConfiguration<Integer, Integer> secondCacheCfg = new CacheConfiguration<>("secondCache");
- secondCacheCfg.setMemoryPolicyName(POLICY_10MB_EVICTION);
+ secondCacheCfg.setMemoryPolicyName(POLICY_20MB_EVICTION);
secondCacheCfg.setCacheMode(CacheMode.REPLICATED);
secondCacheCfg.setAtomicityMode(CacheAtomicityMode.ATOMIC);
IgniteCache<Integer, Integer> firstCache = ignite.createCache(firstCacheCfg);
IgniteCache<Integer, Integer> secondCache = ignite.createCache(secondCacheCfg);
- System.out.println(">>> Started two caches bound to '" + POLICY_10MB_EVICTION + "' memory region.");
+ System.out.println(">>> Started two caches bound to '" + POLICY_20MB_EVICTION + "' memory region.");
/**
* Preparing a configuration for a cache that will be bound to the memory region defined by
@@ -86,11 +86,11 @@ public class MemoryPoliciesExample {
*/
CacheConfiguration<Integer, Integer> thirdCacheCfg = new CacheConfiguration<>("thirdCache");
- thirdCacheCfg.setMemoryPolicyName(POLICY_5MB_MEMORY_MAPPED_FILE);
+ thirdCacheCfg.setMemoryPolicyName(POLICY_15MB_MEMORY_MAPPED_FILE);
IgniteCache<Integer, Integer> thirdCache = ignite.createCache(thirdCacheCfg);
- System.out.println(">>> Started a cache bound to '" + POLICY_5MB_MEMORY_MAPPED_FILE + "' memory region.");
+ System.out.println(">>> Started a cache bound to '" + POLICY_15MB_MEMORY_MAPPED_FILE + "' memory region.");
/**
http://git-wip-us.apache.org/repos/asf/ignite/blob/56e83a82/modules/core/src/main/java/org/apache/ignite/configuration/CacheConfiguration.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/apache/ignite/configuration/CacheConfiguration.java b/modules/core/src/main/java/org/apache/ignite/configuration/CacheConfiguration.java
index dc64c26..2d81458 100644
--- a/modules/core/src/main/java/org/apache/ignite/configuration/CacheConfiguration.java
+++ b/modules/core/src/main/java/org/apache/ignite/configuration/CacheConfiguration.java
@@ -532,6 +532,8 @@ public class CacheConfiguration<K, V> extends MutableConfiguration<K, V> {
}
/**
+ * Checks if the on-heap cache is enabled for the off-heap based page memory.
+ *
* @return On-heap cache enabled flag.
*/
public boolean isOnheapCacheEnabled() {
@@ -539,7 +541,7 @@ public class CacheConfiguration<K, V> extends MutableConfiguration<K, V> {
}
/**
- * Configures on-heap cache.
+ * Configures on-heap cache for the off-heap based page memory.
*
* @param onheapCache {@code True} if on-heap cache should be enabled.
* @return {@code this} for chaining.
http://git-wip-us.apache.org/repos/asf/ignite/blob/56e83a82/modules/core/src/main/java/org/apache/ignite/configuration/DataPageEvictionMode.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/apache/ignite/configuration/DataPageEvictionMode.java b/modules/core/src/main/java/org/apache/ignite/configuration/DataPageEvictionMode.java
index da3dbdf..91f707e 100644
--- a/modules/core/src/main/java/org/apache/ignite/configuration/DataPageEvictionMode.java
+++ b/modules/core/src/main/java/org/apache/ignite/configuration/DataPageEvictionMode.java
@@ -18,27 +18,36 @@
package org.apache.ignite.configuration;
/**
- * Enumeration defines data page eviction modes.
+ * The enumeration defines an algorithm to be used for memory pages eviction. A mode is set for a specific
+ * {@link MemoryPolicyConfiguration}. Only data pages, that store key-value entries, are eligible for eviction. The
+ * other types of pages like index or system pages are evictable.
*/
public enum DataPageEvictionMode {
- /** Disabled. */
+ /** Eviction is disabled. */
DISABLED,
/**
- * Random-LRU algorithm. In a nutshell:
- * 1) During memory policy initialization, off-heap array is allocated to track timestamp of last usage for each
- * data page.
- * 2) When data page on address X is accessed, current timestamp is stored in X / PAGE_SIZE array position.
- * 3) When there's a need for eviction, we randomly choose 5 indices of array (if some of indices point to
- * non-data pages, re-choose them) and evict data page with minimum timestamp.
+ * Activates Random-LRU algorithm that works the way below:
+ * <ul>
+ * <li>Once a memory region defined by a memory policy is configured, an off-heap array is allocated to track
+ * last usage timestamp for every individual data page. The size of the array is calculated this way - size =
+ * ({@link MemoryPolicyConfiguration#getSize()} / {@link MemoryConfiguration#pageSize})</li>
+ * <li>When a data page is accessed, its timestamp gets updated in the tracking array. The page index in the
+ * tracking array is calculated this way - index = (pageAddress / {@link MemoryPolicyConfiguration#getSize()}</li>
+ * <li>When it's required to evict some pages, the algorithm randomly chooses 5 indexes from the tracking array and
+ * evicts a page with the latest timestamp. If some of the indexes point to non-data pages (index or system pages)
+ * then the algorithm peaks another ones.</li>
+ * </ul>
*/
RANDOM_LRU,
/**
- * Random-2-LRU algorithm. Scan-resistant version of Random-LRU. The only difference is that we store two
- * previous timestamps for each data page, and choose minimum between "older" timestamps. LRU-2 outperforms LRU by
- * resolving "one-hit wonder" problem: if page is accessed very rarely, but accidentally accessed once, it's
- * protected from eviction for long time.
+ * Activates Random-2-LRU algorithm which is a scan resistant version of Random-LRU.
+ * <p>
+ * This algorithm differs from Random-LRU only in a way that two latest access timestamps are stored for every
+ * data page. At the eviction time, a minimum between two latest timestamps is taken for further comparison with
+ * minimums of other pages that might be evicted. LRU-2 outperforms LRU by resolving "one-hit wonder" problem -
+ * if a data page is accessed rarely, but accidentally accessed once, it's protected from eviction for a long time.
*/
RANDOM_2_LRU
}
http://git-wip-us.apache.org/repos/asf/ignite/blob/56e83a82/modules/core/src/main/java/org/apache/ignite/configuration/MemoryConfiguration.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/apache/ignite/configuration/MemoryConfiguration.java b/modules/core/src/main/java/org/apache/ignite/configuration/MemoryConfiguration.java
index fce6894..de8fdbf 100644
--- a/modules/core/src/main/java/org/apache/ignite/configuration/MemoryConfiguration.java
+++ b/modules/core/src/main/java/org/apache/ignite/configuration/MemoryConfiguration.java
@@ -22,24 +22,34 @@ import org.apache.ignite.internal.util.typedef.internal.A;
import org.apache.ignite.internal.util.typedef.internal.U;
/**
- * Page memory configuration of an Apache Ignite node.
- *
- * <p>It can be configured using {@link IgniteConfiguration} as follows:</p>
+ * A page memory configuration for an Apache Ignite node. The page memory is a manageable off-heap based memory
+ * architecture that divides all continuously allocated memory regions into pages of fixed size
+ * (see {@link MemoryConfiguration#getPageSize()}. An individual page can store one or many cache key-value entries
+ * that allows reusing the memory in the most efficient way and avoid memory fragmentation issues.
+ * <p>
+ * By default, the page memory allocates a single continuous memory region using settings of
+ * {@link MemoryConfiguration#createDefaultPolicyConfig()}. All the caches that will be configured in an application
+ * will be mapped to this memory region by default, thus, all the cache data will reside in that memory region.
+ * <p>
+ * If initial size of the default memory region doesn't satisfy requirements or it's required to have multiple memory
+ * regions with different properties then {@link MemoryPolicyConfiguration} can be used for both scenarios.
+ * For instance, Using memory policies you can define memory regions of different maximum size, eviction policies,
+ * swapping options, etc. Once you define a new memory region you can bind particular Ignite caches to it.
+ * <p>
+ * To learn more about memory policies refer to {@link MemoryPolicyConfiguration} documentation.
+ * <p>Sample configuration below shows how to make 5 GB memory regions the default one for Apache Ignite:</p>
* <pre>
* {@code
* <property name="memoryConfiguration">
* <bean class="org.apache.ignite.configuration.MemoryConfiguration">
- * <property name="systemCacheMemorySize" value="103833600"/>
+ * <property name="systemCacheMemorySize" value="#{100 * 1024 * 1024}"/>
* <property name="defaultMemoryPolicyName" value="default_mem_plc"/>
*
* <property name="memoryPolicies">
* <list>
* <bean class="org.apache.ignite.configuration.MemoryPolicyConfiguration">
* <property name="name" value="default_mem_plc"/>
- * <property name="size" value="103833600"/>
- * </bean>
- * <bean class="org.apache.ignite.configuration.MemoryPolicyConfiguration">
- * ...
+ * <property name="size" value="#{5 * 1024 * 1024 * 1024}"/>
* </bean>
* </list>
* </property>
@@ -52,39 +62,43 @@ public class MemoryConfiguration implements Serializable {
/** */
private static final long serialVersionUID = 0L;
- /** Default MemoryPolicy size is 1GB. */
+ /** Default memory policy's size (1 GB). */
public static final long DFLT_MEMORY_POLICY_SIZE = 1024 * 1024 * 1024;
- /** Default size of memory chunk for system cache is 100MB. */
+ /** Default size of a memory chunk for the system cache (100 MB). */
public static final long DFLT_SYS_CACHE_MEM_SIZE = 100 * 1024 * 1024;
- /** Default page size. */
+ /** Default memory page size. */
public static final int DFLT_PAGE_SIZE = 2 * 1024;
- /** Size of memory for system cache. */
+ /** Size of a memory chunk reserved for system cache needs. */
private long sysCacheMemSize = DFLT_SYS_CACHE_MEM_SIZE;
- /** Page size. */
+ /** Memory page size. */
private int pageSize = DFLT_PAGE_SIZE;
/** Concurrency level. */
private int concLvl;
- /** Name of MemoryPolicy to be used as default. */
+ /** A name of the memory policy that defines the default memory region. */
private String dfltMemPlcName;
/** Memory policies. */
private MemoryPolicyConfiguration[] memPlcs;
/**
- * @return memory size for system cache.
+ * Gets size of a memory chunk reserved for system cache needs.
+ *
+ * @return Size in bytes.
*/
public long getSystemCacheMemorySize() {
return sysCacheMemSize;
}
/**
- * @param sysCacheMemSize Memory size for system cache.
+ * Sets the size of a memory chunk reserved for system cache needs.
+ *
+ * @param sysCacheMemSize Size in bytes.
*/
public MemoryConfiguration setSystemCacheMemorySize(long sysCacheMemSize) {
this.sysCacheMemSize = sysCacheMemSize;
@@ -93,14 +107,19 @@ public class MemoryConfiguration implements Serializable {
}
/**
- * @return Page size.
+ * The pages memory consists of one or more continuous memory regions defined by {@link MemoryPolicyConfiguration}.
+ * Every memory region is split on pages of fixed size that store actual cache entries.
+ *
+ * @return Page size in bytes.
*/
public int getPageSize() {
return pageSize;
}
/**
- * @param pageSize Page size.
+ * Changes the page size.
+ *
+ * @param pageSize Page size in bytes.
*/
public MemoryConfiguration setPageSize(int pageSize) {
A.ensure(pageSize >= 1024 && pageSize <= 16 * 1024, "Page size must be between 1kB and 16kB.");
@@ -112,14 +131,20 @@ public class MemoryConfiguration implements Serializable {
}
/**
- * @return array of MemoryPolicyConfiguration objects.
+ * Gets an array of all memory policies configured. Apache Ignite will instantiate a dedicated memory region per
+ * policy. An Apache Ignite cache can be mapped to a specific policy with
+ * {@link CacheConfiguration#setMemoryPolicyName(String)} method.
+ *
+ * @return Array of configured memory policies.
*/
public MemoryPolicyConfiguration[] getMemoryPolicies() {
return memPlcs;
}
/**
- * @param memPlcs MemoryPolicyConfiguration instances.
+ * Sets memory policies configurations.
+ *
+ * @param memPlcs Memory policies configurations.
*/
public MemoryConfiguration setMemoryPolicies(MemoryPolicyConfiguration... memPlcs) {
this.memPlcs = memPlcs;
@@ -128,7 +153,13 @@ public class MemoryConfiguration implements Serializable {
}
/**
- * @return default {@link MemoryPolicyConfiguration} instance.
+ * Creates a configuration for the default memory policy that will instantiate the default continuous memory region.
+ * To override settings of the default memory policy in order to create the default memory region with different
+ * parameters, create own memory policy first, pass it to
+ * {@link MemoryConfiguration#setMemoryPolicies(MemoryPolicyConfiguration...)} method and change the name of the
+ * default memory policy with {@link MemoryConfiguration#setDefaultMemoryPolicyName(String)}.
+ *
+ * @return default Memory policy configuration.
*/
public MemoryPolicyConfiguration createDefaultPolicyConfig() {
MemoryPolicyConfiguration memPlc = new MemoryPolicyConfiguration();
@@ -140,6 +171,7 @@ public class MemoryConfiguration implements Serializable {
}
/**
+ * TODO: document
* @return Concurrency level.
*/
public int getConcurrencyLevel() {
@@ -147,6 +179,7 @@ public class MemoryConfiguration implements Serializable {
}
/**
+ * TODO: document
* @param concLvl Concurrency level.
*/
public MemoryConfiguration setConcurrencyLevel(int concLvl) {
@@ -156,14 +189,22 @@ public class MemoryConfiguration implements Serializable {
}
/**
- * @return Name of MemoryPolicy to be used as default.
+ * Gets a name of default memory policy.
+ *
+ * @return A name of a custom memory policy configured with {@link MemoryConfiguration} or {@code null} of the
+ * default policy is used.
*/
public String getDefaultMemoryPolicyName() {
return dfltMemPlcName;
}
/**
- * @param dfltMemPlcName Name of MemoryPolicy to be used as default.
+ * Sets the name for the default memory policy that will initialize the default memory region.
+ * To set own default memory policy, create the policy first, pass it to
+ * {@link MemoryConfiguration#setMemoryPolicies(MemoryPolicyConfiguration...)} method and change the name of the
+ * default memory policy with {@link MemoryConfiguration#setDefaultMemoryPolicyName(String)}.
+ *
+ * @param dfltMemPlcName Name of a memory policy to be used as default one.
*/
public MemoryConfiguration setDefaultMemoryPolicyName(String dfltMemPlcName) {
this.dfltMemPlcName = dfltMemPlcName;
http://git-wip-us.apache.org/repos/asf/ignite/blob/56e83a82/modules/core/src/main/java/org/apache/ignite/configuration/MemoryPolicyConfiguration.java
----------------------------------------------------------------------
diff --git a/modules/core/src/main/java/org/apache/ignite/configuration/MemoryPolicyConfiguration.java b/modules/core/src/main/java/org/apache/ignite/configuration/MemoryPolicyConfiguration.java
index c838756..2cd6d02 100644
--- a/modules/core/src/main/java/org/apache/ignite/configuration/MemoryPolicyConfiguration.java
+++ b/modules/core/src/main/java/org/apache/ignite/configuration/MemoryPolicyConfiguration.java
@@ -18,11 +18,43 @@ package org.apache.ignite.configuration;
import java.io.Serializable;
import org.apache.ignite.internal.mem.OutOfMemoryException;
-import org.apache.ignite.internal.pagemem.PageMemory;
-import org.apache.ignite.internal.processors.cache.database.MemoryPolicy;
/**
- * This class defines {@code MemoryPolicy} configuration.
+ * This class allows defining custom memory policies' configurations with various parameters for Apache Ignite
+ * page memory (see {@link MemoryConfiguration}. For each configured memory policy Apache Ignite instantiates
+ * respective memory regions with different parameters like maximum size, eviction policy, swapping options, etc.
+ * An Apache Ignite cache can be mapped to a particular policy using
+ * {@link CacheConfiguration#setMemoryPolicyName(String)} method.
+ * <p>Sample configuration below shows how to configure several memory policies:</p>
+ * <pre>
+ * {@code
+ * <property name="memoryConfiguration">
+ * <bean class="org.apache.ignite.configuration.MemoryConfiguration">
+ * <property name="defaultMemoryPolicyName" value="Default_Region"/>
+ * <property name="pageSize" value="4096"/>
+ *
+ * <property name="memoryPolicies">
+ * <list>
+ * <bean class="org.apache.ignite.configuration.MemoryPolicyConfiguration">
+ * <property name="name" value="Default_Region"/>
+ * <property name="size" value="#{100 * 1024 * 1024}"/>
+ * </bean>
+ *
+ * <bean class="org.apache.ignite.configuration.MemoryPolicyConfiguration">
+ * <property name="name" value="20MB_Region_Eviction"/>
+ * <property name="size" value="#{20 * 1024 * 1024}"/>
+ * <property name="pageEvictionMode" value="RANDOM_2_LRU"/>
+ * </bean>
+ *
+ * <bean class="org.apache.ignite.configuration.MemoryPolicyConfiguration">
+ * <property name="name" value="25MB_Region_Swapping"/>
+ * <property name="size" value="#{25 * 1024 * 1024}"/>
+ * <property name="swapFilePath" value="memoryPolicyExampleSwap"/>
+ * </bean>
+ * </list>
+ * </property>
+ * }
+ * </pre>
*/
public final class MemoryPolicyConfiguration implements Serializable {
/** */
@@ -31,23 +63,25 @@ public final class MemoryPolicyConfiguration implements Serializable {
/** Memory policy name. */
private String name;
- /** Memory policy size. */
+ /** Memory policy maximum size. */
private long size;
/** An optional path to a memory mapped file for this memory policy. */
private String swapFilePath;
- /** Algorithm for per-page eviction. If {@link DataPageEvictionMode#DISABLED} set, eviction is not performed. */
+ /** An algorithm for memory pages eviction. */
private DataPageEvictionMode pageEvictionMode = DataPageEvictionMode.DISABLED;
- /** Threshold for per-page eviction.
- * When this percentage of memory pages of the current policy is allocated (90% by default),
- * system starts page eviction.
- * Decrease this parameter if {@link OutOfMemoryException} occurred with enabled page eviction.
+ /**
+ * 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% memory region (defined by this policy) is occupied.
*/
private double evictionThreshold = 0.9;
- /** When {@link #evictionThreshold} is reached, allocation of new data pages is prevented by maintaining this
+ /**
+ * TODO: not clear description.
+ *
+ * When {@link #evictionThreshold} is reached, allocation of new data pages is prevented by maintaining this
* amount of evicted data pages in the pool. If any thread needs free page to store cache entry,
* it will take empty page from the pool instead of allocating a new one.
* Increase this parameter if cache can contain very big entries (total size of pages in the pool should be enough
@@ -57,14 +91,18 @@ public final class MemoryPolicyConfiguration implements Serializable {
private int emptyPagesPoolSize = 100;
/**
- * Unique name of MemoryPolicy.
+ * Gets memory policy name.
+ *
+ * @return Memory policy name.
*/
public String getName() {
return name;
}
/**
- * @param name Unique name of MemoryPolicy.
+ * Sets memory policy name. The name must be non empty and must not be equal to the reserved 'sysMemPlc' one.
+ *
+ * @param name Memory policy name.
*/
public MemoryPolicyConfiguration setName(String name) {
this.name = name;
@@ -73,14 +111,18 @@ public final class MemoryPolicyConfiguration implements Serializable {
}
/**
- * Size in bytes of {@link PageMemory} in bytes that will be created for this configuration.
+ * Maximum memory region size defined by this memory policy. If the whole data can not fit into the memory region
+ * an out of memory exception will be thrown.
+ *
+ * @return Size in bytes.
*/
public long getSize() {
return size;
}
/**
- * Size in bytes of {@link PageMemory} in bytes that will be created for this configuration.
+ * Sets maximum memory region size defined by this memory policy. The total size can not be less than 1 MB (TODO: double check)
+ * due to internal requirements.
*/
public MemoryPolicyConfiguration setSize(long size) {
this.size = size;
@@ -89,14 +131,20 @@ public final class MemoryPolicyConfiguration implements Serializable {
}
/**
- * @return Path for memory mapped file (won't be created if not configured).
+ * A path to the memory-mapped file the memory region defined by this memory policy will be mapped to. Having
+ * the path set, allows relying on swapping capabilities of an underlying operating system for the memory region.
+ *
+ * @return A path to the memory-mapped file or {@code null} if this feature is not used for the memory region defined
+ * by this memory policy.
*/
public String getSwapFilePath() {
return swapFilePath;
}
/**
- * @param swapFilePath Path for memory mapped file (won't be created if not configured)..
+ * Sets a path to the memory-mapped file.
+ *
+ * @param swapFilePath A Path to the memory mapped file.
*/
public MemoryPolicyConfiguration setSwapFilePath(String swapFilePath) {
this.swapFilePath = swapFilePath;
@@ -105,14 +153,18 @@ public final class MemoryPolicyConfiguration implements Serializable {
}
/**
- * Gets data page eviction mode.
+ * Gets memory pages eviction mode. If {@link DataPageEvictionMode#DISABLED} is used (default) then an out of
+ * memory exception will be thrown if the memory region usage, defined by this memory policy, goes beyond its
+ * capacity which is {@link #getSize()}.
+ *
+ * @return Memory pages eviction algorithm. {@link DataPageEvictionMode#DISABLED} used by default.
*/
public DataPageEvictionMode getPageEvictionMode() {
return pageEvictionMode;
}
/**
- * Sets data page eviction mode.
+ * Sets memory pages eviction mode.
*
* @param evictionMode Eviction mode.
*/
@@ -123,16 +175,17 @@ public final class MemoryPolicyConfiguration implements Serializable {
}
/**
- * Gets data page eviction threshold.
+ * Gets 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.
*
- * @return Data page eviction threshold.
+ * @return Memory pages eviction threshold.
*/
public double getEvictionThreshold() {
return evictionThreshold;
}
/**
- * Sets data page eviction threshold.
+ * Sets memory pages eviction threshold.
*
* @param evictionThreshold Eviction threshold.
*/
@@ -143,6 +196,7 @@ public final class MemoryPolicyConfiguration implements Serializable {
}
/**
+ * TODO: document clearly
* Gets empty pages pool size.
*/
public int getEmptyPagesPoolSize() {