jbertram commented on a change in pull request #2802: ARTEMIS-2457 implement ring queue URL: https://github.com/apache/activemq-artemis/pull/2802#discussion_r316256563
########## File path: docs/user-manual/en/ring-queue.md ########## @@ -0,0 +1,99 @@ +# Ring Queue + +Queues operate with first-in, first-out (FIFO) semantics which means that +messages, in general, are added to the "tail" of the queue and removed from the +"head." A "ring" queue is a special type of queue with a *fixed* size. The +fixed size is maintained by removing the message at the head of the queue when +the number of messages on the queue reaches the configured size. + +For example, consider a queue configured with a ring size of 3 and a producer +which sends the messages `A`, `B`, `C`, & `D` in that order. Once `C` is sent +the number of messages in the queue will be 3 which is the same as the +configured ring size. We can visualize the queue growth like this... + +After `A` is sent: +``` + |---| +head/tail -> | A | + |---| +``` + +After `B` is sent: + +``` + |---| +head -> | A | + |---| +tail -> | B | + |---| +``` + +After `C` is sent: + +``` + |---| +head -> | A | + |---| + | B | + |---| +tail -> | C | + |---| +``` + +When `D` is sent it will be added to the tail of the queue and the message at +the head of the queue (i.e. `A`) will be removed so the queue will look like +this: + +``` + |---| +head -> | B | + |---| + | C | + |---| +tail -> | D | + |---| +``` + +This example covers the most basic use case with messages being added to the +tail of the queue. However, there are a few other important use cases +involving: + + - Messages in delivery + - Rolled back messages + - Scheduled messages + - Paging + +However, before we get to those use cases let's look at the basic configuration +of a ring queue. + +## Configuration + +There are 2 parameters related to ring queue configuration. + +The `ring-size` parameter can be set directly on the `queue` element. The +default value is `-1` (i.e. no limit). + +```xml +<address name="myRing"> + <anycast> + <queue name="myRing" ring-size="3" /> + </anycast> +</address> +``` + +The `default-ring-size` is an `address-setting` which applies to queues on +matching addresses which don't have an explicit `ring-size` set. This is +especially useful for auto-created queues. Review comment: Will fix. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
