[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>>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>>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>
<connection-factory name="ConnectionFactory">
<connector-ref connector-name="netty-connector"/>
@@ -83,40 +97,75 @@
<consumer-window-size>0</consumer-window-size>
</connection-factory>
</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><connection-factory name="ConnectionFactory">
+ <connector-ref connector-name="netty-connector"/>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+ <!-- We limit consumers created on this connection factory to consume messages at a maximum rate
+ of 10 messages per sec -->
+ <consumer-max-rate>10</consumer-max-rate>
+ </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