From 16292fcc2c830d89361b823760a3b660f3a19ad6 Mon Sep 17 00:00:00 2001 From: Aaron Weiss Date: Mon, 1 Jan 2018 21:47:28 -0500 Subject: [PATCH] Improved documentation for message throttling configuration. --- src/client/data/config.rs | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/src/client/data/config.rs b/src/client/data/config.rs index b2aaa92..ef90073 100644 --- a/src/client/data/config.rs +++ b/src/client/data/config.rs @@ -60,10 +60,14 @@ pub struct Config { pub ping_time: Option, /// The amount of time in seconds for a client to reconnect due to no ping response. pub ping_timeout: Option, - /// The amount of time in seconds to consider a window for burst messages. + /// The length in seconds of a rolling window for message throttling. If more than + /// `max_messages_in_burst` messages are sent within `burst_window_length` seconds, additional + /// messages will be delayed automatically as appropriate. In particular, in the past + /// `burst_window_length` seconds, there will never be more than `max_messages_in_burst` messages + /// sent. pub burst_window_length: Option, /// The maximum number of messages that can be sent in a burst window before they'll be delayed. - /// Messages are automatically delayed until the start of the next window. + /// Messages are automatically delayed as appropriate. pub max_messages_in_burst: Option, /// Whether the client should use NickServ GHOST to reclaim its primary nickname if it is in /// use. This has no effect if `nick_password` is not set. @@ -391,14 +395,18 @@ impl Config { self.ping_timeout.as_ref().cloned().unwrap_or(10) } - /// The amount of time in seconds to consider a window for burst messages. + /// The amount of time in seconds to consider a window for burst messages. The message throttling + /// system maintains the invariant that in the past `burst_window_length` seconds, the maximum + /// number of messages sent is `max_messages_in_burst`. /// This defaults to 8 seconds when not specified. pub fn burst_window_length(&self) -> u32 { self.burst_window_length.as_ref().cloned().unwrap_or(8) } /// The maximum number of messages that can be sent in a burst window before they'll be delayed. - /// Messages are automatically delayed until the start of the next window. + /// Messages are automatically delayed until the start of the next window. The message throttling + /// system maintains the invariant that in the past `burst_window_length` seconds, the maximum + /// number of messages sent is `max_messages_in_burst`. /// This defaults to 15 messages when not specified. pub fn max_messages_in_burst(&self) -> u32 { self.max_messages_in_burst.as_ref().cloned().unwrap_or(15)