From 4e93f2333efc60445b65a553bdb79ae223e77a19 Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 29 Nov 2019 16:52:11 -0800 Subject: [PATCH] doc: update socket.bufferSize text Edit text for clarity and readability. PR-URL: https://github.com/nodejs/node/pull/30723 Reviewed-By: Anna Henningsen Reviewed-By: Gireesh Punathil Reviewed-By: James M Snell --- doc/api/net.md | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/doc/api/net.md b/doc/api/net.md index 9bc9812d7ca6e9..7ec75e358f396a 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -548,19 +548,17 @@ added: v0.3.8 * {integer} +This property shows the number of characters buffered for writing. The buffer +may contain strings whose length after encoding is not yet known. So this number +is only an approximation of the number of bytes in the buffer. + `net.Socket` has the property that `socket.write()` always works. This is to help users get up and running quickly. The computer cannot always keep up with the amount of data that is written to a socket. The network connection simply might be too slow. Node.js will internally queue up the data written to a -socket and send it out over the wire when it is possible. (Internally it is -polling on the socket's file descriptor for being writable). - -The consequence of this internal buffering is that memory may grow. This -property shows the number of characters currently buffered to be written. -(Number of characters is approximately equal to the number of bytes to be -written, but the buffer may contain strings, and the strings are lazily -encoded, so the exact number of bytes is not known.) +socket and send it out over the wire when it is possible. +The consequence of this internal buffering is that memory may grow. Users who experience large or growing `bufferSize` should attempt to "throttle" the data flows in their program with [`socket.pause()`][] and [`socket.resume()`][].