flow control docs

docs/user-manual/en/flow-control.xml

@@ -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>