[jboss-cvs] JBoss Messaging SVN: r6837 - trunk/docs/user-manual/en/modules.

jboss-cvs-commits at lists.jboss.org jboss-cvs-commits at lists.jboss.org
Mon May 18 07:14:20 EDT 2009


Author: ataylor
Date: 2009-05-18 07:14:20 -0400 (Mon, 18 May 2009)
New Revision: 6837

Modified:
   trunk/docs/user-manual/en/modules/flow-control.xml
Log:
flow control docs

Modified: trunk/docs/user-manual/en/modules/flow-control.xml
===================================================================
--- trunk/docs/user-manual/en/modules/flow-control.xml	2009-05-18 11:06:13 UTC (rev 6836)
+++ trunk/docs/user-manual/en/modules/flow-control.xml	2009-05-18 11:14:20 UTC (rev 6837)
@@ -1,77 +1,91 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <chapter id="flow-control">
    <title>Flow Control</title>
-   <para>blah</para>
+   <para>JBoss Messaging allows the user to restrict how fast messages are delivered between both
+      client and server and also between server and client.</para>
    <section>
       <title>Consumer Flow Control</title>
-      <para>Consumer flow can be controlled using window size or rate.</para>
+      <para>This controls the flow of messages between the server and the client. For performance
+         reasons clients buffer messages before delivering to the consumer via the <literal
+            >receive()</literal> method or asynchronously via a message listener. If the consumer
+         can not process messages as fast as they are being delivered and stored in the internal
+         buffer, then you end up with a situation where messages just keep building up and are not
+         processed for a long time. Consider a situation where a queue has 2 consumers 1 of which is
+         very slow. Messages are delivered in a round robin fashion to both consumers, the fast
+         consumer processes all of its messages very quickly until its buffer is empty. At this
+         point there are still messages awaiting to be processed by the slow consumer which could be
+         being consumed by the other consumer.</para>
       <section id="flow-control.consumer.window">
          <title>Window-Based Flow Control</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 consumes a message,
-            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 
+         <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 consumes a message, 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 
+            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.</para>
-         <para>By default, the <literal>consumer-window-size</literal> is set to 1 MiB (1024 * 1024 bytes).</para>
+         <para>By default, the <literal>consumer-window-size</literal> is set to 1 MiB (1024 * 1024
+            bytes).</para>
          <para>The value can be:</para>
          <itemizedlist>
-            <listitem><para><literal>-1</literal> for an <emphasis>unbounded</emphasis> buffer</para></listitem>
-            <listitem><para><literal>0</literal> for <emphasis>no</emphasis> buffer at all</para></listitem>
-            <listitem><para><literal>1</literal> for a buffer of <emphasis>1</emphasis> message</para></listitem>
-            <listitem><para><literal>&gt;1</literal> for a buffer with the given maximum size</para></listitem>
+            <listitem>
+               <para><literal>-1</literal> for an <emphasis>unbounded</emphasis> buffer</para>
+            </listitem>
+            <listitem>
+               <para><literal>0</literal> for <emphasis>no</emphasis> buffer at all</para>
+            </listitem>
+            <listitem>
+               <para><literal>1</literal> for a buffer of <emphasis>1</emphasis> message</para>
+            </listitem>
+            <listitem>
+               <para><literal>&gt;1</literal> for a buffer with the given maximum size</para>
+            </listitem>
          </itemizedlist>
-         
-         <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>
-         <variablelist>  
+         <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>
+         <variablelist>
             <varlistentry>
                <term>Fast consumers</term>
                <listitem>
-                  <para>Fast consumers can process messages as fast as they
-                     consume them (or even faster)</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>
+                  <para>Fast consumers can process messages as fast as they consume them (or even
+                     faster)</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>
                </listitem>
             </varlistentry>
             <varlistentry>
                <term>Slow consumers</term>
                <listitem>
-                  <para>Slow consumers 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>
-                  <para>To allow slow consumers, set the <literal>consumer-window-size</literal> to 0 (for no buffer at all)
-                     or 1 (to buffer only 1 message).
-                     This will prevent from buffering many messages on the client side. Messages will remain on the server side
-                     ready to be consumed by other consumers.</para>
+                  <para>Slow consumers 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>
+                  <para>To allow slow consumers, set the <literal>consumer-window-size</literal> to
+                     0 (for no buffer at all) or 1 (to buffer only 1 message). This will prevent
+                     from buffering many messages on the client side. Messages will remain on the
+                     server side ready to be consumed by other consumers.</para>
                </listitem>
             </varlistentry>
          </variablelist>
