[hornetq-commits] JBoss hornetq SVN: r8558 - trunk/docs/user-manual/en.
do-not-reply at jboss.org
do-not-reply at jboss.org
Fri Dec 4 11:30:54 EST 2009
Author: timfox
Date: 2009-12-04 11:30:53 -0500 (Fri, 04 Dec 2009)
New Revision: 8558
Modified:
trunk/docs/user-manual/en/flow-control.xml
Log:
flow control docs
Modified: trunk/docs/user-manual/en/flow-control.xml
===================================================================
--- trunk/docs/user-manual/en/flow-control.xml 2009-12-04 16:10:51 UTC (rev 8557)
+++ trunk/docs/user-manual/en/flow-control.xml 2009-12-04 16:30:53 UTC (rev 8558)
@@ -184,9 +184,84 @@
server being overwhelmed.</para>
<section>
<title>Window based flow control</title>
- <para>HornetQ clients maintain a buffer of commands that have been sent to the server, thus
- provides a form of flow control. Please see <xref linkend="command-buffering"/> for more
- information on this.</para>
+ <para>In a similar way to consumer window based flow control, HornetQ producers, by
+ default, can only send messages to an address as long as they have sufficient credits to
+ do so. The amount of credits required to send a message is given by the size of the
+ message.</para>
+ <para>As producers run low on credits they request more from the server, when the server
+ sends them more credits they can send more messages.</para>
+ <para>The amount of credits a producer requests in one go is known as the <emphasis
+ role="italic">window size</emphasis>.</para>
+ <para>The window size therefore determines the amount of bytes that can be inflight at any
+ one time before more need to be requested - this prevents the remoting connection from
+ getting overloaded.</para>
+ <section>
+ <title>Using Core API</title>
+ <para>If the HornetQ core API is being window size can be set via the <literal
+ >ClientSessionFactory.setProducerWindowSize(int producerWindowSize)</literal>
+ method.</para>
+ </section>
+ <section>
+ <title>Using JMS</title>
+ <para>If JNDI is used to look up the connection factory, the producer window size can be
+ configured in <literal>hornetq-jms.xml</literal>:</para>
+ <programlisting>
+ <connection-factory name="ConnectionFactory">
+ <connectors>
+ <connector-ref connector-name="netty-connector"/>
+ </connectors>
+ <entries>
+ <entry name="ConnectionFactory"/>
+ </entries>
+ <producer-window-size>10</producer-window-size>
+ </connection-factory></programlisting>
+ <para>If the connection factory is directly instantiated, the producer window size can
+ be set via the <literal>HornetQConnectionFactory.setProducerWindowSize(int
+ producerWindowSize)</literal> method.</para>
+ </section>
+ <section>
+ <title>Blocking producer window based flow control</title>
+ <para>Normally the server will always give the same number of credits as have been
+ requested. However, it is also possible to set a maximum size on any address, and the
+ server will never send more credits than could cause the address's upper memory limit
+ to be exceeded.</para>
+ <para>For example, if I have a JMS queue called "myqueue", I could set the maximum
+ memory size to 10MiB, and the the server will control the number of credits sent to
+ any producers which are sending any messages to myqueue such that the total messages
+ in the queue never exceeds 10MiB.</para>
+ <para>When the address gets full, producers will block on the client side until more
+ space frees up on the address, i.e. until messages are consumed from the queue thus
+ freeing up space for more messages to be sent.</para>
+ <para>We call this blocking producer flow control, and it's an efficient way to prevent
+ the server running out of memory due to producers sending more messages than can be
+ handled at any time.</para>
+ <para>It is an alternative approach to paging, which does not block producers but
+ instead pages messages to storage.</para>
+ <para>To configure an address with a maximum size and tell the server that you want to
+ block producers for this address if it becomes full, you need to define an
+ AddressSettings (<xref linkend="queue-attributes.address-settings"/>) block for the
+ address and specify <literal>max-size-bytes</literal> and <literal
+ >address-full-policy</literal></para>
+ <para>The address block applies to all queues registered to that address. I.e. the total
+ memory for all queues bound to that address will not exceed <literal
+ >max-size-bytes</literal>. In the case of JMS topics this means the <emphasis
+ role="italic">total</emphasis> memory of all subscriptions in the topic won't
+ exceed max-size-bytes.</para>
+ <para>Here's an example:</para>
+ <programlisting>
+ <address-settings>
+ <address-setting match="jms.queue.exampleQueue">
+ <max-size-bytes>100000</max-size-bytes>
+ <address-full-policy>DROP</address-full-policy>
+ </address-setting>
+ </address-settings></programlisting>
+ <para>The above example would set the max size of the JMS queue "exampleQueue" to be
+ 100000 bytes and would block any producers sending to that address to prevent that
+ max size being exceeded.</para>
+ <para>Please note the default value for <literal>address-full-policy</literal> is to
+ <literal>PAGE</literal>. Please see the chapter on paging for more information on
+ paging.</para>
+ </section>
</section>
<section>
<title>Rate limited flow control</title>
More information about the hornetq-commits
mailing list