describe partial mesh in timings table

1 files changed, 14 insertions, 7 deletions

diff --git a/src/state/timing.rs b/src/state/timing.rs
index c2993d7..3c4afe1 100644
--- a/src/state/timing.rs
+++ b/src/state/timing.rs
@@ -40,13 +40,20 @@ impl Timing {
         self.keepalive * 5
     }
 
-    // Recommended values
-    //  Environment                                 | Keepalive | Notes
-    //  --------------------------------------------+-----------+------------------------------------------------------------
-    //  Test harness                                | 1-2 s     | Dormancy after about 4–8 s and healing within seconds keep tests short.
-    //  LAN or small swarm (up to ~50 nodes)      | 15-30 s   | Under 3.5 messages/s per node at 50 nodes and 30 s. Current setting.
-    //  WAN, mobile or metered links, or 100+ nodes | 60-120 s  | At 100 nodes and 30 s it’s about 6–7 messages/s per node. Fine, but rarely worth it on battery or metered links.
-    //  Several hundred nodes or more               | -         | The full mesh becomes the problem in itself, not the interval. Message counts grow O(N²) across the swarm, which calls for partial views (SWIM-style random probing and syncing with a subset of peers).
+    /// The timings for `--keepalive`.
+    ///
+    /// Each node keeps about `k` neighbours (`--neighbours`) whatever the swarm's size,
+    /// and only one side of a pair pings, so idle, a node sends about `k` messages and
+    /// receives about `k` (PINGs and PONGs) per keepalive interval (more on a stable
+    /// member others prefer). The interval trades that against how soon a silent peer is
+    /// noticed (`dormant_after`, 4 intervals) and a gap closes (within an interval).
+    /// Recommended:
+    ///
+    /// | Environment | Keepalive | Notes |
+    /// |---|---|---|
+    /// | Tests | 250 ms – 2 s | dormancy within seconds keeps tests short |
+    /// | LAN, servers | 15–30 s | a returning or silent peer is noticed within a minute or two |
+    /// | WAN, mobile, metered (the default, 1m) | 60–120 s | about 0.4 messages per second per node at `k` = 12 and 1m |
     pub(crate) fn from_keepalive(keepalive: Duration) -> Self {
         Self::new(keepalive, SYNC_REPLY_TIMEOUT)
     }