From 2345e28158407a977961092253c64702a673c9be Mon Sep 17 00:00:00 2001 From: Alex Butler Date: Sat, 17 Jun 2023 23:24:52 +0100 Subject: [PATCH] Clarify WebSocketConfig docs --- src/protocol/mod.rs | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/src/protocol/mod.rs b/src/protocol/mod.rs index db32586..c3a6111 100644 --- a/src/protocol/mod.rs +++ b/src/protocol/mod.rs @@ -42,13 +42,21 @@ pub struct WebSocketConfig { /// to the underlying stream. /// The default value is 128 KiB. /// + /// If set to `0` each message will be eagerly written to the underlying stream. + /// It is often more optimal to allow them to buffer a little, hence the default value. + /// /// Note: [`flush`](WebSocket::flush) will always fully write the buffer regardless. pub write_buffer_size: usize, /// The max size of the write buffer in bytes. Setting this can provide backpressure /// in the case the write buffer is filling up due to write errors. /// The default value is unlimited. /// - /// Note: Should always be set higher than [`write_buffer_size`](Self::write_buffer_size). + /// Note: The write buffer only builds up past [`write_buffer_size`](Self::write_buffer_size) + /// when writes to the underlying stream are failing. So the **write buffer can not + /// fill up if you are not observing write errors even if not flushing**. + /// + /// Note: Should always be at least [`write_buffer_size + 1 message`](Self::write_buffer_size) + /// and probably a little more depending on error handling strategy. pub max_write_buffer_size: usize, /// The maximum size of a message. `None` means no size limit. The default value is 64 MiB /// which should be reasonably big for all normal use-cases but small enough to prevent