Documented when helper requests get queued (#238)

I had to change introductory paragraphs in several directives so that
the new documentation can refer to "numberofchildren". I fixed a few
spelling/grammar problems in changed paragraphs and edited them a bit
for consistency, but they need more work.

Motivation:
http://lists.squid-cache.org/pipermail/squid-users/2018-July/018577.html

diff --git a/src/cf.data.pre b/src/cf.data.pre
index c7f9a3e08edde7a3580093824f393c07789c363d..77f12d54a28a9e0c506bb9c928f2648113de21b3 100644 (file)
--- a/src/cf.data.pre
+++ b/src/cf.data.pre
@@ -612,12 +612,15 @@ DOC_START
                Concurrency must not be set unless it's known the helper
                supports the input format with channel-ID fields.
 
-               The queue-size=N option sets the maximum number of queued
-               requests to N. The default maximum is 2*numberofchildren. Squid
-               is allowed to temporarily exceed the configured maximum, marking
-               the affected helper as "overloaded". If the helper overload
-               lasts more than 3 minutes, the action prescribed by the
-               on-persistent-overload option applies.
+               The queue-size option sets the maximum number of queued
+               requests. A request is queued when no existing child can
+               accept it due to concurrency limit and no new child can be
+               started due to numberofchildren limit. The default maximum is
+               2*numberofchildren. Squid is allowed to temporarily exceed the
+               configured maximum, marking the affected helper as
+               "overloaded". If the helper overload lasts more than 3
+               minutes, the action prescribed by the on-persistent-overload
+               option applies.
 
                The on-persistent-overload=action option specifies Squid
                reaction to a new helper request arriving when the helper
@@ -846,10 +849,12 @@ DOC_START
          concurrency=n concurrency level per process. Only used with helpers
                        capable of processing more than one query at a time.
 
-         queue-size=N  The queue-size= option sets the maximum number of queued
-                       requests. If the queued requests exceed queue size 
-                       the acl is ignored.
-                       The default value is set to 2*children-max.
+         queue-size=N  The queue-size option sets the maximum number of
+                       queued requests. A request is queued when no existing
+                       helper can accept it due to concurrency limit and no
+                       new helper can be started due to children-max limit.
+                       If the queued requests exceed queue size, the acl is
+                       ignored. The default value is set to 2*children-max.
 
          protocol=2.5  Compatibility mode for Squid-2.5 external acl helpers.
 
@@ -3143,9 +3148,14 @@ IFDEF: USE_SSL_CRTD
 DEFAULT: 32 startup=5 idle=1
 LOC: Ssl::TheConfig.ssl_crtdChildren
 DOC_START
-       The maximum number of processes spawn to service ssl server.
-       The maximum this may be safely set to is 32.
-       
+       Specifies the maximum number of certificate generation processes that
+       Squid may spawn (numberofchildren) and several related options. Using
+       too few of these helper processes (a.k.a. "helpers") creates request
+       queues. Using too many helpers wastes your system resources. Squid
+       does not support spawning more than 32 helpers.
+
+       Usage: numberofchildren [option]...
+
        The startup= and idle= options allow some measure of skew in your
        tuning.
        
@@ -3167,10 +3177,11 @@ DOC_START
 
                queue-size=N
 
-       Sets the maximum number of queued requests.
-       If the queued requests exceed queue size for more than 3 minutes
-       squid aborts its operation.
-       The default value is set to 2*numberofchildren.
+       Sets the maximum number of queued requests. A request is queued when
+       no existing child is idle and no new child can be started due to
+       numberofchildren limit. If the queued requests exceed queue size for
+       more than 3 minutes squid aborts its operation. The default value is
+       set to 2*numberofchildren.
        
        You must have at least one ssl_crtd process.
 DOC_END
@@ -3197,8 +3208,13 @@ IFDEF: USE_OPENSSL
 DEFAULT: 32 startup=5 idle=1 concurrency=1
 LOC: Ssl::TheConfig.ssl_crt_validator_Children
 DOC_START
-       The maximum number of processes spawn to service SSL server.
-       The maximum this may be safely set to is 32.
+       Specifies the maximum number of certificate validation processes that
+       Squid may spawn (numberofchildren) and several related options. Using
+       too few of these helper processes (a.k.a. "helpers") creates request
+       queues. Using too many helpers wastes your system resources. Squid
+       does not support spawning more than 32 helpers.
+
+       Usage: numberofchildren [option]...
        
        The startup= and idle= options allow some measure of skew in your
        tuning.
@@ -3233,10 +3249,11 @@ DOC_START
 
                queue-size=N
 
-       Sets the maximum number of queued requests.
-       If the queued requests exceed queue size for more than 3 minutes
-       squid aborts its operation.
-       The default value is set to 2*numberofchildren.
+       Sets the maximum number of queued requests. A request is queued when
+       no existing child can accept it due to concurrency limit and no new
+       child can be started due to numberofchildren limit. If the queued
+       requests exceed queue size for more than 3 minutes squid aborts its
+       operation. The default value is set to 2*numberofchildren.
        
        You must have at least one ssl_crt_validator process.
 DOC_END
@@ -5321,11 +5338,13 @@ TYPE: HelperChildConfig
 DEFAULT: 20 startup=0 idle=1 concurrency=0
 LOC: Config.redirectChildren
 DOC_START
-       The maximum number of redirector processes to spawn. If you limit
-       it too few Squid will have to wait for them to process a backlog of
-       URLs, slowing it down. If you allow too many they will use RAM
-       and other system resources noticably.
-       
+       Specifies the maximum number of redirector processes that Squid may
+       spawn (numberofchildren) and several related options. Using too few of
+       these helper processes (a.k.a. "helpers") creates request queues.
+       Using too many helpers wastes your system resources.
+
+       Usage: numberofchildren [option]...
+
        The startup= and idle= options allow some measure of skew in your
        tuning.
        
@@ -5358,13 +5377,16 @@ DOC_START
 
                queue-size=N
 
-       Sets the maximum number of queued requests to N. The default maximum
-       is 2*numberofchildren. If the queued requests exceed queue size and
-       redirector_bypass configuration option is set, then redirector is bypassed.
-       Otherwise, Squid is allowed to temporarily exceed the configured maximum,
-       marking the affected helper as "overloaded". If the helper overload lasts
-       more than 3 minutes, the action prescribed by the on-persistent-overload
-       option applies.
+       Sets the maximum number of queued requests. A request is queued when
+       no existing child can accept it due to concurrency limit and no new
+       child can be started due to numberofchildren limit. The default
+       maximum is zero if url_rewrite_bypass is enabled and
+       2*numberofchildren otherwise. If the queued requests exceed queue size
+       and redirector_bypass configuration option is set, then redirector is
+       bypassed. Otherwise, Squid is allowed to temporarily exceed the
+       configured maximum, marking the affected helper as "overloaded". If
+       the helper overload lasts more than 3 minutes, the action prescribed
+       by the on-persistent-overload option applies.
 
                on-persistent-overload=action
 
@@ -5430,8 +5452,9 @@ DOC_START
        redirectors for access control, and you enable this option,
        users may have access to pages they should not
        be allowed to request.
-       This options sets default queue-size option of the url_rewrite_children
-       to 0.
+
+       Enabling this option sets the default url_rewrite_children queue-size
+       option value to 0.
 DOC_END
 
 NAME: url_rewrite_extras
@@ -5545,10 +5568,12 @@ TYPE: HelperChildConfig
 DEFAULT: 20 startup=0 idle=1 concurrency=0
 LOC: Config.storeIdChildren
 DOC_START
-       The maximum number of StoreID helper processes to spawn. If you limit
-       it too few Squid will have to wait for them to process a backlog of
-       requests, slowing it down. If you allow too many they will use RAM
-       and other system resources noticably.
+       Specifies the maximum number of StoreID helper processes that Squid
+       may spawn (numberofchildren) and several related options. Using
+       too few of these helper processes (a.k.a. "helpers") creates request
+       queues. Using too many helpers wastes your system resources.
+
+       Usage: numberofchildren [option]...
        
        The startup= and idle= options allow some measure of skew in your
        tuning.
@@ -5582,13 +5607,15 @@ DOC_START
 
                queue-size=N
 
-       Sets the maximum number of queued requests to N. The default maximum
-       is 2*numberofchildren. If the queued requests exceed queue size and
-       redirector_bypass configuration option is set, then redirector is bypassed.
-       Otherwise, Squid is allowed to temporarily exceed the configured maximum,
-       marking the affected helper as "overloaded". If the helper overload lasts
-       more than 3 minutes, the action prescribed by the on-persistent-overload
-       option applies.
+       Sets the maximum number of queued requests to N. A request is queued
+       when no existing child can accept it due to concurrency limit and no
+       new child can be started due to numberofchildren limit. The default
+       maximum is 2*numberofchildren. If the queued requests exceed queue
+       size and redirector_bypass configuration option is set, then
+       redirector is bypassed. Otherwise, Squid is allowed to temporarily
+       exceed the configured maximum, marking the affected helper as
+       "overloaded". If the helper overload lasts more than 3 minutes, the
+       action prescribed by the on-persistent-overload option applies.
 
                on-persistent-overload=action