[jbosscache-commits] JBoss Cache SVN: r4748 - in core/trunk/src/main/docbook/userguide/en: modules and 1 other directory.

[jbosscache-commits at lists.jboss.org]

Author: manik.surtani at jboss.com
Date: 2007-11-13 12:19:28 -0500 (Tue, 13 Nov 2007)
New Revision: 4748

Modified:
   core/trunk/src/main/docbook/userguide/en/master.xml
   core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml
Log:
Updated docs

Modified: core/trunk/src/main/docbook/userguide/en/master.xml
===================================================================
--- core/trunk/src/main/docbook/userguide/en/master.xml	2007-11-13 14:38:17 UTC (rev 4747)
+++ core/trunk/src/main/docbook/userguide/en/master.xml	2007-11-13 17:19:28 UTC (rev 4748)
@@ -61,11 +61,11 @@
          <email>dhuang at jboss.org</email>
       </author>
 
-      <!--<author>-->
-      <!--<firstname>Joseph</firstname>-->
-      <!--<surname>Marques</surname>-->
-      <!--<email>jmarques at redhat.com</email>-->
-      <!--</author>-->
+      <author>
+         <firstname>Mircea</firstname>
+         <surname>Markus</surname>
+         <email>mircea.markus at jboss.com</email>
+      </author>
 
 
       <!-- copyright info -->

Modified: core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml
===================================================================
--- core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml	2007-11-13 14:38:17 UTC (rev 4747)
+++ core/trunk/src/main/docbook/userguide/en/modules/eviction_policies.xml	2007-11-13 17:19:28 UTC (rev 4748)
@@ -139,33 +139,36 @@
       <section>
          <title>Resident Nodes</title>
          <para>
-             Nodes marked resident 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 the eviction policy for a
-             region is "keep LRU 10 nodes" - the resident nodes won't be counted within those 10 nodes,
-             and also won't be evicted when the threshold is reached. In order to mark a node as resident the
-             <literal>Node.setResident</literal> should be used. By default, the newly added nodes are not resident.
-             The <literal>resident</literal> attribute of a node is neither replicated nor transactionable.
+             Nodes marked as resident (using <literal>Node.setResident()</literal> 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.
          </para>
          <para>
-            A good use case for this would be marking the internally build nodes as resident. E.g.
+             In order to mark a node as resident the <literal>Node.setResident()</literal> API should be used. By default, the newly created nodes are not resident.
+             The <literal>resident</literal> attribute of a node is neither replicated, persisted nor transaction-aware.
+         </para>
+         <para>
+            A sample use case for resident nodes would be ensuring "path" nodes don't add "noise" to an eviction policy. E.g.
             <programlisting>
                <![CDATA[
                ...
-
-                         cache.put("/a/b/c", "k", "v");
+                         Map lotsOfData = generateData();
+                         cache.put("/a/b/c", lotsOfData);
                          cache.getRoot().getChild("/a").setResident(true);
                          cache.getRoot().getChild("/a/b").setResident(true);
                ...
                ]]>
             </programlisting>
-            In this example, the nodes <emphasis>/a</emphasis> and <emphasis>/a/b</emphasis> are internally build for
-            supporting the existence of node <emphasis>/a/b/c</emphasis>. If so, they are good candidates for being
-            marked as resident nodes: this would lead into performance improvements as no eviction events would be
-            generated when accessing <emphasis>/a</emphasis> and <emphasis>/a/b</emphasis>. N.B. when adding attributes
-            to such a node, e.g. <emphasis>cache.put("/a", "k", "v")</emphasis> it would make sense to mark the nodes
-            as non resident again and let them be considered for eviction.
+            In this example, the nodes <literal>/a</literal> and <literal>/a/b</literal> are paths which exist solely to
+            support the existence of node <literal>/a/b/c</literal> 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 <literal>/a</literal> and <literal>/a/b</literal>.
          </para>
-
+         <para>
+            N.B. when adding attributes to a resident node, e.g. <literal>cache.put("/a", "k", "v")</literal> in the above example, it would make sense to mark the nodes
+            as non-resident again and let them be considered for eviction..
+         </para>
       </section>
 
       <section>