NEWS,man: tweak the description of FixedRandomDelay=

Explain why this is useful, but don't describe the implementation exactly,
since we're likely to want to change details in the future.

1 files changed, 30 insertions, 33 deletions

diff --git a/man/systemd.timer.xml b/man/systemd.timer.xml
index 7c1a4917e5..9fe7ff3255 100644
--- a/man/systemd.timer.xml
+++ b/man/systemd.timer.xml
@@ -240,44 +240,41 @@
       <varlistentry>
         <term><varname>RandomizedDelaySec=</varname></term>
 
-        <listitem><para>Delay the timer by a randomly selected, evenly
-        distributed amount of time between 0 and the specified time
-        value. Defaults to 0, indicating that no randomized delay
-        shall be applied. Each timer unit will determine this delay
-        randomly before each iteration, and the delay will simply be
-        added on top of the next determined elapsing time. This is
-        useful to stretch dispatching of similarly configured timer
-        events over a certain amount time, to avoid that they all fire
-        at the same time, possibly resulting in resource
-        congestion. Note the relation to
-        <varname>AccuracySec=</varname> above: the latter allows the
-        service manager to coalesce timer events within a specified
-        time range in order to minimize wakeups, the former does the
-        opposite: it stretches timer events over a time range, to make
-        it unlikely that they fire simultaneously. If
-        <varname>RandomizedDelaySec=</varname> and
-        <varname>AccuracySec=</varname> are used in conjunction, first
-        the randomized delay is added, and then the result is
-        possibly further shifted to coalesce it with other timer
-        events happening on the system. As mentioned above
-        <varname>AccuracySec=</varname> defaults to 1min and
-        <varname>RandomizedDelaySec=</varname> to 0, thus encouraging
-        coalescing of timer events. In order to optimally stretch
-        timer events over a certain range of time, make sure to set
-        <varname>RandomizedDelaySec=</varname> to a higher value, and
-        <varname>AccuracySec=1us</varname>.</para></listitem>
+        <listitem><para>Delay the timer by a randomly selected, evenly distributed amount of time between 0
+        and the specified time value. Defaults to 0, indicating that no randomized delay shall be applied.
+        Each timer unit will determine this delay randomly before each iteration, and the delay will simply
+        be added on top of the next determined elapsing time, unless modified with
+        <varname>FixedRandomDelay=</varname>, see below.</para>
+
+        <para>This setting is useful to stretch dispatching of similarly configured timer events over a
+        certain time interval, to prevent them from firing all at the same time, possibly resulting in
+        resource congestion.</para>
+
+        <para>Note the relation to <varname>AccuracySec=</varname> above: the latter allows the service
+        manager to coalesce timer events within a specified time range in order to minimize wakeups, while
+        this setting does the opposite: it stretches timer events over an interval, to make it unlikely that
+        they fire simultaneously. If <varname>RandomizedDelaySec=</varname> and
+        <varname>AccuracySec=</varname> are used in conjunction, first the randomized delay is added, and
+        then the result is possibly further shifted to coalesce it with other timer events happening on the
+        system. As mentioned above <varname>AccuracySec=</varname> defaults to 1 minute and
+        <varname>RandomizedDelaySec=</varname> to 0, thus encouraging coalescing of timer events. In order to
+        optimally stretch timer events over a certain range of time, set
+        <varname>AccuracySec=1us</varname> and <varname>RandomizedDelaySec=</varname> to some higher value.
+        </para></listitem>
       </varlistentry>
 
       <varlistentry>
         <term><varname>FixedRandomDelay=</varname></term>
 
-        <listitem><para>Takes a boolean argument. If true, some amount of time between 0 and
-        <varname>RandomizedDelaySec=</varname> is chosen and added as the delay for each timer iteration. As this
-        delay will not be recalculated on each run, this effectively creates a fixed offset for each iteration.
-        The distribution between 0 and <varname>RandomizedDelaySec=</varname> is deterministic and based on
-        a combination of the machine ID, whether the timer is run by the user/system manager, the service manager's
-        user ID, and the timer's unit name. Has no effect if
-        <varname>RandomizedDelaySec=</varname> is set to 0. Defaults to <option>false</option>.</para></listitem>
+        <listitem><para>Takes a boolean argument. When enabled, the randomized offset specified by
+        <varname>RandomizedDelaySec=</varname> is reused for all firings of the same timer. For a given timer
+        unit, the offset depends on the machine ID, user identifier and timer name, which means that it is
+        stable between restarts of the manager. This effectively creates a fixed offset for an individual
+        timer, reducing the jitter in firings of this timer, while still avoiding firing at the same time as
+        other similarly configured timers.</para>
+
+        <para>This setting has no effect if <varname>RandomizedDelaySec=</varname> is set to 0. Defaults to
+        <option>false</option>.</para></listitem>
       </varlistentry>
 
       <varlistentry>