Docs: fast-ramp two-phase queue run

3 files changed, 20 insertions, 26 deletions

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 6dcb69d47..0c4df93a7 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -4518,6 +4518,7 @@ appear in the correct order. Each flag is described in a separate item below.
 .cindex "queue" "routing"
 .cindex "routing" "whole queue before delivery"
 .cindex "first pass routing"
+.cindex "queue runner" "two phase"
 An option starting with &%-qq%& requests a two-stage queue run. In the first
 stage, the queue is scanned as if the &%queue_smtp_domains%& option matched
 every domain. Addresses are routed, local deliveries happen, but no remote
@@ -4525,6 +4526,10 @@ transports are run.
 
 .new
 Performance will be best if the &%queue_run_in_order%& option is false.
+If that is so and the &%queue_fast_ramp%& option is true then
+in the first phase of the run,
+once a threshold number of messages are routed for a given host,
+a delivery process is forked in parallel with the rest of the scan.
 .wen
 
 .cindex "hints database" "remembering routing"
@@ -14800,6 +14805,7 @@ See also the &'Policy controls'& section above.
 .row &%hold_domains%&                "hold delivery for these domains"
 .row &%local_interfaces%&            "for routing checks"
 .row &%queue_domains%&               "no immediate delivery for these"
+.row &%queue_fast ramp%&             "parallel delivery with 2-phase queue run"
 .row &%queue_only%&                  "no immediate delivery at all"
 .row &%queue_only_file%&             "no immediate delivery if file exists"
 .row &%queue_only_load%&             "no immediate delivery if load is high"
@@ -16976,6 +16982,17 @@ domains that do not match are processed. All other deliveries wait until the
 next queue run. See also &%hold_domains%& and &%queue_smtp_domains%&.
 
 
+.new
+.option queue_fast_ramp main boolean false
+.cindex "queue runner" "two phase"
+.cindex "queue" "double scanning"
+If set to true, two-phase queue runs, initiated using &%-qq%& on the
+command line, may start parallel delivery processes during their first
+phase.  This will be done when a threshold number of messages have been
+routed for a single host.
+.wen
+
+
 .option queue_list_requires_admin main boolean true
 .cindex "restricting access to features"
 .oindex "&%-bp%&"
@@ -29545,7 +29562,7 @@ tls_resumption_hosts = ${if inlist {$received_port}{587:465} {:}{*}}
 If the peer host matches the list after expansion then resumption
 is offered and/or accepted.
 
-The &%tls_resumption_hosts% smtp transport option performs the
+The &%tls_resumption_hosts%& smtp transport option performs the
 equivalent function for operation as a client.
 If the peer host matches the list after expansion then resumption
 is attempted (if a stored session is available) or the information
diff --git a/doc/doc-txt/OptionLists.txt b/doc/doc-txt/OptionLists.txt
index 39827b6ee..5de6d6936 100644
--- a/doc/doc-txt/OptionLists.txt
+++ b/doc/doc-txt/OptionLists.txt
@@ -443,6 +443,7 @@ qualify_recipient                    string          +             main
 qualify_single                       boolean         true          dnslookup         4.00
 query                                string*         +             iplookup          4.00
 queue_domains                        domain list     unset         main              4.00
+queue_fasst_ramp                     boolean         false         main              4.95
 queue_list_requires_admin            boolean         true          main              1.95
 queue_only                           boolean         false         main
 queue_only_file                      string          unset         main              2.05
diff --git a/doc/doc-txt/experimental-spec.txt b/doc/doc-txt/experimental-spec.txt
index 8c9a866a2..68366a4a9 100644
--- a/doc/doc-txt/experimental-spec.txt
+++ b/doc/doc-txt/experimental-spec.txt
@@ -639,7 +639,7 @@ used via the transport in question.
 
 
 Dovecot authenticator via inet socket
-------------------------------------
+--------------------------------------------------------------
 If Dovecot is configured similar to :-
 
 service auth {
@@ -666,30 +666,6 @@ and a whitespace-separated port number must be given.
 
 
 
-Twophase queue run fast ramp
-----------------------------
-To include this feature, add to Local/Makefile:
-  EXPERIMENTAL_QUEUE_RAMP=yes
-
-If the (added for this feature) main-section option "queue_fast_ramp" (boolean)
-is set, and a two-phase ("-qq") queue run finds, during the first phase, a
-suitably large number of message routed for a given host - then (subject to
-the usual queue-runner resource limits) delivery for that host is initiated
-immediately, overlapping with the remainder of the first phase.
-
-This is incompatible with queue_run_in_order.
-
-The result should be a faster startup of deliveries when a large queue is
-present and reasonable numbers of messages are routed to common hosts; this
-could be a smarthost case, or delivery onto the Internet where a large proportion
-of recipients hapen to be on a Gorilla-sized provider.
-
-As usual, the presence of a configuration option is associated with a
-predefined macro, making it possible to write portable configurations.
-For this one, the macro is _OPT_MAIN_QUEUE_FAST_RAMP.
-
-
-
 --------------------------------------------------------------
 End of file
 --------------------------------------------------------------