[#2132] Text edits

doc/sphinx/arm/congestion-handling.rst

@@ -18,32 +18,30 @@ continue to retry forever. In the former case, the server may eventually
 recover, but the latter case is a vicious cycle from which the server is
 unable to escape.
 
-In a well-planned deployment, the number and capacity of servers is
+Congestion typically occurs when there is a network event that causes overly large
-matched to the maximum client loads expected. As long as capacity is
-matched to load, congestion does not occur. If the load is routinely too
-heavy, then the deployment needs to be re-evaluated. Congestion
-typically occurs when there is a network event that causes overly large
 numbers of clients to simultaneously need leases, such as recovery after
-a network outage.
+a network outage. In a well-planned deployment, the number and capacity of servers is
+matched to the maximum expected client load. If the load is routinely too
+heavy, then the deployment needs to be re-evaluated. 
 
 The goal of congestion handling is to help servers mitigate the peak in
 traffic by fulfilling as many of the most relevant requests as possible
 until the congestion subsides.
 
-Prior to Kea 1.5, kea-dhcp4 and kea-dhcp6 read inbound packets directly
-from the interface sockets in the main application thread, which meant
-that packets waiting to be processed were held in socket buffers
-themselves. Once these buffers filled, any new packets were discarded.
-Under swamped conditions, the servers ended up processing client packets
-that were no longer relevant, or worse, were redundant. In other words,
-the packets waiting in the FIFO socket buffers became increasingly
-stale.
-
 .. _congestion-handling-solution:
 
 Configuring Congestion Handling
 ===============================
 
+Prior to Kea 1.5, ``kea-dhcp4`` and ``kea-dhcp6`` read inbound packets directly
+from the interface sockets in the main application thread, which meant
+that packets waiting to be processed were held in socket buffers.
+Once these buffers filled, any new packets were discarded.
+Under swamped conditions, the servers ended up processing client packets
+that were no longer relevant, or worse, were redundant. In other words,
+the packets waiting in the first-in, first-out (FIFO) socket buffers became increasingly
+stale.
+
 Kea 1.5 introduced the Congestion Handling feature. Congestion handling
 offers the ability to configure the server to use a separate thread to
 read packets from the interface socket buffers. As the thread reads
@@ -54,26 +52,26 @@ configurable layer has been introduced which can make decisions on which
 packets to process, how to store them, and the order in which they are
 processed by the server.
 
-The default packet queue implementation for both kea-dhcp4 and kea-dhcp6
+The default packet queue implementation for both ``kea-dhcp4`` and ``kea-dhcp6``
 is a simple ring buffer. Once it reaches capacity, new packets get added
 to the back of the queue by discarding packets from the front of the
 queue. Rather than always discarding the newest packets, Kea now always
 discards the oldest packets. The capacity of the buffer, i.e. the maximum
 number of packets the buffer can contain, is configurable. A reasonable
-starting point would be to match the capacity to the number of leases
+starting point is to match the capacity to the number of leases
-per second a specific installation of Kea can handle. Please note that this
+per second a specific installation of Kea can handle. This
 figure varies widely depending on the specifics of an individual deployment.
 
-As there is no one algorithm that will best handle the dynamics of all
+As there is no one algorithm that can best handle the dynamics of all
 sites, and because over time new approaches will evolve, the packet
 queue is implemented as a plug-in, which can be replaced by a custom queue
 implementation via a hook library. This should make it straightforward
 for interested parties to experiment with their own solutions.
-(Developers can refer to isc::dhcp::PacketQueue and
+(Developers can refer to ``isc::dhcp::PacketQueue`` and
-isc::dhcp::PacketQueueMgr, described in the
+``isc::dhcp::PacketQueueMgr``, described in the
 `Kea Developer's Guide <https://reports.kea.isc.org/dev_guide/index.html>`__.)
 
-Packet queue behavior is configured in both kea-dhcp4 and kea-dhcp6
+Packet queue behavior is configured in both ``kea-dhcp4`` and ``kea-dhcp6``
 servers through an optional, top-level, configuration element,
 ``dhcp-queue-control``. Omitting this element disables packet queueing:
 
@@ -87,24 +85,24 @@ servers through an optional, top-level, configuration element,
 
 where:
 
--  ``enable-queue`` true|false - enables or disables packet queueing.
+-  ``enable-queue`` - enables or disables packet queueing.
-   When true, the server processes packets from the packet queue, which
+   When "true", the server processes packets from the packet queue, which
-   is filled by a separate thread. When false, the server processes
+   is filled by a separate thread. When "false", the server processes
    packets directly from the socket buffers in the main thread. It is
-   disabled by default.
+   disabled ("false") by default.
 
--  ``queue-type`` - name of the queue implementation to use. This value
+-  ``queue-type`` - the name of the queue implementation to use. This value
    exists so that custom implementations can be registered (via a hook
    library) and then selected. There is a default packet queue
    implementation that is pre-registered during server start up:
-   "kea-ring4" for kea-dhcp4 and "kea-ring6" for kea-dhcp6.
+   "kea-ring4" for ``kea-dhcp4`` and "kea-ring6" for ``kea-dhcp6``.
 
--  ``capacity`` = n [packets] - this is the maximum number of packets the
+-  ``capacity`` - this is the maximum number of packets the
    queue can hold before packets are discarded. The optimal value for
    this is extremely site-dependent. The default value is 64 for both
-   kea-ring4 and kea-ring6.
+   "kea-ring4" and "kea-ring6".
 
-The following example enables the default packet queue for kea-dhcp4,
+The following example enables the default packet queue for ``kea-dhcp4``,
 with a queue capacity of 250 packets:
 
 ::
@@ -120,7 +118,7 @@ with a queue capacity of 250 packets:
        ...
    }
 
-The following example enables the default packet queue for kea-dhcp6,
+The following example enables the default packet queue for ``kea-dhcp6``,
 with a queue capacity of 300 packets:
 
 ::
@@ -138,5 +136,5 @@ with a queue capacity of 300 packets:
 
 .. note:
 
-   Currently the congestion handling is incompatible with multi-threading:
+   Congestion handling is currently incompatible with multi-threading;
-   when both are enabled the congestion handling is silently disabled.
+   when both are enabled, congestion handling is silently disabled.