You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by jo...@apache.org on 2011/04/28 18:49:56 UTC
svn commit: r1097544 [5/20] - in /qpid/site/docs/books/0.10: ./
AMQP-Messaging-Broker-CPP-Book/ AMQP-Messaging-Broker-CPP-Book/html-single/
AMQP-Messaging-Broker-CPP-Book/html-single/images/
AMQP-Messaging-Broker-CPP-Book/html-single/images/jmx_console...
Added: qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s07.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s07.html?rev=1097544&view=auto
==============================================================================
--- qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s07.html (added)
+++ qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s07.html Thu Apr 28 16:49:49 2011
@@ -0,0 +1,229 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>1.7. Queue State Replication</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in C++)"><link rel="up" href="ch01.html" title="Chapter 1. Running the AMQP Messaging Broker"><link rel="prev" href="ch01s06.html" title="1.6. LVQ"><link rel="next" href="ch01s08.html" title="1.8. High Availability Messaging Clusters"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">1.7.
+ Queue State Replication
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch01s06.html">Prev</a> </td><th width="60%" align="center">Chapter 1.
+ Running the AMQP Messaging Broker
+ </th><td width="20%" align="right"> <a accesskey="n" href="ch01s08.html">Next</a></td></tr></table><hr></div><div class="section" title="1.7. Queue State Replication"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="queue-state-replication"></a>1.7.
+ Queue State Replication
+ </h2></div></div></div><div class="section" title="1.7.1. Asynchronous Replication of Queue State"><div class="titlepage"><div><div><h3 class="title"><a name="queuestatereplication-AsynchronousReplicationofQueueState"></a>1.7.1.
+ Asynchronous
+ Replication of Queue State
+ </h3></div></div></div><div class="section" title="1.7.1.1. Overview"><div class="titlepage"><div><div><h4 class="title"><a name="queuestatereplication-Overview"></a>1.7.1.1.
+ Overview
+ </h4></div></div></div><p>
+ There is support in qpidd for selective asynchronous replication
+ of queue state. This is achieved by:
+ </p><p>
+ (a) enabling event generation for the queues in question
+ </p><p>
+ (b) loading a plugin on the 'source' broker to encode those
+ events as messages on a replication queue (this plugin is
+ called
+ replicating_listener.so)
+ </p><p>
+ (c) loading a custom exchange plugin on the 'backup' broker (this
+ plugin is called replication_exchange.so)
+ </p><p>
+ (d) creating an instance of the replication exchange type on the
+ backup broker
+ </p><p>
+ (e) establishing a federation bridge between the replication
+ queue on the source broker and the replication exchange on the
+ backup broker
+ </p><p>
+ The bridge established between the source and backup brokers for
+ replication (step (e) above) should have acknowledgements turned
+ on (this may be done through the --ack N option to qpid-route).
+ This ensures that replication events are not lost if the bridge
+ fails.
+ </p><p>
+ The replication protocol will also eliminate duplicates to ensure
+ reliably replicated state. Note though that only one bridge per
+ replication exchange is supported. If clients try to publish to
+ the replication exchange or if more than a the single required
+ bridge from the replication queue on the source broker is
+ created, replication will be corrupted. (Access control may be
+ used to restrict access and help prevent this).
+ </p><p>
+ The replicating event listener plugin (step (b) above) has the
+ following options:
+ </p><pre class="programlisting">
+Queue Replication Options:
+ --replication-queue QUEUE Queue on which events for
+ other queues are recorded
+ --replication-listener-name NAME (replicator) name by which to register the
+ replicating event listener
+ --create-replication-queue if set, the replication will
+ be created if it does not
+ exist
+ </pre><p>
+ The name of the queue is required. It can either point to a
+ durable queue whose definition has been previously recorded, or
+ the --create-replication-queue option can be specified in which
+ case the queue will be created a simple non-durable queue if it
+ does not already exist.
+ </p></div><div class="section" title="1.7.1.2. Use with Clustering"><div class="titlepage"><div><div><h4 class="title"><a name="queuestatereplication-UsewithClustering"></a>1.7.1.2.
+ Use with
+ Clustering
+ </h4></div></div></div><p>
+ The source and/or backup brokers may also be clustered brokers.
+ In this case the federated bridge will be re-established between
+ replicas should either of the originally connected nodes fail.
+ There are however the following limitations at present:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The backup site does not process membership updates after it
+ establishes the first connection. In order for newly added
+ members on a source cluster to be eligible as failover targets,
+ the bridge must be recreated after those members have been added
+ to the source cluster.
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>New members added to a backup cluster will not receive
+ information about currently established bridges. Therefore in
+ order to allow the bridge to be re-established from these members
+ in the event of failure of older nodes, the bridge must be
+ recreated after the new members have joined.
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Only a single URL can be passed to create the initial link
+ from backup site to the primary site. this means that at the time
+ of creating the initial connection the initial node in the
+ primary site to which the connection is made needs to be running.
+ Once connected the backup site will receive a membership update
+ of all the nodes in the primary site, and if the initial
+ connection node in the primary fails, the link will be
+ re-established on the next node that was started (time) on the
+ primary site.
+ </p></li></ul></div><p>
+ Due to the acknowledged transfer of events over the bridge (see
+ note above) manual recreation of the bridge and automatic
+ re-establishment of te bridge after connection failure (including
+ failover where either or both ends are clustered brokers) will
+ not result in event loss.
+ </p></div><div class="section" title="1.7.1.3. Operations on Backup Queues"><div class="titlepage"><div><div><h4 class="title"><a name="queuestatereplication-OperationsonBackupQueues"></a>1.7.1.3.
+ Operations
+ on Backup Queues
+ </h4></div></div></div><p>
+ When replicating the state of a queue to a backup broker it is
+ important to recognise that any other operations performed
+ directly on the backup queue may break the replication.
+ </p><p>
+ If the backup queue is to be an active (i.e. accessed by clients
+ while replication is on) only enqueues should be selected
+ for
+ replication. In this mode, any message enqueued on the source
+ brokers copy of the queue will also be enqueued on the backup
+ brokers copy. However not attempt will be made to remove messages
+ from the backup queue in response to removal of messages from the
+ source queue.
+ </p></div><div class="section" title="1.7.1.4. Selecting Queues for Replication"><div class="titlepage"><div><div><h4 class="title"><a name="queuestatereplication-SelectingQueuesforReplication"></a>1.7.1.4.
+ Selecting
+ Queues for Replication
+ </h4></div></div></div><p>
+ Queues are selected for replication by specifying the types of
+ events they should generate (it is from these events that the
+ replicating plugin constructs messages which are then pulled and
+ processed by the backup site). This is done through options
+ passed to the initial queue-declare command that creates the
+ queue and may be done either through qpid-config or similar
+ tools, or by the application.
+ </p><p>
+ With qpid-config, the --generate-queue-events options is used:
+ </p><pre class="programlisting">
+ --generate-queue-events N
+ If set to 1, every enqueue will generate an event that can be processed by
+ registered listeners (e.g. for replication). If set to 2, events will be
+ generated for enqueues and dequeues
+ </pre><p>
+ From an application, the arguments field of the queue-declare
+ AMQP command is used to convey this information. An entry should
+ be added to the map with key 'qpid.queue_event_generation' and an
+ integer value of 1 (to replicate only enqueue events) or 2 (to
+ replicate both enqueue and dequeue events).
+ </p><p>
+ Applications written using the c++ client API may fine the
+ qpid::client::QueueOptions class convenient. This has a
+ enableQueueEvents() method on it that can be used to set the
+ option (the instance of QueueOptions is then passed as the value
+ of the arguments field in the queue-declare command. The boolean
+ option to that method should be set to true if only enequeue
+ events should be replicated; by default it is false meaning that
+ both enqueues and dequeues will be replicated. E.g.
+ </p><pre class="programlisting">
+ QueueOptions options;
+ options.enableQueueEvents(false);
+ session.queueDeclare(arg::queue="my-queue", arg::arguments=options);
+ </pre></div><div class="section" title="1.7.1.5. Example"><div class="titlepage"><div><div><h4 class="title"><a name="queuestatereplication-Example"></a>1.7.1.5.
+ Example
+ </h4></div></div></div><p>
+ Lets assume we will run the primary broker on host1 and the
+ backup on host2, have installed qpidd on both and have the
+ replicating_listener and replication_exchange plugins in qpidd's
+ module directory(*1).
+ </p><p>
+ On host1 we start the source broker and specifcy that a queue
+ called 'replication' should be used for storing the events until
+ consumed by the backup. We also request that this queue be
+ created (as transient) if not already specified:
+ </p><pre class="programlisting">
+ qpidd --replication-queue replication-queue --create-replication-queue true --log-enable info+
+ </pre><p>
+ On host2 we start up the backup broker ensuring that the
+ replication exchange module is loaded:
+ </p><pre class="programlisting">
+ qpidd
+ </pre><p>
+ We can then create the instance of that replication exchange that
+ we will use to process the events:
+ </p><pre class="programlisting">
+ qpid-config -a host2 add exchange replication replication-exchange
+ </pre><p>
+ If this fails with the message "Exchange type not implemented:
+ replication", it means the replication exchange module was
+ not
+ loaded. Check that the module is installed on your system and if
+ necessary provide the full path to the library.
+ </p><p>
+ We then connect the replication queue on the source broker with
+ the replication exchange on the backup broker using the
+ qpid-route command:
+ </p><pre class="programlisting">
+ qpid-route --ack 50 queue add host2 host1 replication-exchange replication-queue
+</pre><p>
+ The example above configures the bridge to acknowledge messages
+ in batches of 50.
+ </p><p>
+ Now create two queues (on both source and backup brokers), one
+ replicating both enqueues and dequeues (queue-a) and the
+ other
+ replicating only dequeues (queue-b):
+ </p><pre class="programlisting">
+ qpid-config -a host1 add queue queue-a --generate-queue-events 2
+ qpid-config -a host1 add queue queue-b --generate-queue-events 1
+
+ qpid-config -a host2 add queue queue-a
+ qpid-config -a host2 add queue queue-b
+ </pre><p>
+ We are now ready to use the queues and see the replication.
+ </p><p>
+ Any message enqueued on queue-a will be replicated to the backup
+ broker. When the message is acknowledged by a client connected to
+ host1 (and thus dequeued), that message will be removed from the
+ copy of the queue on host2. The state of queue-a on host2 will
+ thus mirror that of the equivalent queue on host1, albeit with a
+ small lag. (Note
+ however that we must not have clients connected to host2 publish
+ to-or consume from- queue-a or the state will fail to replicate
+ correctly due to conflicts).
+ </p><p>
+ Any message enqueued on queue-b on host1 will also be enqueued on
+ the equivalent queue on host2. However the acknowledgement and
+ consequent dequeuing of messages from queue-b on host1 will have
+ no effect on the state of queue-b on host2.
+ </p><p>
+ (*1) If not the paths in the above may need to be modified. E.g.
+ if using modules built from a qpid svn checkout, the following
+ would be added to the command line used to start qpidd on host1:
+ </p><pre class="programlisting">
+ --load-module <path-to-qpid-dir>/src/.libs/replicating_listener.so
+ </pre><p>
+ and the following for the equivalent command line on host2:
+ </p><pre class="programlisting">
+ --load-module <path-to-qpid-dir>/src/.libs/replication_exchange.so
+ </pre></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s06.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch01s08.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.6.
+ LVQ
+ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 1.8. High Availability Messaging Clusters</td></tr></table></div></body></html>
Added: qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s08.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s08.html?rev=1097544&view=auto
==============================================================================
--- qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s08.html (added)
+++ qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s08.html Thu Apr 28 16:49:49 2011
@@ -0,0 +1,248 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>1.8. High Availability Messaging Clusters</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in C++)"><link rel="up" href="ch01.html" title="Chapter 1. Running the AMQP Messaging Broker"><link rel="prev" href="ch01s07.html" title="1.7. Queue State Replication"><link rel="next" href="ch01s09.html" title="1.9. Producer Flow Control"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">1.8. High Availability Messaging Clusters</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch01s07.html">Prev</a> </td><th width="60%" align="center">Chapter 1.
+ Running the AMQP Messaging Broker
+ </th><td width="20%" align="right"> <a accesskey="n" href="ch01s09.html">Next</a></td></tr></table><hr></div><div class="section" title="1.8. High Availability Messaging Clusters"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="chap-Messaging_User_Guide-High_Availability_Messaging_Clusters"></a>1.8. High Availability Messaging Clusters</h2></div></div></div><p>
+ High Availability Messaging Clusters provide fault tolerance by ensuring that every broker in a <em class="firstterm">cluster</em> has the same queues, exchanges, messages, and bindings, and allowing a client to <em class="firstterm">fail over</em> to a new broker and continue without any loss of messages if the current broker fails or becomes unavailable. Because all brokers are automatically kept in a consistent state, clients can connect to and use any broker in a cluster. Any number of messaging brokers can be run as one <em class="firstterm">cluster</em>, and brokers can be added to or removed from a cluster while it is in use.
+ </p><p>
+ High Availability Messaging Clusters are implemented using using the <a class="ulink" href="http://www.openais.org/" target="_top">OpenAIS Cluster Framework</a>.
+ </p><p>
+ An OpenAIS daemon runs on every machine in the cluster, and these daemons communicate using multicast on a particular address. Every qpidd process in a cluster joins a named group that is automatically synchronized using OpenAIS Closed Process Groups (CPG) — the qpidd processes multicast events to the named group, and CPG ensures that each qpidd process receives all the events in the same sequence. All members get an identical sequence of events, so they can all update their state consistently.
+ </p><p>
+ Two messaging brokers are in the same cluster if
+ </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ They run on hosts in the same OpenAIS cluster; that is, OpenAIS is configured with the same mcastaddr, mcastport and bindnetaddr, and
+ </p></li><li class="listitem"><p>
+ They use the same cluster name.
+ </p></li></ol></div><p>
+
+ </p><p>
+ High Availability Clustering has a cost: in order to allow each broker in a cluster to continue the work of any other broker, a cluster must replicate state for all brokers in the cluster. Because of this, the brokers in a cluster should normally be on a LAN; there should be fast and reliable connections between brokers. Even on a LAN, using multiple brokers in a cluster is somewhat slower than using a single broker without clustering. This may be counter-intuitive for people who are used to clustering in the context of High Performance Computing or High Throughput Computing, where clustering increases performance or throughput.
+ </p><p>
+ High Availability Messaging Clusters should be used together with Red Hat Clustering Services (RHCS); without RHCS, clusters are vulnerable to the "split-brain" condition, in which a network failure splits the cluster into two sub-clusters that cannot communicate with each other. See the documentation on the <span class="command"><strong>--cluster-cman</strong></span> option for details on running using RHCS with High Availability Messaging Clusters. See the <a class="ulink" href="http://sources.redhat.com/cluster/wiki" target="_top">CMAN Wiki</a> for more detail on CMAN and split-brain conditions. Use the <span class="command"><strong>--cluster-cman</strong></span> option to enable RHCS when starting the broker.
+ </p><div class="section" title="1.8.1. Starting a Broker in a Cluster"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Starting_a_Broker_in_a_Cluster"></a>1.8.1. Starting a Broker in a Cluster</h3></div></div></div><p>
+ Clustering is implemented using the <code class="filename">cluster.so</code> module, which is loaded by default when you start a broker. To run brokers in a cluster, make sure they all use the same OpenAIS mcastaddr, mcastport, and bindnetaddr. All brokers in a cluster must also have the same cluster name — specify the cluster name in <code class="filename">qpidd.conf</code>:
+ </p><pre class="screen">cluster-name="local_test_cluster"
+</pre><p>
+ On RHEL6, you must create the file <code class="filename">/etc/corosync/uidgid.d/qpidd</code> to tell Corosync the name of the user running the broker.By default, the user is qpidd:
+ </p><pre class="programlisting">
+uidgid {
+ uid: qpidd
+ gid: qpidd
+}
+</pre><p>
+ On RHEL5, the primary group for the process running qpidd must be the ais group. If you are running qpidd as a service, it is run as the <span class="command"><strong>qpidd</strong></span> user, which is already in the ais group. If you are running the broker from the command line, you must ensure that the primary group for the user running qpidd is ais. You can set the primary group using <span class="command"><strong>newgrp</strong></span>:
+ </p><pre class="screen">$ newgrp ais
+</pre><p>
+ You can then run the broker from the command line, specifying the cluster name as an option.
+ </p><pre class="screen">[jonathan@localhost]$ qpidd --cluster-name="local_test_cluster"
+</pre><p>
+ All brokers in a cluster must have identical configuration, with a few exceptions noted below. They must load the same set of plug-ins, and have matching configuration files and command line arguments. The should also have identical ACL files and SASL databases if these are used. If one broker uses persistence, all must use persistence — a mix of transient and persistent brokers is not allowed. Differences in configuration can cause brokers to exit the cluster. For instance, if different ACL settings allow a client to access a queue on broker A but not on broker B, then publishing to the queue will succeed on A and fail on B, so B will exit the cluster to prevent inconsistency.
+ </p><p>
+ The following settings can differ for brokers on a given cluster:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+ logging options
+ </p></li><li class="listitem"><p>
+ cluster-url — if set, it will be different for each broker.
+ </p></li><li class="listitem"><p>
+ port — brokers can listen on different ports.
+ </p></li></ul></div><p>
+ The qpid log contains entries that record significant clustering events, e.g. when a broker becomes a member of a cluster, the membership of a cluster is changed, or an old journal is moved out of the way. For instance, the following message states that a broker has been added to a cluster as the first node:
+ </p><pre class="screen">
+2009-07-09 18:13:41 info 127.0.0.1:1410(READY) member update: 127.0.0.1:1410(member)
+2009-07-09 18:13:41 notice 127.0.0.1:1410(READY) first in cluster
+</pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
+ If you are using SELinux, the qpidd process and OpenAIS must have the same SELinux context, or else SELinux must be set to permissive mode. If both qpidd and OpenAIS are run as services, they have the same SELinux context. If both OpenAIS and qpidd are run as user processes, they have the same SELinux context. If one is run as a service, and the other is run as a user process, they have different SELinux contexts.
+ </p></div><p>
+ The following options are available for clustering:
+ </p><div class="table"><a name="tabl-Messaging_User_Guide-Starting_a_Broker_in_a_Cluster-Options_for_High_Availability_Messaging_Cluster"></a><p class="title"><b>Table 1.8. Options for High Availability Messaging Cluster</b></p><div class="table-contents"><table summary="Options for High Availability Messaging Cluster" border="1"><colgroup><col align="left"><col align="left"></colgroup><thead><tr><th colspan="2" align="center">
+ Options for High Availability Messaging Cluster
+ </th></tr></thead><tbody><tr><td align="left">
+ <span class="command"><strong>--cluster-name <em class="replaceable"><code>NAME</code></em></strong></span>
+ </td><td align="left">
+ Name of the Messaging Cluster to join. A Messaging Cluster consists of all brokers started with the same cluster-name and openais configuration.
+ </td></tr><tr><td align="left">
+ <span class="command"><strong>--cluster-size <em class="replaceable"><code>N</code></em></strong></span>
+ </td><td align="left">
+ Wait for at least N initial members before completing cluster initialization and serving clients. Use this option in a persistent cluster so all brokers in a persistent cluster can exchange the status of their persistent store and do consistency checks before serving clients.
+ </td></tr><tr><td align="left">
+ <span class="command"><strong>--cluster-url <em class="replaceable"><code>URL</code></em></strong></span>
+ </td><td align="left">
+ An AMQP URL containing the local address that the broker advertizes to clients for fail-over connections. This is different for each host. By default, all local addresses for the broker are advertized. You only need to set this if
+ <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
+ Your host has more than one active network interface, and
+ </p></li><li class="listitem"><p>
+ You want to restrict client fail-over to a specific interface or interfaces.
+ </p></li></ol></div>
+ <p>Each broker in the cluster is specified using the following form:</p>
+
+<pre class="programlisting">url = ["amqp:"][ user ["/" password] "@" ] protocol_addr
+ ("," protocol_addr)*
+protocol_addr = tcp_addr / rmda_addr / ssl_addr / ...
+tcp_addr = ["tcp:"] host [":" port]
+rdma_addr = "rdma:" host [":" port]
+ssl_addr = "ssl:" host [":" port]</pre>
+
+ <p>In most cases, only one address is advertized, but more than one address can be specified in if the machine running the broker has more than one network interface card, and you want to allow clients to connect using multiple network interfaces. Use a comma delimiter (",") to separate brokers in the URL. Examples:</p>
+ <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+ <span class="command"><strong>amqp:tcp:192.168.1.103:5672</strong></span> advertizes a single address to the broker for failover.
+ </p></li><li class="listitem"><p>
+ <span class="command"><strong>amqp:tcp:192.168.1.103:5672,tcp:192.168.1.105:5672</strong></span> advertizes two different addresses to the broker for failover, on two different network interfaces.
+ </p></li></ul></div>
+
+ </td></tr><tr><td align="left">
+ <span class="command"><strong>--cluster-cman</strong></span>
+ </td><td align="left">
+ <p>
+ CMAN protects against the "split-brain" condition, in which a network failure splits the cluster into two sub-clusters that cannot communicate with each other. When "split-brain" occurs, each of the sub-clusters can access shared resources without knowledge of the other sub-cluster, resulting in corrupted cluster integrity.
+ </p>
+ <p>
+ To avoid "split-brain", CMAN uses the notion of a "quorum". If more than half the cluster nodes are active, the cluster has quorum and can act. If half (or fewer) nodes are active, the cluster does not have quorum, and all cluster activity is stopped. There are other ways to define the quorum for particular use cases (e.g. a cluster of only 2 members), see the <a class="ulink" href="http://sources.redhat.com/cluster/wiki" target="_top">CMAN Wiki</a>
+for more detail.
+ </p>
+ <p>
+ When enabled, the broker will wait until it belongs to a quorate cluster before accepting client connections. It continually monitors the quorum status and shuts down immediately if the node it runs on loses touch with the quorum.
+ </p>
+
+ </td></tr><tr><td align="left">
+ --cluster-username
+ </td><td align="left">
+ SASL username for connections between brokers.
+ </td></tr><tr><td align="left">
+ --cluster-password
+ </td><td align="left">
+ SASL password for connections between brokers.
+ </td></tr><tr><td align="left">
+ --cluster-mechanism
+ </td><td align="left">
+ SASL authentication mechanism for connections between brokers
+ </td></tr></tbody></table></div></div><br class="table-break"><p>
+ If a broker is unable to establish a connection to another broker in the cluster, the log will contain SASL errors, e.g:
+ </p><pre class="screen">2009-aug-04 10:17:37 info SASL: Authentication failed: SASL(-13): user not found: Password verification failed
+</pre><p>
+ You can set the SASL user name and password used to connect to other brokers using the <span class="command"><strong>cluster-username</strong></span> and <span class="command"><strong>cluster-password</strong></span> properties when you start the broker. In most environment, it is easiest to create an account with the same user name and password on each broker in the cluster, and use these as the <span class="command"><strong>cluster-username</strong></span> and <span class="command"><strong>cluster-password</strong></span>. You can also set the SASL mode using <span class="command"><strong>cluster-mechanism</strong></span>. Remember that any mechanism you enable for broker-to-broker communication can also be used by a client, so do not enable <span class="command"><strong>cluster-mechanism=ANONYMOUS</strong></span> in a secure environment.
+ </p><p>
+ Once the cluster is running, run <span class="command"><strong>qpid-cluster</strong></span> to make sure that the brokers are running as one cluster. See the following section for details.
+ </p><p>
+ If the cluster is correctly configured, queues and messages are replicated to all brokers in the cluster, so an easy way to test the cluster is to run a program that routes messages to a queue on one broker, then connect to a different broker in the same cluster and read the messages to make sure they have been replicated. The <span class="command"><strong>drain</strong></span> and <span class="command"><strong>spout</strong></span> programs can be used for this test.
+ </p></div><div class="section" title="1.8.2. qpid-cluster"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-qpid_cluster"></a>1.8.2. qpid-cluster</h3></div></div></div><p>
+ <span class="command"><strong>qpid-cluster</strong></span> is a command-line utility that allows you to view information on a cluster and its brokers, disconnect a client connection, shut down a broker in a cluster, or shut down the entire cluster. You can see the options using the <span class="command"><strong>--help</strong></span> option:
+ </p><pre class="screen">$ ./qpid-cluster --help
+</pre><pre class="screen">Usage: qpid-cluster [OPTIONS] [broker-addr]
+
+ broker-addr is in the form: [username/password@] hostname | ip-address [:<port>]
+ ex: localhost, 10.1.1.7:10000, broker-host:10000, guest/guest@localhost
+
+Options:
+ -C [--all-connections] View client connections to all cluster members
+ -c [--connections] ID View client connections to specified member
+ -d [--del-connection] HOST:PORT
+ Disconnect a client connection
+ -s [--stop] ID Stop one member of the cluster by its ID
+ -k [--all-stop] Shut down the whole cluster
+ -f [--force] Suppress the 'are-you-sure?' prompt
+ -n [--numeric] Don't resolve names
+</pre><p>
+ Let's connect to a cluster and display basic information about the cluser and its brokers. When you connect to the cluster using <span class="command"><strong>qpid-tool</strong></span>, you can use the host and port for any broker in the cluster. For instance, if a broker in the cluster is running on <code class="filename">localhost</code> on port 6664, you can start <span class="command"><strong>qpid-tool</strong></span> like this:
+ </p><pre class="screen">
+$ qpid-cluster localhost:6664
+</pre><p>
+ Here is the output:
+ </p><pre class="screen">
+ Cluster Name: local_test_cluster
+Cluster Status: ACTIVE
+ Cluster Size: 3
+ Members: ID=127.0.0.1:13143 URL=amqp:tcp:192.168.1.101:6664,tcp:192.168.122.1:6664,tcp:10.16.10.62:6664
+ : ID=127.0.0.1:13167 URL=amqp:tcp:192.168.1.101:6665,tcp:192.168.122.1:6665,tcp:10.16.10.62:6665
+ : ID=127.0.0.1:13192 URL=amqp:tcp:192.168.1.101:6666,tcp:192.168.122.1:6666,tcp:10.16.10.62:6666
+</pre><p>
+ The ID for each broker in cluster is given on the left. For instance, the ID for the first broker in the cluster is <span class="command"><strong>127.0.0.1:13143</strong></span>. The URL in the output is the broker's advertized address. Let's use the ID to shut the broker down using the <span class="command"><strong>--stop</strong></span> command:
+ </p><pre class="screen">$ ./qpid-cluster localhost:6664 --stop 127.0.0.1:13143
+</pre></div><div class="section" title="1.8.3. Failover in Clients"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Failover_in_Clients"></a>1.8.3. Failover in Clients</h3></div></div></div><p>
+ If a client is connected to a broker, the connection fails if the broker crashes or is killed. If heartbeat is enabled for the connection, a connection also fails if the broker hangs, the machine the broker is running on fails, or the network connection to the broker is lost — the connection fails no later than twice the heartbeat interval.
+ </p><p>
+ When a client's connection to a broker fails, any sent messages that have been acknowledged to the sender will have been replicated to all brokers in the cluster, any received messages that have not yet been acknowledged by the receiving client requeued to all brokers, and the client API notifies the application of the failure by throwing an exception.
+ </p><p>
+ Clients can be configured to automatically reconnect to another broker when it receives such an exception. Any messages that have been sent by the client, but not yet acknowledged as delivered, are resent. Any messages that have been read by the client, but not acknowledged, are delivered to the client.
+ </p><p>
+ TCP is slow to detect connection failures. A client can configure a connection to use a heartbeat to detect connection failure, and can specify a time interval for the heartbeat. If heartbeats are in use, failures will be detected no later than twice the heartbeat interval. The Java JMS client enables hearbeat by default. See the sections on Failover in Java JMS Clients and Failover in C++ Clients for the code to enable heartbeat.
+ </p><div class="section" title="1.8.3.1. Failover in Java JMS Clients"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Failover_in_Clients-Failover_in_Java_JMS_Clients"></a>1.8.3.1. Failover in Java JMS Clients</h4></div></div></div><p>
+ In Java JMS clients, client failover is handled automatically if it is enabled in the connection. Any messages that have been sent by the client, but not yet acknowledged as delivered, are resent. Any messages that have been read by the client, but not acknowledged, are sent to the client.
+ </p><p>
+ You can configure a connection to use failover using the <span class="command"><strong>failover</strong></span> property:
+ </p><pre class="screen">
+connectionfactory.qpidConnectionfactory = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672'&failover='failover_exchange'
+</pre><p>
+ This property can take three values:
+ </p><div class="variablelist" title="Failover Modes"><a name="vari-Messaging_User_Guide-Failover_in_Java_JMS_Clients-Failover_Modes"></a><p class="title"><b>Failover Modes</b></p><dl><dt><span class="term">failover_exchange</span></dt><dd><p>
+ If the connection fails, fail over to any other broker in the cluster.
+ </p></dd><dt><span class="term">roundrobin</span></dt><dd><p>
+ If the connection fails, fail over to one of the brokers specified in the <span class="command"><strong>brokerlist</strong></span>.
+ </p></dd><dt><span class="term">singlebroker</span></dt><dd><p>
+ Failover is not supported; the connection is to a single broker only.
+ </p></dd></dl></div><p>
+ In a Connection URL, heartbeat is set using the <span class="command"><strong>idle_timeout</strong></span> property, which is an integer corresponding to the heartbeat period in seconds. For instance, the following line from a JNDI properties file sets the heartbeat time out to 3 seconds:
+ </p><pre class="screen">
+connectionfactory.qpidConnectionfactory = amqp://guest:guest@clientid/test?brokerlist='tcp://localhost:5672',idle_timeout=3
+</pre></div><div class="section" title="1.8.3.2. Failover and the Qpid Messaging API"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Failover_in_Clients-Failover_and_the_Qpid_Messaging_API"></a>1.8.3.2. Failover and the Qpid Messaging API</h4></div></div></div><p>
+ The Qpid Messaging API also supports automatic reconnection in the event a connection fails. . Senders can also be configured to replay any in-doubt messages (i.e. messages whice were sent but not acknowleged by the broker. See "Connection Options" and "Sender Capacity and Replay" in <em class="citetitle">Programming in Apache Qpid</em> for details.
+ </p><p>
+ In C++ and python clients, heartbeats are disabled by default. You can enable them by specifying a heartbeat interval (in seconds) for the connection via the 'heartbeat' option.
+ </p><p>
+ See "Cluster Failover" in <em class="citetitle">Programming in Apache Qpid</em> for details on how to keep the client aware of cluster membership.
+ </p></div></div><div class="section" title="1.8.4. Error handling in Clusters"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Error_handling_in_Clusters"></a>1.8.4. Error handling in Clusters</h3></div></div></div><p>
+ If a broker crashes or is killed, or a broker machine failure, broker connection failure, or a broker hang is detected, the other brokers in the cluster are notified that it is no longer a member of the cluster. If a new broker is joined to the cluster, it synchronizes with an active broker to obtain the current cluster state; if this synchronization fails, the new broker exit the cluster and aborts.
+ </p><p>
+ If a broker becomes extremely busy and stops responding, it stops accepting incoming work. All other brokers continue processing, and the non-responsive node caches all AIS traffic. When it resumes, the broker completes processes all cached AIS events, then accepts further incoming work.
+ </p><p>
+ Broker hangs are only detected if the watchdog plugin is loaded and the <span class="command"><strong>--watchdog-interval</strong></span> option is set. The watchdog plug-in kills the qpidd broker process if it becomes stuck for longer than the watchdog interval. In some cases, e.g. certain phases of error resolution, it is possible for a stuck process to hang other cluster members that are waiting for it to send a message. Using the watchdog, the stuck process is terminated and removed from the cluster, allowing other members to continue and clients of the stuck process to fail over to other members.
+ </p><p>
+ Redundancy can also be achieved directly in the AIS network by specifying more than one network interface in the AIS configuration file. This causes Totem to use a redundant ring protocol, which makes failure of a single network transparent.
+ </p><p>
+ Redundancy can be achieved at the operating system level by using NIC bonding, which combines multiple network ports into a single group, effectively aggregating the bandwidth of multiple interfaces into a single connection. This provides both network load balancing and fault tolerance.
+ </p><p>
+ If any broker encounters an error, the brokers compare notes to see if they all received the same error. If not, the broker removes itself from the cluster and shuts itself down to ensure that all brokers in the cluster have consistent state. For instance, a broker may run out of disk space; if this happens, the broker shuts itself down. Examining the broker's log can help determine the error and suggest ways to prevent it from occuring in the future.
+ </p></div><div class="section" title="1.8.5. Persistence in High Availability Message Clusters"><div class="titlepage"><div><div><h3 class="title"><a name="sect-Messaging_User_Guide-High_Availability_Messaging_Clusters-Persistence_in_High_Availability_Message_Clusters"></a>1.8.5. Persistence in High Availability Message Clusters</h3></div></div></div><p>
+ Persistence and clustering are two different ways to provide reliability. Most systems that use a cluster do not enable persistence, but you can do so if you want to ensure that messages are not lost even if the last broker in a cluster fails. A cluster must have all transient or all persistent members, mixed clusters are not allowed. Each broker in a persistent cluster has it's own independent replica of the cluster's state it its store.
+ </p><div class="section" title="1.8.5.1. Clean and Dirty Stores"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Persistence_in_High_Availability_Message_Clusters-Clean_and_Dirty_Stores"></a>1.8.5.1. Clean and Dirty Stores</h4></div></div></div><p>
+ When a broker is an active member of a cluster, its store is marked "dirty" because it may be out of date compared to other brokers in the cluster. If a broker leaves a running cluster because it is stopped, it crashes or the host crashes, its store continues to be marked "dirty".
+ </p><p>
+ If the cluster is reduced to a single broker, its store is marked "clean" since it is the only broker making updates. If the cluster is shut down with the command <code class="literal">qpid-cluster -k</code> then all the stores are marked clean.
+ </p><p>
+ When a cluster is initially formed, brokers with clean stores read from their stores. Brokers with dirty stores, or brokers that join after the cluster is running, discard their old stores and initialize a new store with an update from one of the running brokers. The <span class="command"><strong>--truncate</strong></span> option can be used to force a broker to discard all existing stores even if they are clean. (A dirty store is discarded regardless.)
+ </p><p>
+ Discarded stores are copied to a back up directory. The active store is in <data-dir>/rhm. Back-up stores are in <data-dir>/_cluster.bak.<nnnn>/rhm, where <nnnn> is a 4 digit number. A higher number means a more recent backup.
+ </p></div><div class="section" title="1.8.5.2. Starting a persistent cluster"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Persistence_in_High_Availability_Message_Clusters-Starting_a_persistent_cluster"></a>1.8.5.2. Starting a persistent cluster</h4></div></div></div><p>
+ When starting a persistent cluster broker, set the cluster-size option to the number of brokers in the cluster. This allows the brokers to wait until the entire cluster is running so that they can synchronize their stored state.
+ </p><p>
+ The cluster can start if:
+ </p><p>
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>
+ all members have empty stores, or
+ </p></li><li class="listitem"><p>
+ at least one member has a clean store
+ </p></li></ul></div><p>
+
+ </p><p>
+ All members of the new cluster will be initialized with the state from a clean store.
+ </p></div><div class="section" title="1.8.5.3. Stopping a persistent cluster"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Persistence_in_High_Availability_Message_Clusters-Stopping_a_persistent_cluster"></a>1.8.5.3. Stopping a persistent cluster</h4></div></div></div><p>
+ To cleanly shut down a persistent cluster use the command <span class="command"><strong>qpid-cluster -k</strong></span>. This causes all brokers to synchronize their state and mark their stores as "clean" so they can be used when the cluster restarts.
+ </p></div><div class="section" title="1.8.5.4. Starting a persistent cluster with no clean store"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Persistence_in_High_Availability_Message_Clusters-Starting_a_persistent_cluster_with_no_clean_store"></a>1.8.5.4. Starting a persistent cluster with no clean store</h4></div></div></div><p>
+ If the cluster has previously had a total failure and there are no clean stores then the brokers will fail to start with the log message <code class="literal">Cannot recover, no clean store.</code> If this happens you can start the cluster by marking one of the stores "clean" as follows:
+ </p><div class="procedure"><ol class="procedure" type="1"><li class="step" title="Step 1"><p>
+ Move the latest store backup into place in the brokers data-directory. The backups end in a 4 digit number, the latest backup is the highest number.
+ </p><pre class="screen">
+ cd <data-dir>
+ mv rhm rhm.bak
+ cp -a _cluster.bak.<nnnn>/rhm .
+</pre></li><li class="step" title="Step 2"><p>
+ Mark the store as clean:
+</p><pre class="screen">qpid-cluster-store -c <data-dir></pre><p>
+
+ </p></li></ol></div><p>
+ Now you can start the cluster, all members will be initialized from the store you marked as clean.
+ </p></div><div class="section" title="1.8.5.5. Isolated failures in a persistent cluster"><div class="titlepage"><div><div><h4 class="title"><a name="sect-Messaging_User_Guide-Persistence_in_High_Availability_Message_Clusters-Isolated_failures_in_a_persistent_cluster"></a>1.8.5.5. Isolated failures in a persistent cluster</h4></div></div></div><p>
+ A broker in a persistent cluster may encounter errors that other brokers in the cluster do not; if this happens, the broker shuts itself down to avoid making the cluster state inconsistent. For example a disk failure on one node will result in that node shutting down. Running out of storage capacity can also cause a node to shut down because because the brokers may not run out of storage at exactly the same point, even if they have similar storage configuration. To avoid unnecessary broker shutdowns, make sure the queue policy size of each durable queue is less than the capacity of the journal for the queue.
+ </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s07.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch01s09.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.7.
+ Queue State Replication
+ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 1.9.
+ Producer Flow Control
+ </td></tr></table></div></body></html>
Added: qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s09.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s09.html?rev=1097544&view=auto
==============================================================================
--- qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s09.html (added)
+++ qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s09.html Thu Apr 28 16:49:49 2011
@@ -0,0 +1,187 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>1.9. Producer Flow Control</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in C++)"><link rel="up" href="ch01.html" title="Chapter 1. Running the AMQP Messaging Broker"><link rel="prev" href="ch01s08.html" title="1.8. High Availability Messaging Clusters"><link rel="next" href="ch01s10.html" title="1.10. AMQP compatibility"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">1.9.
+ Producer Flow Control
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch01s08.html">Prev</a> </td><th width="60%" align="center">Chapter 1.
+ Running the AMQP Messaging Broker
+ </th><td width="20%" align="right"> <a accesskey="n" href="ch01s10.html">Next</a></td></tr></table><hr></div><div class="section" title="1.9. Producer Flow Control"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="producer-flow-control"></a>1.9.
+ Producer Flow Control
+ </h2></div></div></div><div class="section" title="1.9.1. Overview"><div class="titlepage"><div><div><h3 class="title"><a name="producerflowcontrol-Overview"></a>1.9.1.
+ Overview
+ </h3></div></div></div><p>
+ 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.
+ </p><p>
+ Each queue in the C++ broker has two threshold values associated with it:
+ </p><p>
+ 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.
+ </p><p>
+ 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.
+ </p><p>
+ 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.
+ </p><p>
+ 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.
+ </p><div class="section" title="1.9.1.1. Example"><div class="titlepage"><div><div><h4 class="title"><a name="producerflowcontrol-QueueThresholdsExample"></a>1.9.1.1.
+ Example
+ </h4></div></div></div><p>
+ 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:
+ </p><p>
+ When the total number of enqueued messages is greater than or equal to
+ 900, the queue's flow control state is OFF.
+ </p><p>
+ When the total number of enqueued messages is greater than 900, the
+ queue's flow control state transitions to ON.
+ </p><p>
+ 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".
+ </p><p>
+ A similar example using total enqueued content bytes as the threshold
+ units are permitted.
+ </p></div><p>
+ Thresholds may be set using both total message counts and total byte
+ counts. In this case, the following rules apply:
+ </p><p>
+ 1) Flow control is "ON" when either stop threshold value is crossed.
+ </p><p>
+ 2) Flow control remains "ON" until both resume thresholds are satisfied.
+ </p><div class="section" title="1.9.1.2. Example"><div class="titlepage"><div><div><h4 class="title"><a name="producerflowcontro-MultiThresholdExample"></a>1.9.1.2.
+ Example
+ </h4></div></div></div><p>
+ 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).
+ </p><p>
+ 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).
+ </p></div><p>
+ 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.
+ </p><p>
+ 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.
+ </p><p>
+ 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.
+ </p><p>
+ 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.
+ </p></div><div class="section" title="1.9.2. User Interface"><div class="titlepage"><div><div><h3 class="title"><a name="producerflowcontrol-UserInterface"></a>1.9.2.
+ User Interface
+ </h3></div></div></div><p>
+ 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.
+ </p><p>
+ 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.
+ </p><p>
+ 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.
+ </p><p>
+ 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:
+ </p><pre class="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.")
+ </pre><p>
+ For example:
+ </p><pre class="programlisting">
+ qpidd --default-flow-stop-threshold=90 --default-flow-resume-threshold=75
+ </pre><p>
+ 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.
+ </p><p>
+ 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%.
+ </p><p>
+ 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.
+ </p><p>
+ The user may manually set the flow thresholds when creating a queue.
+ The following options may be provided when adding a queue using the
+ <span class="command"><strong>qpid-config</strong></span> command line tool:
+ </p><pre class="programlisting">
+ --flow-stop-size=<em class="replaceable"><code>N</code></em> Sets the queue's flow stop threshold to <em class="replaceable"><code>N</code></em> total bytes.
+ --flow-resume-size=<em class="replaceable"><code>N</code></em> Sets the queue's flow resume threshold to <em class="replaceable"><code>N</code></em> total bytes.
+ --flow-stop-count=<em class="replaceable"><code>N</code></em> Sets the queue's flow stop threshold to <em class="replaceable"><code>N</code></em> total messages.
+ --flow-resume-count=<em class="replaceable"><code>N</code></em> Sets the queue's flow resume threshold to <em class="replaceable"><code>N</code></em> total messages.
+ </pre><p>
+ Flow thresholds may also be specified in the
+ <span class="command"><strong>queue.declare</strong></span> method, via the
+ <span class="command"><strong>arguments</strong></span> parameter map. The following keys can be
+ provided in the arguments map for setting flow thresholds:
+ </p><div class="table"><a name="id2594787"></a><p class="title"><b>Table 1.9. Queue Declare Method Flow Control Arguments</b></p><div class="table-contents"><table summary="Queue Declare Method Flow Control Arguments" border="1"><colgroup><col><col></colgroup><thead><tr><th>Key</th><th>Value</th></tr></thead><tbody><tr><td>qpid.flow_stop_size</td><td>integer - queue's flow stop threshold value in bytes</td></tr><tr><td>qpid.flow_resume_size</td><td>integer - queue's flow resume threshold value in bytes</td></tr><tr><td>qpid.flow_stop_count</td><td>integer - queue's flow stop threshold value as a message count</td></tr><tr><td>qpid.flow_resume_count</td><td>integer - queue's flow resume threshold value as a message count</td></tr></tbody></table></div></div><br class="table-break"><p>
+ 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.
+ </p><p>
+ 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.
+ </p><p>
+ 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.
+ </p><div class="table"><a name="id2629099"></a><p class="title"><b>Table 1.10. Flow Control Statistics available in Queue's QMF Class</b></p><div class="table-contents"><table summary="Flow Control Statistics available in Queue's QMF Class" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Statistic Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>flowStopped</td><td>Boolean</td><td>If true, producers are blocked by flow control.</td></tr><tr><td>flowStoppedCount</td><td>count32</td><td>Number of times flow control was activated for this queue</td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s08.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch01s10.html">Next</a></td></tr><t
r><td width="40%" align="left" valign="top">1.8. High Availability Messaging Clusters </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 1.10.
+ AMQP compatibility
+ </td></tr></table></div></body></html>
Added: qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s10.html
URL: http://svn.apache.org/viewvc/qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s10.html?rev=1097544&view=auto
==============================================================================
--- qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s10.html (added)
+++ qpid/site/docs/books/0.10/AMQP-Messaging-Broker-CPP-Book/html/ch01s10.html Thu Apr 28 16:49:49 2011
@@ -0,0 +1,393 @@
+<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>1.10. AMQP compatibility</title><meta name="generator" content="DocBook XSL Stylesheets V1.75.2"><link rel="home" href="index.html" title="AMQP Messaging Broker (Implemented in C++)"><link rel="up" href="ch01.html" title="Chapter 1. Running the AMQP Messaging Broker"><link rel="prev" href="ch01s09.html" title="1.9. Producer Flow Control"><link rel="next" href="ch01s11.html" title="1.11. Qpid Interoperability Documentation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">1.10.
+ AMQP compatibility
+ </th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch01s09.html">Prev</a> </td><th width="60%" align="center">Chapter 1.
+ Running the AMQP Messaging Broker
+ </th><td width="20%" align="right"> <a accesskey="n" href="ch01s11.html">Next</a></td></tr></table><hr></div><div class="section" title="1.10. AMQP compatibility"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="AMQP-Compatibility"></a>1.10.
+ AMQP compatibility
+ </h2></div></div></div><p>
+ Qpid provides the most complete and compatible implementation
+ of AMQP. And is the most aggressive in implementing the latest
+ version of the specification.
+ </p><p>
+ There are two brokers:
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>C++ with support for AMQP 0-10</p></li><li class="listitem"><p>Java with support for AMQP 0-8 and 0-9 (0-10 planned)</p></li></ul></div><p>
+ There are client libraries for C++, Java (JMS), .Net (written in
+ C#), python and ruby.
+ </p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>All clients support 0-10 and interoperate with the C++
+ broker.
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The JMS client supports 0-8, 0-9 and 0-10 and interoperates
+ with both brokers.
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>The python and ruby clients will also support all versions,
+ but the API is dynamically driven by the specification used and
+ so differs between versions. To work with the Java broker you
+ must use 0-8 or 0-9, to work with the C++ broker you must use
+ 0-10.
+ </p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>There are two separate C# clients, one for 0-8 that
+ interoperates with the Java broker, one for 0-10 that
+ inteoperates with the C++ broker.
+ </p></li></ul></div><p>
+ QMF Management is supported in Ruby, Python, C++, and via QMan
+ for Java JMX & WS-DM.
+ </p><div class="section" title="1.10.1. AMQP Compatibility of Qpid releases:"><div class="titlepage"><div><div><h3 class="title"><a name="AMQPcompatibility-AMQPCompatibilityofQpidreleases-3A"></a>1.10.1.
+ AMQP
+ Compatibility of Qpid releases:
+ </h3></div></div></div><p>
+ Qpid implements the AMQP Specification, and as the specification
+ has progressed Qpid is keeping up with the updates. This means
+ that different Qpid versions support different versions of AMQP.
+ Here is a simple guide on what use.
+ </p><p>
+ Here is a matrix that describes the different versions supported
+ by each release. The status symbols are interpreted as follows:
+ </p><div class="variablelist"><dl><dt><span class="term">Y</span></dt><dd><p>supported</p></dd><dt><span class="term">N</span></dt><dd><p>unsupported</p></dd><dt><span class="term">IP</span></dt><dd><p>in progress</p></dd><dt><span class="term">P</span></dt><dd><p>planned</p></dd></dl></div><div class="table"><a name="id2613222"></a><p class="title"><b>Table 1.11. AMQP Version Support by Qpid Release</b></p><div class="table-contents"><table summary="AMQP Version Support by Qpid Release" border="1"><colgroup><col><col><col><col><col><col></colgroup><tbody><tr><td>
+ Component
+ </td><td>
+ Spec
+ </td><td>
+
+ </td><td>
+
+ </td><td>
+
+ </td><td>
+
+ </td></tr><tr><td>
+
+ </td><td>
+
+ </td><td>
+ M2.1
+ </td><td>
+ M3
+ </td><td>
+ M4
+ </td><td>
+ 0.5
+ </td></tr><tr><td>
+ java client
+ </td><td>
+ 0-10
+ </td><td>
+
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+
+ </td><td>
+ 0-9
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+
+ </td><td>
+ 0-8
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+ java broker
+ </td><td>
+ 0-10
+ </td><td>
+
+ </td><td>
+
+ </td><td>
+
+ </td><td>
+ P
+ </td></tr><tr><td>
+
+ </td><td>
+ 0-9
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+
+ </td><td>
+ 0-8
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+ c++ client/broker
+ </td><td>
+ 0-10
+ </td><td>
+
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+
+ </td><td>
+ 0-9
+ </td><td>
+ Y
+ </td><td>
+
+ </td><td>
+
+ </td><td>
+
+ </td></tr><tr><td>
+ python client
+ </td><td>
+ 0-10
+ </td><td>
+
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+
+ </td><td>
+ 0-9
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+
+ </td><td>
+ 0-8
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+ ruby client
+ </td><td>
+ 0-10
+ </td><td>
+
+ </td><td>
+
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+
+ </td><td>
+ 0-8
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+ C# client
+ </td><td>
+ 0-10
+ </td><td>
+
+ </td><td>
+
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+
+ </td><td>
+ 0-8
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr></tbody></table></div></div><br class="table-break"></div><div class="section" title="1.10.2. Interop table by AMQP specification version"><div class="titlepage"><div><div><h3 class="title"><a name="AMQPcompatibility-InteroptablebyAMQPspecificationversion"></a>1.10.2.
+ Interop
+ table by AMQP specification version
+ </h3></div></div></div><p>
+ Above table represented in another format.
+ </p><div class="table"><a name="id2593930"></a><p class="title"><b>Table 1.12. AMQP Version Support - alternate format</b></p><div class="table-contents"><table summary="AMQP Version Support - alternate format" border="1"><colgroup><col><col><col><col><col></colgroup><tbody><tr><td>
+
+ </td><td>
+ release
+ </td><td>
+ 0-8
+ </td><td>
+ 0-9
+ </td><td>
+ 0-10
+ </td></tr><tr><td>
+ java client
+ </td><td>
+ M3 M4 0.5
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+ java client
+ </td><td>
+ M2.1
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ N
+ </td></tr><tr><td>
+ java broker
+ </td><td>
+ M3 M4 0.5
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ N
+ </td></tr><tr><td>
+ java broker
+ </td><td>
+ trunk
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ P
+ </td></tr><tr><td>
+ java broker
+ </td><td>
+ M2.1
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ N
+ </td></tr><tr><td>
+ c++ client/broker
+ </td><td>
+ M3 M4 0.5
+ </td><td>
+ N
+ </td><td>
+ N
+ </td><td>
+ Y
+ </td></tr><tr><td>
+ c++ client/broker
+ </td><td>
+ M2.1
+ </td><td>
+ N
+ </td><td>
+ Y
+ </td><td>
+ N
+ </td></tr><tr><td>
+ python client
+ </td><td>
+ M3 M4 0.5
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td></tr><tr><td>
+ python client
+ </td><td>
+ M2.1
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ N
+ </td></tr><tr><td>
+ ruby client
+ </td><td>
+ M3 M4 0.5
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ N
+ </td></tr><tr><td>
+ ruby client
+ </td><td>
+ trunk
+ </td><td>
+ Y
+ </td><td>
+ Y
+ </td><td>
+ P
+ </td></tr><tr><td>
+ C# client
+ </td><td>
+ M3 M4 0.5
+ </td><td>
+ Y
+ </td><td>
+ N
+ </td><td>
+ N
+ </td></tr><tr><td>
+ C# client
+ </td><td>
+ trunk
+ </td><td>
+ Y
+ </td><td>
+ N
+ </td><td>
+ Y
+ </td></tr></tbody></table></div></div><br class="table-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch01s09.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ch01.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch01s11.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">1.9.
+ Producer Flow Control
+ </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 1.11. Qpid Interoperability Documentation</td></tr></table></div></body></html>
---------------------------------------------------------------------
Apache Qpid - AMQP Messaging Implementation
Project: http://qpid.apache.org
Use/Interact: mailto:commits-subscribe@qpid.apache.org