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> + &lt;connection-factory name="ConnectionFactory"> + &lt;connectors> + &lt;connector-ref connector-name="netty-connector"/> + &lt;/connectors> + &lt;entries> + &lt;entry name="ConnectionFactory"/> + &lt;/entries> + &lt;producer-window-size>10&lt;/producer-window-size> + &lt;/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> + &lt;address-settings> + &lt;address-setting match="jms.queue.exampleQueue"> + &lt;max-size-bytes>100000&lt;/max-size-bytes> + &lt;address-full-policy>DROP&lt;/address-full-policy> + &lt;/address-setting> + &lt;/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>