[jbosscache-commits] JBoss Cache SVN: r6987 - core/trunk/src/main/docbook/userguide/en/modules.

Author: manik.surtani(a)jboss.com Date: 2008-10-20 17:43:47 -0400 (Mon, 20 Oct 2008) New Revision: 6987 Modified: core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml Log: More doc updates Modified: core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml =================================================================== --- core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml 2008-10-20 13:46:58 UTC (rev 6986) +++ core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml 2008-10-20 21:43:47 UTC (rev 6987) @@ -1,141 +1,116 @@ <chapter id="eviction_policies"> - <title>Eviction Policies</title> + <title>Eviction</title> <para> - Eviction policies control JBoss Cache's memory management by managing how many nodes are allowed to be stored in - memory and their life spans. Memory constraints on servers mean cache cannot grow indefinitely, so policies - need to be in place to restrict the size of the cache. Eviction policies are most often used alongside - <link linkend="cache_loaders">cache loaders</link> - <link linkend="cache_loaders">cache loaders</link> - . + Eviction controls JBoss Cache's memory management by restricting how many nodes are allowed to be stored in + memory, and for how long. Memory constraints on servers mean caches cannot grow indefinitely, so eviction + needs to occur to prevent out of memory errors. Eviction is most often used alongside <link linkend="cache_loaders">cache loaders</link>. </para> - <section> - <title>Configuring Eviction Policies</title> + <section id="eviction.design"> + <title>Design</title> + <para> + Eviction in JBoss Cache is designed around four concepts: + <itemizedlist> + <listitem>1. Collecting statistics</listitem> + <listitem>2. Determining which nodes to evict</listitem> + <listitem>3. How nodes are evicted</listitem> + <listitem>4. Eviction threads.</listitem> + </itemizedlist> + In addition, Regions play a key role in eviction, as eviction is always configured on a per-region basis so that + different subtrees in the cache can have different eviction characteristics. + </para> + <section> - <title>Basic Configuration</title> + <title>Collecting Statistics</title> <para> - The basic eviction policy configuration element looks like: + This is done on the caller's thread whenever anyone interacts with the cache. If eviction is enabled, an + <literal>EvictionInterceptor</literal> is added to the interceptor chain and events are recorded in an + event queue. Events are denoted by the <literal>EvictionEvent</literal> class. Event queues are held on + specific Regions so each region has its own event queue. </para> - <programlisting role="XML"><![CDATA[ - ... - - <attribute name="EvictionConfig"> - <config> - <attribute name="wakeUpIntervalSeconds">3</attribute> - - <!-- This defaults to 200000 if not specified --> - <attribute name="eventQueueSize">100000</attribute> - - <!-- Name of the DEFAULT eviction policy class. --> - <attribute name="policyClass">org.jboss.cache.eviction.LRUPolicy</attribute> - - <!-- Cache wide default --> - <region name="/_default_"> - <attribute name="maxNodes">100</attribute> - </region> - - <!-- override policy used for this region --> - <region name="/org/jboss/data" policyClass="org.jboss.cache.eviction.LRUPolicy"> - <attribute name="maxNodes">250</attribute> - <attribute name="minTimeToLiveSeconds">10</attribute> - </region> - - <!-- We expect a lot of events for this region, - so override the default event queue size --> - <region name="/org/jboss/test/data" eventQueueSize="500000"> - <attribute name="maxNodes">60000</attribute> - </region> - - </config> - </attribute> - - ... -]]></programlisting> <para> - <itemizedlist> - <listitem> - <literal>wakeUpIntervalSeconds</literal> - - this required parameter defines how often the eviction thread runs - </listitem> - <listitem> - <literal>eventQueueSize</literal> - - this optional parameter defines the size of the queue which holds eviction events. If your eviction - thread does not run often enough, you may need to increase this. This can be overridden on a - per-region basis. - </listitem> - <listitem> - <literal>policyClass</literal> - - this is required, unless you set individual policyClass attributes on each and every region. This - defines the eviction policy to use if one is not defined for a region. - </listitem> - </itemizedlist> + This aspect of eviction is not configurable, except that the <literal>EvictionInterceptor</literal> is either + added to the interceptor chain or not, depending on whether eviction is enabled. + </para> + </section> + <section> + <title>Determining Which Nodes to Evict</title> + <para> + An <literal>EvictionAlgorithm</literal> implementation processes the eviction queue to decide which nodes to + evict. JBoss Cache ships with a number of implementations, including <literal>FIFOAlgorithm</literal>, + <literal>LRUAlgorithm</literal>, <literal>LFUAlgorithm</literal>, etc. Each implementation has a corresponding + <literal>EvictionAlgorithmConfig</literal> implementation with configuration details for the algorithm. </para> + <para> + Custom <literal>EvictionAlgorithm</literal> implementations can be provided by implementing the interface + or extending one of the provided implementations. + </para> + <para> + Algorithms are executed by calling its <literal>process()</literal> method and passing in the event queue to + process. This is typically done by calling <literal>Region.processEvictionQueues()</literal>, which will + locate the Algorithm assigned to the region. + </para> </section> + <section> - <title>Eviction Regions</title> + <title>How Nodes are Evicted</title> <para> - The concept of regions and the - <literal>Region</literal> - class were - <link linkend="architecture.regions">visited earlier</link> - when talking about marshalling. Regions also have another use, in that they are used to define the eviction - policy used within the region. In addition to using a region-specific configuration, you can also configure - a default, cache-wide eviction policy for nodes that do not fall into predefined regions or if you do not - wish to define specific regions. It is important to note that when defining regions using the configuration - XML file, all elements of the - <literal>Fqn</literal> - that defines the region are - <literal>java.lang.String</literal> - objects. + Once the <literal>EvictionAlgorithm</literal> decides which nodes to evict, it uses an implementation of + <literal>EvictionActionPolicy</literal> to determine how to evict nodes. This is configurable on a per-region + basis, and defaults to <literal>DefaultEvictionActionPolicy</literal>, which invokes <literal>Cache.evict()</literal> + for each node that needs to be evicted. </para> <para> - Looking at the eviction configuration snippet above, we see that a default region, - <literal>_default_</literal> - , holds attributes - which apply to nodes that do not fall into any of the other regions defined. + JBoss Cache also ships with <literal>RemoveOnEvictActionPolicy</literal>, which calls <literal>Cache.removeNode()</literal> + for each node that needs to be evicted, instead of <literal>Cache.evict()</literal>. </para> <para> - For each region, you can define parameters which affect how the policy which applies to the region chooses - to evict nodes. - In the example above, the - <literal>LRUPolicy</literal> - allows a - <literal>maxNodes</literal> - parameter which defines - how many nodes can exist in the region before it chooses to start evicting nodes. See the javadocs for each - policy for a list of allowed parameters. It also defines a - <literal>minTimeToLiveSeconds</literal> - parameter, - which defines a minimum time a node must exist in memory before being considered for eviction. + Custom <literal>EvictionActionPolicy</literal> implementations can be used as well. </para> + </section> - <section> - <title>Overlapping Eviction Regions</title> + <section> + <title>Eviction threads</title> + <para> + By default, a single cache-wide eviction thread is used to periodically iterate through registered regions + and call <literal>Region.processEvictionQueues()</literal> on each region. The frequency with which this + thread runs can be configured using the <literal>wakeUpInterval</literal> attribute in the <literal>eviction</literal> + configuration element, and defaults to 5000 milliseconds if not specified. + </para> + <para> + The eviction thread can be disabled by setting <literal>wakeUpInterval</literal> to <literal>0</literal>. + This can be useful if you have your own periodic maintenance thread running and would like to iterate through + regions and call <literal>Region.processEvictionQueues()</literal> yourself. + </para> + </section> + </section> + <section id="regions"> + <title>Eviction Regions</title> + <para> + The concept of regions and the <literal>Region</literal> class were + <link linkend="architecture.regions">visited earlier</link> when talking about marshalling. Regions are also + used to define the eviction behavior for nodes within that region. In addition to using a region-specific + configuration, you can also configure default, cache-wide eviction behavior for nodes that do not fall into + predefined regions or if you do not wish to define specific regions. It is important to note that when + defining regions using the configuration XML file, all elements of the <literal>Fqn</literal> that defines + the region are <literal>String</literal> objects. + </para> + <para> + For each region, you can define eviction parameters. + </para> + <para>It's possible to define regions that overlap. In other words, one region can be defined for - <emphasis>/a/b/c</emphasis> - , and another - defined for - <emphasis>/a/b/c/d</emphasis> - (which is just the - <emphasis>d</emphasis> - subtree of the - <emphasis>/a/b/c</emphasis> - sub-tree). + <literal>/a/b/c</literal>, and another defined for <literal>/a/b/c/d</literal> (which is just the + <emphasis>d</emphasis> subtree of the <literal>/a/b/c</literal> sub-tree). The algorithm, in order to handle scenarios like this consistently, will always choose the first region - it encounters. - In this way, if the algorithm needed to decide how to handle - <emphasis>/a/b/c/d/e</emphasis> - , it would start from there and work + it encounters. In this way, if the algorithm needed to decide how to handle node + <literal>/a/b/c/d/e</literal>, it would start from there and work its way up the tree until it hits the first defined region - in this case - <emphasis>/a/b/c/d</emphasis> - . + <literal>/a/b/c/d</literal>. </para> - </section> - - </section> <section> <title>Resident Nodes</title> <para> @@ -190,7 +165,52 @@ as non-resident again and let them be considered for eviction.. </para> </section> + </section> + <section> + <title>Configuring Eviction</title> + <section id="eviction.basic_cfg"> + <title>Basic Configuration</title> + <para> + The basic eviction configuration element looks like: + </para> + <programlisting role="XML"><![CDATA[ + ... + <eviction wakeUpInterval="500" eventQueueSize="100000"> + <default algorithmClass="org.jboss.cache.eviction.LRUAlgorithm"> + <attribute name="maxNodes">5000</attribute> + <attribute name="timeToLive">1000</attribute> + </default> + </eviction> + ... +]]></programlisting> + <para> + <itemizedlist> + <listitem> + <literal>wakeUpInterval</literal> + - this required parameter defines how often the eviction thread runs, in milliseconds. + </listitem> + <listitem> + <literal>eventQueueSize</literal> + - this optional parameter defines the size of the bounded queue which holds eviction events. If your + eviction thread does not run often enough, you may find that the event queue fills up. It may then be + necessary to get your eviction thread to run more frequently, or increase the size of your event queue. + This configuration is just the <emphasis>default</emphasis> event queue size, and can be overridden + in specific eviction regions. If not specified, this defaults to <literal>200000</literal>. + </listitem> + <listitem> + <literal>algorithmClass</literal> + - this is required, unless you set individual <literal>algorithmClass</literal> attributes on each and every region. This + defines the default eviction algorithm to use if one is not defined for a region. + </listitem> + <listitem> + Algorithm configuration attributes - these are specific to the algorithm specified in <literal>algorithmClass</literal>. + See the section specific to the algorithm you are interested in for details. + </listitem> + </itemizedlist> + </para> + </section> + <section> <title>Programmatic Configuration</title> <para> @@ -199,8 +219,7 @@ object entails the use of the <literal>org.jboss.cache.config.EvictionConfig</literal> bean, which is passed into - <literal>Configuration.setEvictionConfig()</literal> - . See the + <literal>Configuration.setEvictionConfig()</literal>. See the <link linkend="configuration">chapter on Configuration</link> for more on building a <literal>Configuration</literal> @@ -210,37 +229,43 @@ <para> The use of simple POJO beans to represent all elements in a cache's configuration also makes it fairly easy to programatically - add eviction regions after the cache is started . For example, + add eviction regions after the cache is started. For example, assume we had an existing cache configured via XML with the EvictionConfig element shown above. Now at runtime we wished to add a new eviction region named "/org/jboss/fifo", using - <literal>LRUPolicy</literal> + <literal>LRUAlgorithm</literal> but a different number of - <literal>maxNodes</literal> - : + <literal>maxNodes</literal>: </para> <programlisting role="JAVA"><![CDATA[ Fqn fqn = Fqn.fromString("/org/jboss/fifo"); // Create a configuration for an LRUPolicy - LRUConfiguration lruc = new LRUConfiguration(); + LRUAlgorithmConfig lruc = new LRUAlgorithmConfig(); lruc.setMaxNodes(10000); + // Create an eviction region config + EvictionRegionConfig erc = new EvictionRegionConfig(fqn, lruc); + // Create the region and set the config Region region = cache.getRegion(fqn, true); - region.setEvictionPolicy(lruc); + region.setEvictionRegionConfig(erc); ]]></programlisting> </section> </section> - <section> + <section id="eviction.shipped"> <title>Shipped Eviction Policies</title> + + This section details the different algorithms shipped with JBoss Cache, and the various configuration parameters + used for each algorithm. + <section> - <title>LRUPolicy - Least Recently Used</title> + <title>LRUAlgorithm - Least Recently Used</title> <para> - <literal>org.jboss.cache.eviction.LRUPolicy</literal> + <literal>org.jboss.cache.eviction.LRUAlgorithm</literal> controls both the node lifetime and age. This policy guarantees a constant order ( <literal>O (1)</literal> ) for @@ -251,22 +276,22 @@ <itemizedlist> <listitem> <literal>maxNodes</literal> - - This is the maximum number of nodes allowed in this region. 0 denotes no limit. + - This is the maximum number of nodes allowed in this region. 0 denotes immediate expiry, -1 denotes no limit. </listitem> <listitem> - <literal>timeToLiveSeconds</literal> - - The amount of time a node is not written to or read (in seconds) before the node is swept away. 0 - denotes no limit. + <literal>timeToLive</literal> + - The amount of time a node is not written to or read (in milliseconds) before the node is swept away. 0 + denotes immediate expiry, -1 denotes no limit. </listitem> <listitem> - <literal>maxAgeSeconds</literal> - - Lifespan of a node (in seconds) regardless of idle time before the node is swept away. 0 denotes no - limit. + <literal>maxAge</literal> + - Lifespan of a node (in milliseconds) regardless of idle time before the node is swept away. 0 + denotes immediate expiry, -1 denotes no limit. </listitem> <listitem> - <literal>minTimeToLiveSeconds</literal> + <literal>minTimeToLive</literal> - the minimum amount of time a node must be allowed to live after being accessed before it is allowed to be considered for eviction. 0 denotes that this feature is disabled, which is the default value. </listitem> @@ -274,10 +299,10 @@ </section> <section> - <title>FIFOPolicy - First In, First Out</title> + <title>FIFOAlgorithm - First In, First Out</title> <para> - <literal>org.jboss.cache.eviction.FIFOPolicy</literal> + <literal>org.jboss.cache.eviction.FIFOAlgorithm</literal> controls the eviction in a proper first in first out order. This policy guarantees a constant order ( <literal>O (1)</literal> @@ -288,10 +313,10 @@ <itemizedlist> <listitem> <literal>maxNodes</literal> - - This is the maximum number of nodes allowed in this region. 0 denotes no limit. + - This is the maximum number of nodes allowed in this region. 0 denotes immediate expiry, -1 denotes no limit. </listitem> <listitem> - <literal>minTimeToLiveSeconds</literal> + <literal>minTimeToLive</literal> - the minimum amount of time a node must be allowed to live after being accessed before it is allowed to be considered for eviction. 0 denotes that this feature is disabled, which is the default value. </listitem> @@ -300,10 +325,10 @@ <section> - <title>MRUPolicy - Most Recently Used</title> + <title>MRUAlgorithm - Most Recently Used</title> <para> - <literal>org.jboss.cache.eviction.MRUPolicy</literal> + <literal>org.jboss.cache.eviction.MRUAlgorithm</literal> controls the eviction in based on most recently used algorithm. The most recently used nodes will be the first to evict with this policy. This policy @@ -316,10 +341,11 @@ <itemizedlist> <listitem> <literal>maxNodes</literal> - - This is the maximum number of nodes allowed in this region. 0 denotes no limit. + - This is the maximum number of nodes allowed in this region. 0 + denotes immediate expiry, -1 denotes no limit. </listitem> <listitem> - <literal>minTimeToLiveSeconds</literal> + <literal>minTimeToLive</literal> - the minimum amount of time a node must be allowed to live after being accessed before it is allowed to be considered for eviction. 0 denotes that this feature is disabled, which is the default value. </listitem> @@ -327,10 +353,10 @@ </section> <section> - <title>LFUPolicy - Least Frequently Used</title> + <title>LFUAlgorithm - Least Frequently Used</title> <para> - <literal>org.jboss.cache.eviction.LFUPolicy</literal> + <literal>org.jboss.cache.eviction.LFUAlgorithm</literal> controls the eviction in based on least frequently used algorithm. The least frequently used nodes will be the first to evict with this policy. Node @@ -356,7 +382,8 @@ <itemizedlist> <listitem> <literal>maxNodes</literal> - - This is the maximum number of nodes allowed in this region. 0 denotes no limit. + - This is the maximum number of nodes allowed in this region. 0 + denotes immediate expiry, -1 denotes no limit. </listitem> <listitem> <literal>minNodes</literal> @@ -368,7 +395,7 @@ algorithm. </listitem> <listitem> - <literal>minTimeToLiveSeconds</literal> + <literal>minTimeToLive</literal> - the minimum amount of time a node must be allowed to live after being accessed before it is allowed to be considered for eviction. 0 denotes that this feature is disabled, which is the default value. </listitem> @@ -377,10 +404,10 @@ </section> <section> - <title>ExpirationPolicy</title> + <title>ExpirationAlgorithm</title> <para> - <literal>org.jboss.cache.eviction.ExpirationPolicy</literal> + <literal>org.jboss.cache.eviction.ExpirationAlgorithm</literal> is a policy that evicts nodes based on an absolute expiration time. The expiration time is indicated using the @@ -418,7 +445,8 @@ </listitem> <listitem> <literal>maxNodes</literal> - - This is the maximum number of nodes allowed in this region. 0 denotes no limit. + - This is the maximum number of nodes allowed in this region. 0 + denotes immediate expiry, -1 denotes no limit. </listitem> </itemizedlist> @@ -449,10 +477,10 @@ </para> </section> <section> - <title>ElementSizePolicy - Eviction based on number of key/value pairs in a node</title> + <title>ElementSizeAlgorithm - Eviction based on number of key/value pairs in a node</title> <para> - <literal>org.jboss.cache.eviction.ElementSizePolicy</literal> + <literal>org.jboss.cache.eviction.ElementSizeAlgorithm</literal> controls the eviction in based on the number of key/value pairs in the node. Nodes The most recently used nodes will be the first to evict with this policy. It has the following configuration parameters: @@ -461,159 +489,20 @@ <itemizedlist> <listitem> <literal>maxNodes</literal> - - This is the maximum number of nodes allowed in this region. 0 denotes no limit. + - This is the maximum number of nodes allowed in this region. 0 + denotes immediate expiry, -1 denotes no limit. </listitem> <listitem> <literal>maxElementsPerNode</literal> - - This is the trigger number of attributes per node for the node to be selected for eviction. 0 denotes - no limit. + - This is the trigger number of attributes per node for the node to be selected for eviction. 0 + denotes immediate expiry, -1 denotes no limit. </listitem> <listitem> - <literal>minTimeToLiveSeconds</literal> + <literal>minTimeToLive</literal> - the minimum amount of time a node must be allowed to live after being accessed before it is allowed to be considered for eviction. 0 denotes that this feature is disabled, which is the default value. </listitem> </itemizedlist> </section> </section> - - <section> - <title>Writing Your Own Eviction Policies</title> - <section> - <title>Eviction Policy Plugin Design</title> - - <para>The design of the JBoss Cache eviction policy framework is based - on an - <literal>EvictionInterceptor</literal> - to handle cache events and relay them back to the eviction - policies. During the cache start up, an - <literal>EvictionInterceptor</literal> - will be added to the cache - interceptor stack if the eviction policy is specified. - Then whenever a node is added, removed, evicted, or visited, the - <literal>EvictionInterceptor</literal> - will maintain state statistics and - information will be relayed to each individual eviction region. - </para> - - <para> - There is a single eviction thread (timer) that will run at a - configured interval. This thread will make calls into each of the policy - providers and inform it of any aggregated adds, - removes and visits (gets) events to the cache during the configured interval. - The eviction thread is responsible for kicking off the eviction policy - processing (a single pass) for each configured eviction cache - region. - </para> - </section> - - <section> - <title>Interfaces to implement</title> - <para>In order to implement an eviction policy, the following interfaces - must be implemented: - <itemizedlist> - <listitem> - <literal>org.jboss.cache.eviction.EvictionPolicy</literal> - </listitem> - <listitem> - <literal>org.jboss.cache.eviction.EvictionAlgorithm</literal> - </listitem> - <listitem> - <literal>org.jboss.cache.eviction.EvictionQueue</literal> - </listitem> - <listitem> - <literal>org.jboss.cache.config.EvictionPolicyConfig</literal> - </listitem> - </itemizedlist> - When compounded - together, each of these interface implementations define all the - underlying mechanics necessary for a complete eviction policy - implementation. - </para> - - <para> - <emphasis>Note that:</emphasis> - </para> - - <itemizedlist> - <listitem> - <para>The - <literal>EvictionPolicyConfig</literal> - implementation - should maintain - getter and setter methods for whatever configuration properties - the policy supports (e.g. for - <literal>LRUConfiguration</literal> - among others there is a - <literal>int getMaxNodes()</literal> - and a - <literal>setMaxNodes(int)</literal> - ). When the "EvictionConfig" section of an XML configuration - is parsed, these properties will be set by reflection. - </para> - </listitem> - </itemizedlist> - - <para>Alternatively, the implementation of a new eviction policy - provider can be simplified by extending - <literal>BaseEvictionPolicy</literal> - and - <literal>BaseEvictionAlgorithm</literal> - . Or for properly sorted EvictionAlgorithms (sorted - in eviction order - see - <literal>LFUAlgorithm</literal> - ) extending - <literal>BaseSortedEvictionAlgorithm</literal> - and implementing - <literal>SortedEvictionQueue</literal> - takes - care of most of the common functionality available in a set of eviction - policy provider classes - </para> - - - <para> - <emphasis>Note that:</emphasis> - </para> - - <itemizedlist> - <listitem> - <para>The - <literal>BaseEvictionAlgorithm</literal> - class maintains a processing - structure. It will process the ADD, REMOVE, and VISIT events queued - by the region first. It also maintains an collection of - items that were not properly evicted during the last go around - because of held locks. That list is pruned. Finally, the - EvictionQueue itself is pruned for entries that should be evicted - based upon the configured eviction rules for the region. - </para> - </listitem> - <listitem> - <para>The - <literal>BaseSortedEvictionAlgorithm</literal> - class will maintain a boolean - through the algorithm processing that will determine if any new - nodes were added or visited. This allows the Algorithm to determine - whether to resort the eviction queue items (in first to evict order) - or to skip the potentially expensive sorting if there have been no - changes to the cache in this region. - </para> - </listitem> - <listitem> - <para>The - <literal>SortedEvictionQueue</literal> - interface defines the contract used by - the - <literal>BaseSortedEvictionAlgorithm</literal> - abstract class that is used to - resort the underlying queue. Again, the queue sorting should be - sorted in first to evict order. The first entry in the list should - evict before the last entry in the queue. The last entry in the - queue should be the last entry that will require eviction. - </para> - </listitem> - </itemizedlist> - </section> - </section> </chapter> \ No newline at end of file