[jboss-cvs] JBoss Messaging SVN: r6792 - in trunk: examples/jms/no-consumer-buffering and 1 other directory.

[jboss-cvs-commits at lists.jboss.org]

Author: jmesnil
Date: 2009-05-14 08:55:32 -0400 (Thu, 14 May 2009)
New Revision: 6792

Modified:
   trunk/docs/user-manual/en/modules/consumer-buffering.xml
   trunk/examples/jms/no-consumer-buffering/readme.html
Log:
user manual

* consumer buffering chapter

Modified: trunk/docs/user-manual/en/modules/consumer-buffering.xml
===================================================================
--- trunk/docs/user-manual/en/modules/consumer-buffering.xml	2009-05-14 12:53:47 UTC (rev 6791)
+++ trunk/docs/user-manual/en/modules/consumer-buffering.xml	2009-05-14 12:55:32 UTC (rev 6792)
@@ -1,14 +1,63 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <chapter id="consumer-buffering">
-    <title>Consumer Buffering</title>
-    <para>blah</para>
+   <title>Consumer Buffering</title>
+   <para>By default, JBoss Messaging consumers buffer messages from the server 
+      in a client side buffer before the client receive them.       
+      This improves performance: otherwise every time the client called <literal>receive()</literal>
+      or processed the last message in a <literal>MessageListener</literal>, JBoss Messaging would 
+      have to go the server to request the next message. In turn, this message would then get sent 
+      to the client side, if one was available.</para>
+    <para>A network round trip would be involved for <emphasis>every</emphasis> message and 
+    considerably reduce performance.</para>
+    <para>To prevent this, JBoss Messaging pre-fetches messages into a buffer on each consumer.
+       The total maximum size of messages (in bytes) that will be buffered on each consumer is 
+       determined by the <literal>consumer-window-size</literal> parameter on the connection factory
+       setting in <literal>jbm-jms.xml</literal>:</para>
+    <programlisting>
+&lt;connection-factory name="ConnectionFactory"&gt;
+   &lt;connector-ref connector-name="netty-connector"/&gt;
+   &lt;entries&gt;
+      &lt;entry name="ConnectionFactory"/&gt;       
+   &lt;/entries&gt;
+
+   &lt;!-- Set the consumer window size to 0 to have *no* buffer on the client side --&gt;
+   &lt;consumer-window-size&gt;0&lt;/consumer-window-size&gt;
+&lt;/connection-factory&gt;
+    </programlisting>
+    <para>By default, the <literal>consumer-window-size</literal> is set to 1 Mib (1024 * 1024 bytes).</para>
+    
+    <para>Setting the consumer window size can considerably improve performance depending
+       on the messaging use case. As an example, let's consider the two extremes:
+    </para>
+    <itemizedlist>
+      <listitem><para><emphasis>Fast consumers</emphasis> can process messages as fast as they
+      consume them (or even faster)</para></listitem>
+      <listitem><para><emphasis>Slow consumers</emphasis> takes significant time to process each
+      message and it is desirable to prevent buffering messages on the client side so that they
+      can be delivered to another consumer instead
+      </para></listitem>
+    </itemizedlist>
+    <para>Most of the consumers can not be clearly identified as fast or slow consumers but are in-between.
+       In that case, setting the value of <literal>consumer-window-size</literal> to optimize performance
+       depends on the messaging use case and requires benchmarks to find the optimal value.</para>
+    
     <section>
         <title>Fast consumers</title>
-        <para></para>
+        <para>To allow fast consumers, set the <literal>consumer-window-size</literal> to -1.
+        This will allow <emphasis>unbounded</emphasis> message buffering on the client side.</para>
+        <para>Use this setting with caution: it can overflow the client memory if the consumer
+           is not able to process messages as fast as it receives them.</para>
     </section>
     <section>
         <title>Slow consumers</title>
-        <para></para>
+        <para>To allow slow consumers, set the <literal>consumer-window-size</literal> to 0 (for no buffer at all).
+        This will prevent from buffering messages on the client side. Messages will remain on the server side
+        ready to be consumed by other consumers.</para>
     </section>
-   
+    <section>
+       <title>Example</title>
+       <para>The <ulink url="../../../../examples/jms/no-consumer-buffering/readme.html"><literal>no-consumer-buffering</literal> example</ulink> shows
+          how to configure JBoss Messaging to prevent consumer buffering when dealing with slow
+          consumers.</para>
+    </section>
 </chapter>

Modified: trunk/examples/jms/no-consumer-buffering/readme.html
===================================================================
--- trunk/examples/jms/no-consumer-buffering/readme.html	2009-05-14 12:53:47 UTC (rev 6791)
+++ trunk/examples/jms/no-consumer-buffering/readme.html	2009-05-14 12:55:32 UTC (rev 6792)
@@ -172,9 +172,13 @@
               }
            }</code>
         </pre>
+     </ol>
 
+     <h2>More information</h2>
+     
+     <ul>
+         <li>User Manual's <a href="../../../docs/user-manual/en/html_single/index.html#consumer-buffering">Consumer Buffering chapter</a></li>
+     </ul>
 
-
-     </ol>
   </body>
 </html>
\ No newline at end of file