154 // Buffers

   155 //

   156 // Connections buffer network input and output to reduce the number

   157 // of system calls when reading or writing messages.

   158 //

   159 // Write buffers are also used for constructing WebSocket frames. See RFC 6455,

   160 // Section 5 for a discussion of message framing. A WebSocket frame header is

   161 // written to the network each time a write buffer is flushed to the network.

   162 // Decreasing the size of the write buffer can increase the amount of framing

   163 // overhead on the connection.

   164 //

   165 // The buffer sizes in bytes are specified by the ReadBufferSize and

   166 // WriteBufferSize fields in the Dialer and Upgrader. The Dialer uses a default

   167 // size of 4096 when a buffer size field is set to zero. The Upgrader reuses

   168 // buffers created by the HTTP server when a buffer size field is set to zero.

   169 // The HTTP server buffers have a size of 4096 at the time of this writing.

   170 //

   171 // The buffer sizes do not limit the size of a message that can be read or

   172 // written by a connection.

   173 //

   174 // Buffers are held for the lifetime of the connection by default. If the

   175 // Dialer or Upgrader WriteBufferPool field is set, then a connection holds the

   176 // write buffer only when writing a message.

   177 //

   178 // Applications should tune the buffer sizes to balance memory use and

   179 // performance. Increasing the buffer size uses more memory, but can reduce the

   180 // number of system calls to read or write the network. In the case of writing,

   181 // increasing the buffer size can reduce the number of frame headers written to

   182 // the network.

   183 //

   184 // Some guidelines for setting buffer parameters are:

   185 //

   186 // Limit the buffer sizes to the maximum expected message size. Buffers larger

   187 // than the largest message do not provide any benefit.

   188 //

   189 // Depending on the distribution of message sizes, setting the buffer size to

   190 // to a value less than the maximum expected message size can greatly reduce

   191 // memory use with a small impact on performance. Here's an example: If 99% of

   192 // the messages are smaller than 256 bytes and the maximum message size is 512

   193 // bytes, then a buffer size of 256 bytes will result in 1.01 more system calls

   194 // than a buffer size of 512 bytes. The memory savings is 50%.

   195 //

   196 // A write buffer pool is useful when the application has a modest number

   197 // writes over a large number of connections. when buffers are pooled, a larger

   198 // buffer size has a reduced impact on total memory use and has the benefit of

   199 // reducing system calls and frame overhead.

   200 //