Author: kgiusti
Date: Wed Mar 9 15:17:52 2011
New Revision: 1079830
URL: http://svn.apache.org/viewvc?rev=1079830&view=rev
Log:
QPID-3128: add producer flow control info to C++ Broker docs
Added:
qpid/trunk/qpid/doc/book/src/producer-flow-control.xml
Modified:
qpid/trunk/qpid/doc/book/src/AMQP-Messaging-Broker-CPP-Book.xml
qpid/trunk/qpid/doc/book/src/AMQP-Messaging-Broker-CPP.xml
qpid/trunk/qpid/doc/book/src/Cheat-Sheet-for-configuring-Queue-Options.xml
Modified: qpid/trunk/qpid/doc/book/src/AMQP-Messaging-Broker-CPP-Book.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/AMQP-Messaging-Broker-CPP-Book.xml?rev=1079830&r1=1079829&r2=1079830&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/AMQP-Messaging-Broker-CPP-Book.xml (original)
+++ qpid/trunk/qpid/doc/book/src/AMQP-Messaging-Broker-CPP-Book.xml Wed Mar 9
15:17:52 2011
@@ -56,6 +56,7 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="LVQ.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="queue-state-replication.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="Starting-a-cluster.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="producer-flow-control.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="AMQP-Compatibility.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="Qpid-Interoperability-Documentation.xml"/>
Modified: qpid/trunk/qpid/doc/book/src/AMQP-Messaging-Broker-CPP.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/AMQP-Messaging-Broker-CPP.xml?rev=1079830&r1=1079829&r2=1079830&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/AMQP-Messaging-Broker-CPP.xml (original)
+++ qpid/trunk/qpid/doc/book/src/AMQP-Messaging-Broker-CPP.xml Wed Mar 9
15:17:52 2011
@@ -50,7 +50,8 @@
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="LVQ.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="queue-state-replication.xml"/>
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="Starting-a-cluster.xml"/>
- <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="ACL.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"; href="ACL.xml"/>
+ <xi:include xmlns:xi="http://www.w3.org/2001/XInclude";
href="producer-flow-control.xml"/>
</chapter>
Modified:
qpid/trunk/qpid/doc/book/src/Cheat-Sheet-for-configuring-Queue-Options.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/Cheat-Sheet-for-configuring-Queue-Options.xml?rev=1079830&r1=1079829&r2=1079830&view=diff
==============================================================================
--- qpid/trunk/qpid/doc/book/src/Cheat-Sheet-for-configuring-Queue-Options.xml
(original)
+++ qpid/trunk/qpid/doc/book/src/Cheat-Sheet-for-configuring-Queue-Options.xml
Wed Mar 9 15:17:52 2011
@@ -65,6 +65,16 @@
</itemizedlist>
</para></listitem>
</itemizedlist>
+
+ <para>
+ The 0.10 C++ Broker supports the following additional Queue
configuration options:
+ </para>
+ <itemizedlist>
+ <listitem><para>
+ <xref linkend="producer-flow-control"/>
+ </para></listitem>
+ </itemizedlist>
+
<section role="h3"
id="CheatSheetforconfiguringQueueOptions-ApplyingQueueSizingConstraints"><title>
Applying Queue Sizing Constraints
</title>
Added: qpid/trunk/qpid/doc/book/src/producer-flow-control.xml
URL:
http://svn.apache.org/viewvc/qpid/trunk/qpid/doc/book/src/producer-flow-control.xml?rev=1079830&view=auto
==============================================================================
--- qpid/trunk/qpid/doc/book/src/producer-flow-control.xml (added)
+++ qpid/trunk/qpid/doc/book/src/producer-flow-control.xml Wed Mar 9 15:17:52
2011
@@ -0,0 +1,347 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+
+-->
+
+<section id="producer-flow-control">
+ <title>
+ Producer Flow Control
+ </title>
+
+ <section role="h2" id="producerflowcontrol-Overview">
+ <title>
+ Overview
+ </title>
+ <para>
+ As of release 0.10, the C++ broker supports the use of flow control to
+ throttle back message producers that are at risk of overflowing a
+ destination queue.
+ </para>
+
+ <para>
+ Each queue in the C++ broker has two threshold values associated with
it:
+ </para>
+
+ <para>
+ Flow Stop Threshold: this is the level of queue resource
+ utilization above which flow control will be enabled. Once this
+ threshold is crossed, the queue is considered in danger of overflow.
+ </para>
+
+ <para>
+ Flow Resume Threshold - this is the level of queue resource utilization
+ below which flow control will be disabled. Once this threshold is
+ crossed, the queue is no longer considered in danger of overflow.
+ </para>
+
+ <para>
+ In the above description, queue resource utilization may be
+ defined as the total count of messages currently enqueued, or the total
+ sum of all message content in bytes.
+ </para>
+
+ <para>
+ The value for a queue's Flow Stop Threshold must be greater than or
+ equal to the value of the queue's Flow Resume Threshold.
+ </para>
+
+ <section role="h3" id="producerflowcontrol-QueueThresholdsExample">
+ <title>
+ Example
+ </title>
+
+ <para>
+ Let's consider a queue with a maximum limit set on the total number of
+ messages that may be enqueued to that queue. Assume this maximum
+ message limit is 1000 messages. Assume also that the user configures a
+ Flow Stop Threshold of 900 messages, and a Flow Resume Threshold of 500
+ messages. Then the following holds:
+ </para>
+
+ <para>
+ When the total number of enqueued messages is greater than or equal to
+ 900, the queue's flow control state is OFF.
+ </para>
+
+ <para>
+ When the total number of enqueued messages is greater than 900, the
+ queue's flow control state transitions to ON.
+ </para>
+
+ <para>
+ When the queue's flow control state is "ON", it remains "ON" until the
+ total number of enqueued messages is less than 500. At that point,
the queue's
+ flow control state transitions to "OFF".
+ </para>
+
+ <para>
+ A similar example using total enqueued content bytes as the threshold
+ units are permitted.
+ </para>
+ </section>
+
+ <para>
+ Thresholds may be set using both total message counts and total byte
+ counts. In this case, the following rules apply:
+ </para>
+
+ <para>
+ 1) Flow control is "ON" when either stop threshold value is crossed.
+ </para>
+ <para>
+ 2) Flow control remains "ON" until both resume thresholds are satisfied.
+ </para>
+
+ <section role="h3" id="producerflowcontro-MultiThresholdExample">
+ <title>
+ Example
+ </title>
+
+ <para>
+ Let's consider a queue with a maximum size limit of 10K bytes, and 5000
+ messages. A user may assign a Flow Stop Threshold based on a total
+ message count of 4000 messages. They may also assigne a Flow Stop
+ Threshold of 8K bytes. The queue's flow control state transitions to
+ "ON" if either threshold is crossed: (total-msgs greater-than 4000 OR
total-bytes
+ greater-than 8K).
+ </para>
+
+ <para>
+ Assume the user has assigned Flow Resume threshold's of 3000 messages and
+ 6K bytes. Then the queue's flow control will remain active until both
+ thresholds are satified: (total-msg less-than 3000 AND total-bytes
less-than 6K).
+ </para>
+ </section>
+
+ <para>
+ The Broker enforces flow control by delaying the completion of the
+ Message.Transfer command that causes a message to be delivered to a queue
+ with active flow control. The completion of the Message.Transfer command
+ is held off until flow control state transitions to "OFF" for all queues
+ that are a destination for that command.
+ </para>
+
+ <para>
+ A message producing client is permitted to have a finite number of
+ commands pending completion. When the total number of these outstanding
+ commands reaches the limit, the client must not issue further commands
+ until one or more of the outstanding commands have completed. This
+ window of outstanding commands is considered the sender's "capacity".
+ This allows any given producer to have a "capacity's" worth of messages
+ blocked due to flow control before the sender must stop sending further
+ messages.
+ </para>
+
+ <para>
+ This capacity window must be considered when determining a suitable
+ flow stop threshold for a given queue, as a producer may send its
+ capacity worth of messages _after_ a queue has reached the flow stop
+ threshold. Therefore, a flow stop threshould should be set such that
+ the queue can accomodate more messages without overflowing.
+ </para>
+
+ <para>
+ For example, assume two clients, C1 and C2, are producing messages to
+ one particular destination queue. Assume client C1 has a configured
+ capacity of 50 messages, and client C2's capacity is 15 messages. In
+ this example, assume C1 and C2 are the only clients queuing messages to
+ a given queue. If this queue has a Flow Stop Threshold of 100
+ messages, then, worst-case, the queue may receive up to 165 messages
+ before clients C1 and C2 are blocked from sending further messages.
+ This is due to the fact that the queue will enable flow control on
+ receipt of its 101'st message - preventing the completion of the
+ Message.Transfer command that carried the 101'st message. However, C1
+ and C2 are allowed to have a total of 65 (50 for C1 and 15 for C2)
+ messages pending completion of Message.Transfer before they will stop
+ producing messages. Thus, up to 65 messages may be enqueued beyond the
+ flow stop threshold before the producers will be blocked.
+ </para>
+ </section>
+
+ <section role="h2" id="producerflowcontrol-UserInterface">
+ <title>
+ User Interface
+ </title>
+
+ <para>
+ By default, the C++ broker assigns a queue's flow stop and flow resume
+ thresholds when the queue is created. The C++ broker also allows the
+ user to manually specify the flow control thresholds on a per queue
+ basis.
+ </para>
+
+ <para>
+ However, queues that have been configured with a Limit Policy of type
+ RING or RING-STRICT do NOT have queue flow thresholds enabled by
+ default. The nature of a RING queue defines its behavior when its
+ capacity is reach: replace the oldest message.
+ </para>
+
+ <para>
+ The flow control state of a queue can be determined by the "flowState"
+ boolean in the queue's QMF management object. The queue's management
+ object also contains a counter that increments each time flow control
+ becomes active for the queue.
+ </para>
+
+ <para>
+ The broker applies a threshold ratio to compute a queue's default flow
+ control configuration. These thresholds are expressed as a percentage
+ of a queue's maximum capacity. There is one value for determining the
+ stop threshold, and another for determining the resume threshold. The
+ user may configure these percentages using the following broker
+ configuration options:
+ </para>
+
+ <programlisting>
+ --default-flow-stop-threshold ("Queue capacity level at which flow
control is activated.")
+ --default-flow-resume-threshold ("Queue capacity level at which flow
control is de-activated.")
+ </programlisting>
+
+ <para>
+ For example:
+ </para>
+
+ <programlisting>
+ qpidd --default-flow-stop-threshold=90
--default-flow-resume-threshold=75
+ </programlisting>
+
+ <para>
+ Sets the default flow stop threshold to 90% of a queue's maximum
+ capacity and the flow resume threshold to 75% of the maximum capacity.
+ If a queue is created with a default-queue-limit of 10000 bytes, then
+ the default flow stop threshold would be 90% of 10000 = 9000 bytes and
+ the flow resume threshold would be 75% of 10000 = 7500. The same
+ computation is performed should a queue be created with a maximum size
+ expressed as a message count instead of a byte count.
+ </para>
+
+ <para>
+ If not overridden by the user, the value of the
+ default-flow-stop-threshold is 80% and the value of the
+ default-flow-resume-threshold is 70%.
+ </para>
+
+ <para>
+ The user may disable default queue flow control broker-wide by
+ specifying the value 0 for both of these configuration options. Note
+ that flow control may still be applied manually on a per-queue basis in
+ this case.
+ </para>
+
+ <para>
+ The user may manually set the flow thresholds when creating a queue.
+ The following options may be provided when adding a queue using the
+ <command>qpid-config</command> command line tool:
+ </para>
+
+ <programlisting>
+ --flow-stop-size=<replaceable>N</replaceable> Sets the queue's flow
stop threshold to <replaceable>N</replaceable> total bytes.
+ --flow-resume-size=<replaceable>N</replaceable> Sets the queue's flow
resume threshold to <replaceable>N</replaceable> total bytes.
+ --flow-stop-count=<replaceable>N</replaceable> Sets the queue's flow
stop threshold to <replaceable>N</replaceable> total messages.
+ --flow-resume-count=<replaceable>N</replaceable> Sets the queue's flow
resume threshold to <replaceable>N</replaceable> total messages.
+ </programlisting>
+
+ <para>
+ Flow thresholds may also be specified in the
+ <command>queue.declare</command> method, via the
+ <command>arguments</command> parameter map. The following keys can be
+ provided in the arguments map for setting flow thresholds:
+ </para>
+
+ <table>
+ <title>Queue Declare Method Flow Control Arguments</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Key</entry>
+ <entry>Value</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>qpid.flow_stop_size</entry>
+ <entry>integer - queue's flow stop threshold value in
bytes</entry>
+ </row>
+ <row>
+ <entry>qpid.flow_resume_size</entry>
+ <entry>integer - queue's flow resume threshold value in
bytes</entry>
+ </row>
+ <row>
+ <entry>qpid.flow_stop_count</entry>
+ <entry>integer - queue's flow stop threshold value as a message
count</entry>
+ </row>
+ <row>
+ <entry>qpid.flow_resume_count</entry>
+ <entry>integer - queue's flow resume threshold value as a
message count</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ The user may disable flow control on a per queue basis by setting
+ the flow-stop-size and flow-stop-count to zero for the queue.
+ </para>
+
+ <para>
+ The current state of flow control for a given queue can be
+ determined by the "flowStopped" statistic. This statistic is
+ available in the queue's QMF management object. The value of
+ flowStopped is True when the queue's capacity has exceeded the
+ flow stop threshold. The value of flowStopped is False when the
+ queue is no longer blocking due to flow control.
+ </para>
+
+ <para>
+ A queue will also track the number of times flow control has been
+ activated. The "flowStoppedCount" statistic is incremented each time
+ the queue's capacity exceeds a flow stop threshold. This statistic can
+ be used to monitor the activity of flow control for any given queue
+ over time.
+ </para>
+
+ <table>
+ <title>Flow Control Statistics available in Queue's QMF Class</title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>Statistic Name</entry>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>flowStopped</entry>
+ <entry>Boolean</entry>
+ <entry>If true, producers are blocked by flow control.</entry>
+ </row>
+ <row>
+ <entry>flowStoppedCount</entry>
+ <entry>count32</entry>
+ <entry>Number of times flow control was activated for this
queue</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+ <!--h2-->
+ </section>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:[email protected]
