C# Class System.IO.BufferedStream

One of the design goals here is to prevent the buffer from getting in the way and slowing down underlying stream accesses when it is not needed. If you always read & write for sizes greater than the internal buffer size, then this class may not even allocate the internal buffer. See a large comment in Write for the details of the write buffer heuristic. This class buffers reads & writes in a shared buffer. (If you maintained two buffers separately, one operation would always trash the other buffer anyways, so we might as well use one buffer.) The assumption here is you will almost always be doing a series of reads or writes, but rarely alternate between the two of them on the same stream. Class Invariants: The class has one buffer, shared for reading & writing. It can only be used for one or the other at any point in time - not both. The following should be true: 0 implies the read buffer is valid, but we're at the end of the buffer. * _readPos == _readLen == 0 means the read buffer contains garbage. * Either _writePos can be greater than 0, or _readLen & _readPos can be greater than zero, but neither can be greater than zero at the same time. ]]> This class will never cache more bytes than the max specified buffer size. However, it may use a temporary buffer of up to twice the size in order to combine several IO operations on the underlying stream into a single operation. This is because we assume that memory copies are significantly faster than IO operations on the underlying stream (if this was not true, using buffering is never appropriate). The max size of this "shadow" buffer is limited as to not allocate it on the LOH. Shadowing is always transient. Even when using this technique, this class still guarantees that the number of bytes cached (not yet written to the target stream or not yet consumed by the user) is never larger than the actual specified buffer size.