anchor.diff:  = Ring Buffer
   :toc:
   :toc-title: Contents
  -:toclevels: 2
  +:toclevels: 1
   
  -== Chronicle Ring Buffer
  +== Chronicle Queue Enterprise Ring Buffer
   
  -Chronicle Queue Enterprise Ring Buffer provides a high performance, multi-writer, multi-reader ring buffer implementation
  -which can be used in your application code. Additionally to this, it allows the ring buffer to be accessed
  -via two different implementations of the `ChronicleQueue` interface.
  +Chronicle Queue Enterprise Ring Buffer provides a high performance, multi-writer, multi-reader, ring buffer implementation which can be used in your application code.
  +
  +Additionally, it allows the ring buffer to be accessed
  +through two different implementations of the `ChronicleQueue` interface.
   
   .Chronicle Ring Buffer
   image::images/Ring_buffer.svg[]
   
   === The mechanics of Chronicle Ring Buffer
   
  -The Chronicle Queue Enterprise Ring Buffer is a multi-writer, multi-reader, zero GC, monitered, ring buffer implementation,
  -which takes `Bytes`. As the Chronicle stack is built on `Bytes` you can use the ring buffer for byte arrays,
  -packed objects, or you can (de)serialise objects out of/in to it with
  -https://github.com/OpenHFT/Chronicle-Wire[Chronicle Wire]
  +The Chronicle Queue Enterprise Ring Buffer is a multi-writer, multi-reader, zero-garbage collection, monitored ring buffer implementation which takes `Bytes`.
   
  -When you create a ring buffer then any and all readers can block all writers. If a reader stops reading
  -then this will eventually block writers. The number of readers is fixed and they are all created when the
  -RB is created (actually when the underlying BytesStore is first written to) and will live for as long as the
  -Ring Buffer (actually until you stop using the BytesStore).
  +As the Chronicle stack is built on `Bytes`, you can use the ring buffer for byte arrays, packed objects, or you can serialise (or de-serialise objects out of, or into, it using
  +https://github.com/OpenHFT/Chronicle-Wire[Chronicle Wire].
   
  -Backing the RB with a persistent BytesStore (i.e. one backed with a memory-mapped file) means it will be visible to
  -multiple processes and all processes can write to and all read from the RB.
  +When you create a ring buffer then any reader can block all writers. If a reader stops reading
  +then this will eventually block writers. The number of readers is fixed, and they are all created when the ring buffer is created; when the underlying BytesStore is first written-to. The readers will live for as long as the ring buffer; until you stop using the BytesStore.
   
  -Common scenarios:
  -1. back the ring buffer with an in-memory BytesStore and you can have multiple writers and multiple readers in
  -the same process. The ring buffer does not survive longer than the process.
  -2. back the ring buffer with an memory-mapped BytesStore and you can have multiple writers and multiple readers in
  -multiple processes. The ring buffer's data can outlast individual processes.
  +Backing the ring buffer with a persistent BytesStore (that is, one backed with a memory-mapped file) means it will be visible to multiple processes. All processes can write to, and read from, the ring buffer.
   
  -To use the basic ring buffer, first one must be created by calling `newInstance`. Note that the number of readers
  -must be specified up-front. If not provided the number of readers is assumed to be 1. The BytesStore must be an
  -implementation of NativeBytesStore and must be sized appropriately by using the `sizeFor` method (note that base
  -size must be a power of 2).
  +==== Common scenarios:
  +- Back the ring buffer with an in-memory BytesStore. +
  +You can have multiple writers and multiple readers in the same process. The ring buffer does not survive longer than the process.
  +
  +- Back the ring buffer with a memory-mapped BytesStore. +
  +You can have multiple writers and multiple readers in multiple processes. The ring buffer's data can outlast individual processes.
  +
  +To use the basic ring buffer, you must create it by calling `newInstance`.
  +
  +NOTE: The number of readers must be specified at creation. If not provided, the number of readers is assumed to be `1`. The `BytesStore` must be an
  +implementation of `NativeBytesStore`, and must be sized appropriately by using the `sizeFor` method. The base size must be a power of `2`.
   
   ```
     int size = BytesRingBuffer.sizeFor(2 << 20);
  
positive.code:   MultiReaderBytesRingBuffer ringBuffer2 = newInstance(nativeStore2, numReaders)
  ```
  
  And once created, can be written to with `offer` (multiple threads can call `offer` at the "same" time). If
  `offer` returns false it means that the queue is full and we are waiting for one or more readers.
  
  ```
    boolean succeeded = ringBuffer.offer(bytesToWrite);
  ```
  
  And when `offer` has returned, the data is available for all readers to consume. The `read` method consumes from
  the ring buffer into the passed `BytesStore` and returns a success boolean indicating whether anything was read.
  If the queue is empty, false will be returned.
  
  ```
    boolean succeeded = ringBuffer.read(bytesToRead);
  
negative.code: 
  === Chronicle Ring Buffer and Chronicle Queue
  
  There are two types of Chronicle Queue which are backed by the ring buffer:
  
  - `software.chronicle.enterprise.queue.RingBufferChronicleQueue`
  - `software.chronicle.enterprise.queue.EnterpriseSingleChronicleQueue`
  
  ==== software.chronicle.enterprise.queue.RingBufferChronicleQueue
  
  This queue does not implement the full contract of `ChronicleQueue`, and will throw a `UnsupportedOperationException`
  from some methods. It is created as in the example below, where:
  
  - `ringBuffer` is the ring buffer to back this queue with,
  - `wireType` is the wire type to use when appending and tailing,
  - `pauser` is the pauser to use by the appender when waiting for readers.
  
  ```
      ChronicleQueue rbq = new RingBufferChronicleQueue(ringBuffer, wireType, pauser);
  ```
  
  It can be used in the same way as any other Chronicle Queue implementation.
  
  ==== software.chronicle.enterprise.queue.EnterpriseSingleChronicleQueue
  
  The ring buffer can be used in one of two ways in EnterpriseSingleChronicleQueue, and this is controlled by
  the builder's `readBufferMode` and `writeBufferMode`.
  
  - Asynchronous writes
  - Writes and reads using ring buffer
  
  ===== Asynchronous writes
  
  If `writeBufferMode` is set to `BufferMode.Asynchronous` then any writes to the queue will be given to the ring buffer. A background task is created in the builder's event loop to drain the ring buffer in to the underlying (disk-backed) chronicle queue. Reads are made from the underlying queue. This use-case is designed to help with very "bursty" writes, which cannot afford to be blocked by a slow underlying disk sub-system. The ring buffer's buffer size must be carefully chosen to allow for the maxmimum burst size.
  
  ====== Example:
  
  ```
      try (ChronicleQueue queue = EnterpriseChronicleQueueBuilder
  