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()`][].