ignite-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From agoncha...@apache.org
Subject [37/50] [abbrv] ignite git commit: Fixed memory policies example and improved page memory related documentation.
Date Tue, 18 Apr 2017 09:00:49 GMT
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 <dmagda@gridgain.com>
Authored: Mon Apr 17 17:27:14 2017 -0700
Committer: Denis Magda <dmagda@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() {


Mime
View raw message