General Information
The Qpid 0.6 release introduces a simplistic producer-side flow control mechanism into the Java Messaging Broker, causing producers to be flow-controlled when they attempt to send messages to an overfull queue.
Configuring a Queue to use flow control
Flow control is enabled on a producer when it sends a message to a Queue which is "overfull". The producer flow control will be rescinded when all Queues on which a producer is blocking become "underfull". A Queue is defined as overfull when the size (in bytes) of the messages on the queue exceeds the "capacity" of the Queue. A Queue becomes "underfull" when its size becomes less than the "flowResumeCapacity".
<queue>
<name>test</name>
<test>
<exchange>amq.direct</exchange>
<capacity>10485760</capacity>
<flowResumeCapacity>8388608</flowResumeCapacity>
</test>
</queue>
The default for all queues on a virtual host can also be set
<virtualhosts>
<virtualhost>
<name>localhost</name>
<localhost>
<capacity>10485760</capacity>
<flowResumeCapacity>8388608</flowResumeCapacity>
</localhost>
</virtualhost>
</virtualhosts>
Where no flowResumeCapacity is set, the flowResumeCapacity is set to be equal to the capacity. Where no capacity is set, capacity is defaulted to 0 meaning there is no capacity limit.
Client impact and configuration
If a producer sends to a queue which is overfull, the broker will respond by instructing the client not to send any more messages. The impact of this is that any future attempts to send will block until the broker rescinds the flow control order.
While blocking the client will periodically log the fact that it is blocked waiting on flow control.
WARN AMQSession - Broker enforced flow control has been enforced
WARN AMQSession - Message send delayed by 5s due to broker enforced flow control
WARN AMQSession - Message send delayed by 10s due to broker enforced flow control
After a set period the send will timeout and throw a JMSException to the calling code.
If such a JMSException is thrown, the message will not be sent to the broker, however the underlying Session may still be active - in particular if the Session is transactional then the current transaction will not be automatically rolled back. Users may choose to either attempt to resend the message, or to rollback any transactional work and close the Session.
ERROR AMQSession - Message send failed due to timeout waiting on broker enforced flow control
Both the timeout delay, and the periodicity of the warning messages can be set using java system properties. The amount of time (in milliseconds) to wait before timing out is controlled by the property qpid.flow_control_wait_failure (the default is 120000 - which is two minutes), the frequency at which the log message informing that the producer is flow controlled is sent is controlled by the system property qpid.flow_control_wait_notify_period: the default value is 5000 milliseconds (i.e. 5 seconds).
Adding the following to the command line to start the client would result in a timeout of one minute, with warning messages every ten seconds:
-Dqpid.flow_control_wait_failure=60000
-Dqpid.flow_control_wait_notify_period=10000
Broker Log Messages
There are four new Broker log messages that may occur if flow control through queue capacity limits is enabled.
Firstly, when a capacity limited queue becomes overfull, a log message similar to the following is produced
MESSAGE [vh(/test)/qu(MyQueue)] [vh(/test)/qu(MyQueue)] QUE-1003 : Overfull : Size : 1,200 bytes, Capacity : 1,000
Then for each channel which becomes blocked upon the overful queue a log message similar to the following is produced:
MESSAGE [con:2(gu...@anonymous(713889609)/test)/ch:1] [con:2(gu...@anonymous(713889609)/test)/ch:1] CHN-1005 : Flow Control Enforced (Queue MyQueue)
When enough messages have been consumed from the queue that it becomes underfull, then the following log is generated:
MESSAGE [vh(/test)/qu(MyQueue)] [vh(/test)/qu(MyQueue)] QUE-1004 : Underfull : Size : 600 bytes, Resume Capacity : 800
And for every channel which becomes unblocked you will see a message similar to:
MESSAGE [con:2(gu...@anonymous(713889609)/test)/ch:1] [con:2(gu...@anonymous(713889609)/test)/ch:1] CHN-1006 : Flow Control Removed
Obviously the details of connection, virtual host, queue, size, capacity, etc would depend on the configuration in use.