-
-         <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>
-         
+         <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>Using Core API</title>
-            <para>If JBoss Messaging Core API is used, the consumer window size is specified
-               by <literal>ClientSessionFactory.setConsumerWindowSize()</literal>
-               method and some of the <literal>ClientSession.createConsumer()</literal> methods.</para>
+            <para>If JBoss Messaging Core API is used, the consumer window size is specified by
+                  <literal>ClientSessionFactory.setConsumerWindowSize()</literal> method and some of
+               the <literal>ClientSession.createConsumer()</literal> methods.</para>
          </section>
-         
          <section>
             <title>Using JMS</title>
             <para>if JNDI is used to look up the connection factory, the consumer window size is
-            configured in <literal>jbm-jms.xml</literal>:</para>
+               configured in <literal>jbm-jms.xml</literal>:</para>
             <programlisting>
 &lt;connection-factory name="ConnectionFactory"&gt;
    &lt;connector-ref connector-name="netty-connector"/&gt;
@@ -83,40 +97,75 @@
    &lt;consumer-window-size&gt;0&lt;/consumer-window-size&gt;
 &lt;/connection-factory&gt;
             </programlisting>
-            <para>If the connection factory is directly instantiated, the consumer window size
-               is specified by <literal>JBossConnectionFactory.setConsumerWindowSize()</literal>
+            <para>If the connection factory is directly instantiated, the consumer window size is
+               specified by <literal>JBossConnectionFactory.setConsumerWindowSize()</literal>
                method.</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
+                  <literal>no-consumer-buffering</literal> example</ulink> shows how to configure
+               JBoss Messaging to prevent consumer buffering when dealing with slow
                consumers.</para>
          </section>
       </section>
-      
       <section>
-          <title>Rate limited flow control</title>
-          <para></para>
+         <title>Rate limited flow control</title>
+         <para>It is also possible to control the rate at which a consumer can consumer messages.
+            This is a form of throttling and can be used to make sure that a consumer never consumes
+            messages at a rate faster than the rate specified. </para>
+         <para>The rate must be a positive integer to enable and is the rate per second of messages
+            consumed. Setting to 0 or negative disables rate limited flow control.</para>
+         <section>
+            <title>Using Core API</title>
+            <para>If the JBoss Messaging core API is being used the rate can be set via the <literal
+                  >ClientSessionFactory.setConsumerMaxRate(int consumerMaxRate)</literal> method or
+               alternatively via some of the <literal>ClientSession.createConsumer()</literal>
+               methods. </para>
+            <section>
+               <title>Using JMS</title>
+               <para>If JNDI is used to look up the connection factory, the max rate can be
+                  configured in <literal>jbm-jms.xml</literal>:</para>
+               <programlisting>&lt;connection-factory name="ConnectionFactory">
+      &lt;connector-ref connector-name="netty-connector"/>
+      &lt;entries>
+         &lt;entry name="ConnectionFactory"/>       
+      &lt;/entries>
+      &lt;!-- We limit consumers created on this connection factory to consume messages at a maximum rate
+      of 10 messages per sec -->
+      &lt;consumer-max-rate>10&lt;/consumer-max-rate>
+ &lt;/connection-factory></programlisting>
+               <para>If the connection factory is directly instantiated, the max rate size can be
+                  set via the <literal>JBossConnectionFactory.setConsumerMaxRate(int
+                     consumerMaxRate)</literal> method.</para>
+               <note>
+                  <para>Rate limited flow control can be used in conjunction with window based flow
+                     control. Rate limited flow control only effects how many messages a client can
+                     consume in a second and not how many messages are in its buffer. So if you had
+                     a slow rate limit and a high window based limit the clients internal buffer
+                     would soon fill up with messages.</para>
+               </note>
+            </section>
+         </section>
+         <section>
+            <title>Example</title>
+            <para>The <ulink url="../../../../examples/jms/consumer-rate-limit/readme.html">
+                  <literal>consumer-rate-limit</literal> example</ulink> shows how to configure
+               JBoss Messaging to prevent consumer buffering when dealing with slow
+               consumers.</para>
+         </section>
       </section>
    </section>
-   
    <section>
-       <title>Producer flow control</title>
-       <para></para>
-       
-       <section>
-           <title>Window based flow control</title>
-           <para></para>
-       </section>
-       
-       <section>
-           <title>Rate limited flow control</title>
-           <para></para>
-       </section>
-       
+      <title>Producer flow control</title>
+      <para>Producer flow control can be controlled using window size or rate limit </para>
+      <section>
+         <title>Window based flow control</title>
+         <para/>
+      </section>
+      <section>
+         <title>Rate limited flow control</title>
+         <para/>
+      </section>
    </section>
-   
 </chapter>




More information about the jboss-cvs-commits mailing list