[docs] Rewording portions of the optimizing guide (Issue #2998)

docs/glossary.rst

@@ -18,6 +18,32 @@ Glossary
     ack
         Short for :term:`acknowledged`.
 
+    early acknowledgement
+
+        Task is :term:`acknowledged` just-in-time before being executed,
+        meaning the task will not be redelivered to another worker if the
+        machine loses power, or the worker instance is abruptly killed,
+        mid-execution.
+
+        Configured using :setting:`task_acks_late`.
+
+    late acknowledgment
+
+        Task is :term:`acknowledged` after execution (both if successful, or
+        if the task is raising an error), which means the task will be
+        redelivered to another worker in the event of the machine losing
+        power, or the worker instance being killed mid-execution.
+
+        Configured using :setting:`task_acks_late`.
+
+    early ack
+
+        Short for :term:`early acknowledgement`
+
+    late ack
+
+        Short for :term:`late acknowledgement`
+
     request
         Task messages are converted to *requests* within the worker.
         The request information is also available as the task's
@@ -54,6 +80,8 @@ Glossary
         unintended effects, but not necessarily side-effect free in the pure
         sense (compare to :term:`nullipotent`).
 
+        Further reading: http://en.wikipedia.org/wiki/Idempotent
+
     nullipotent
         describes a function that will have the same effect, and give the same
         result, even if called zero or multiple times (side-effect free).

docs/userguide/optimizing.rst

@@ -176,20 +176,29 @@ the tasks according to the run-time. (see :ref:`guide-routing`).
 Reserve one task at a time
 --------------------------
 
-When using early acknowledgement (default), a prefetch multiplier of 1
-means the worker will reserve at most one extra task for every active
-worker process.
+The task message is only deleted from the queue after the task is
+:term:`acknowledged`, so if the worker crashes before acknowleding the task,
+it can be redelivered to another worker (or the same after recovery).
 
-When users ask if it's possible to disable "prefetching of tasks", often
-what they really want is to have a worker only reserve as many tasks as there
-are child processes.
+When using the default of early acknowledgement, having a prefetch multiplier setting
+of 1, means the worker will reserve at most one extra task for every
+worker process: or in other words, if the worker is started with `-c 10`,
+the worker may reserve at most 20 tasks (10 unacknowledged tasks executing, and 10
+unacknowledged reserved tasks) at any time.
 
-But this is not possible without enabling late acknowledgements
-acknowledgements; A task that has been started, will be
-retried if the worker crashes mid execution so the task must be `idempotent`_
-(see also notes at :ref:`faq-acks_late-vs-retry`).
+Often users ask if disabling "prefetching of tasks" is possible, but what
+they really mean by that is to have a worker only reserve as many tasks as
+there are worker processes (10 unacknowledged tasks for `-c 10`)
 
-.. _`idempotent`: http://en.wikipedia.org/wiki/Idempotent
+That is possible, but not without also enabling
+:term:`late acknowledgments`.  Using this option over the
+default beahvior means a task that has already started executing will be
+retried in the event of a power failure or the worker instance being killed
+abruptly, so this also means the task must be :term:`idempotent`
+
+.. seealso::
+
+    Notes at :ref:`faq-acks_late-vs-retry`.
 
 You can enable this behavior by using the following configuration options: