RatePolicy documentation

doc/qbk/07_concepts/0_concepts.qbk

@@ -19,6 +19,7 @@ This section describes all of the concepts defined by the library.
 [include Fields.qbk]
 [include FieldsWriter.qbk]
 [include File.qbk]
+[include RatePolicy.qbk]
 [include Streams.qbk]
 
 [endsect]

doc/qbk/07_concepts/RatePolicy.qbk

@@ -0,0 +1,124 @@
+[/
+    Copyright (c) 2019 Vinnie Falco (vinnie dot falco at gmail dot com)
+
+    Distributed under the Boost Software License, Version 1.0. (See accompanying
+    file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+
+    Official repository: https://github.com/boostorg/beast
+]
+
+[section:RatePolicy RatePolicy]
+
+An instance of [*RatePolicy] is associated with a
+[link beast.ref.boost__beast__basic_stream `basic_stream`],
+and controls the rate at which bytes may be independently sent and
+received. This may be used to achieve fine-grained bandwidth management
+and flow control.
+
+[heading Associated Types]
+
+* [link beast.ref.boost__beast__rate_policy_access `rate_policy_access`]
+
+[warning
+    These requirements may undergo non-backward compatible
+    changes in subsequent versions.
+]
+
+[heading Requirements]
+
+In this table:
+
+* `P` denotes a type that meets the requirements of [*RatePolicy].
+* `x` denotes an xvalue of type `P`
+* `a` denotes a value of type `P`.
+* `n` denotes a value of type `std::size_t`
+
+[table Valid expressions
+[[Expression] [Type] [Semantics, Pre/Post-conditions]]
+[
+    [`P a(x)`]
+    []
+    [
+        Requires ['MoveConstructible].
+    ]
+][
+    [`friend rate_policy_access`]
+    []
+    [
+        The member functions required in `P` should be private.
+        [link beast.ref.boost__beast__rate_policy_access `rate_policy_access`]
+        must be a friend of `P` for the implementation to gain access
+        to the required member functions.
+    ]
+][
+    [`a.available_read_bytes()`]
+    [`std::size_t`]
+    [
+        This function is called by the implementation to determine
+        the maximum number of allowed bytes to be transferred
+        in the next read operation. The actual number of bytes
+        subsequently transferred may be less than this number.
+        
+        If the policy returns a value of zero, the read operation
+        will asynchronously wait until the next timer interval
+        before retrying. When the retry occurs, this function will
+        be called again.
+    ]
+][
+    [`a.available_write_bytes()`]
+    [`std::size_t`]
+    [
+        This function is called by the implementation to determine
+        the maximum number of allowed bytes to be transferred
+        in the next write operation. The actual number of bytes
+        subsequently transferred may be less than this number.
+        
+        If the policy returns a value of zero, the read operation
+        will asynchronously wait until the next timer interval
+        before retrying. When the retry occurs, this function will
+        be called again.
+    ]
+][
+    [`a.transfer_read_bytes(n)`]
+    []
+    [
+        The implementation calls this function to inform the
+        policy that `n` bytes were successfully transferred
+        in the most recent read operation. The policy object
+        may optionally use this information to calculate
+        throughputs and/or inform the algorithm used to
+        determine subsequently queried transfer maximums.
+    ]
+][
+    [`a.transfer_write_bytes(n)`]
+    []
+    [
+        The implementation calls this function to inform the
+        policy that `n` bytes were successfully transferred
+        in the most recent write operation. The policy object
+        may optionally use this information to calculate
+        throughputs and/or inform the algorithm used to
+        determine subsequently queried transfer limits.
+    ]
+][
+    [`a.on_timer()`]
+    []
+    [
+        The implementation calls this function every time the
+        internal timer expires. The policy object may optionally
+        use this opportunity to calculate elapsed time and
+        throughput, and/or inform the algorithm used to
+        determine subsequently queried transfer limits.
+    ]
+]]
+
+[heading Exemplar]
+
+[concept_RatePolicy]
+
+[heading Models]
+
+* [link beast.ref.boost__beast__simple_rate_policy `simple_rate_policy`]
+* [link beast.ref.boost__beast__unlimited_rate_policy `unlimited_rate_policy`]
+
+[endsect]

doc/qbk/main.qbk

@@ -134,6 +134,8 @@
 [import ../../test/doc/core_3_layers.cpp]
 [import ../../test/doc/websocket_3_handshake.cpp]
 
+[import ../../test/beast/core/rate_policy.cpp]
+
 [section:quickref Reference]
 '''
 <emphasis role="green">&#128946;</emphasis> indicates an item that is new in this version.

doc/qbk/quickref.xml

@@ -104,6 +104,7 @@
         <simplelist type="vert" columns="1">
           <member><link linkend="beast.concepts.streams.AsyncStream">AsyncStream</link></member>
           <member><link linkend="beast.concepts.File">File</link></member>
+          <member><link linkend="beast.concepts.RatePolicy">RatePolicy</link>&nbsp;<emphasis role="green">&#128946;</emphasis></member>
           <member><link linkend="beast.concepts.streams.Stream">Stream</link></member>
           <member><link linkend="beast.concepts.streams.SyncStream">SyncStream</link></member>
         </simplelist>

doc/xsl/class_detail.xsl

@@ -63,6 +63,9 @@
     <xsl:when test="type = 'class RangeConnectHandler'">
       <xsl:text>class __RangeConnectHandler__</xsl:text>
     </xsl:when>
+    <xsl:when test="type = 'class RatePolicy'">
+      <xsl:text>class ``[link beast.concepts.RatePolicy [*RatePolicy]]``</xsl:text>
+    </xsl:when>
     <xsl:when test="declname = 'ReadHandler' or type = 'class ReadHandler'">
       <xsl:text>class __ReadHandler__</xsl:text>
     </xsl:when>