Chapter 9. Eviction Policies

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 cache loaders cache loaders .

9.1. Configuring Eviction Policies

9.1.1. Basic Configuration

The basic eviction policy configuration element looks like:




   ...



   <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>



   ...

wakeUpIntervalSeconds - this required parameter defines how often the eviction thread runs
eventQueueSize - 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.
policyClass - 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.

9.1.2. Eviction Regions

The concept of regions and the Region class were visited earlier 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 Fqn that defines the region are java.lang.String objects.

Looking at the eviction configuration snippet above, we see that a default region, _default_ , holds attributes which apply to nodes that do not fall into any of the other regions defined.

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 LRUPolicy allows a maxNodes 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 minTimeToLiveSeconds parameter, which defines a minimum time a node must exist in memory before being considered for eviction.

9.1.2.1. Overlapping Eviction Regions

It's possible to define regions that overlap. In other words, one region can be defined for /a/b/c , and another defined for /a/b/c/d (which is just the d subtree of the /a/b/c 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 /a/b/c/d/e , it would start from there and work its way up the tree until it hits the first defined region - in this case /a/b/c/d .

9.1.3. Resident Nodes

Nodes marked as resident (using Node.setResident() API) will be ignored by the eviction policies both when checking whether to trigger the eviction and when proceeding with the actual eviction of nodes. E.g. if a region is configured to have a maximum of 10 nodes, resident nodes won't be counted when deciding whether to evict nodes in that region. In addition, resident nodes will not be considered for eviction when the region's eviction threshold is reached.

In order to mark a node as resident the Node.setResident() API should be used. By default, the newly created nodes are not resident. The resident attribute of a node is neither replicated, persisted nor transaction-aware.

A sample use case for resident nodes would be ensuring "path" nodes don't add "noise" to an eviction policy. E.g.,:



...

   Map lotsOfData = generateData();

   cache.put("/a/b/c", lotsOfData);

   cache.getRoot().getChild("/a").setResident(true);

   cache.getRoot().getChild("/a/b").setResident(true);

...

In this example, the nodes /a and /a/b are paths which exist solely to support the existence of node /a/b/c and don't hold any data themselves. As such, they are good candidates for being marked as resident. This would lead to better memory management as no eviction events would be generated when accessing /a and/a/b.

N.B. when adding attributes to a resident node, e.g. cache.put("/a", "k", "v") in the above example, it would make sense to mark the nodes as non-resident again and let them be considered for eviction..

9.1.4. Programmatic Configuration

Configuring eviction using the Configuration object entails the use of the org.jboss.cache.config.EvictionConfig bean, which is passed into Configuration.setEvictionConfig() . See the chapter on Configuration for more on building a Configuration programatically.

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, 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 LRUPolicy but a different number of maxNodes :



   Fqn fqn = Fqn.fromString("/org/jboss/fifo");


   // Create a configuration for an LRUPolicy

   LRUConfiguration lruc = new LRUConfiguration();

   lruc.setMaxNodes(10000);


   // Create the region and set the config

   Region region = cache.getRegion(fqn, true);

   region.setEvictionPolicy(lruc);

9.2. Shipped Eviction Policies



   Cache cache = DefaultCacheFactory.createCache();

   Fqn fqn1 = Fqn.fromString("/node/1");

   Long future = new Long(System.currentTimeMillis() + 2000);


   // sets the expiry time for a node

   cache.getRoot().addChild(fqn1).put(ExpirationConfiguration.EXPIRATION_KEY, future);


   assertTrue(cache.getRoot().hasChild(fqn1));

   Thread.sleep(5000);


   // after 5 seconds, expiration completes

   assertFalse(cache.getRoot().hasChild(fqn1));