`BufferedTCP` - Buffered TCP/IP Network Stream

The BufferedTCP class implements a communications stream which buffers both input and output from and to a TCP/IP network connection.

When an application first attempts to Read() from a buffered stream, the stream object (i) allocates a single, large input buffer and (ii) reads as much data as it can - up to the size of the buffer - with a single call to the system read(2) function. The stream object then doles out from the input buffer the amounts of data requested by the application in successive Read() calls. When the input buffer is exhausted, the stream object performs another large read(2) to refill the buffer, and so on.

Output buffering is controlled by the timeout argument to the Write() method. Unbuffered output is achieved with a negative timeout (e.g., -1.0): the Write() method blocks until all the data (including previously buffered output) has been written to the stream's network connection. Buffered output, on the other hand, results from a zero or positive timeout. For a zero timeout, Write() simply appends the caller's data to a queue of output buffers. In the case of a positive timeout, Write() adds the caller's data to the queue and then attempts to write(2) to the stream's network connection as much of the buffered data as possible in the given time interval.

When buffering output, the buffered data must be flushed to the network connection at some point. This can by accomplished in a polled manner by periodic calls to Flush(). More sophisticated applications, operating in the context of an event loop (e.g., the X Toolkit or ERAL's Dispatcher), can register the stream's socket connection, returned by Fd(), as an output source. When the event loop signals that the connection is ready for output, the application should call Flush() with a zero timeout. After all the buffered output data has been flushed to the network connection and PendingOutput() returns false, the application should unregister the connection as an output source.

Although BufferedTCP can be used as a stand-alone class, it is primarily intended as a parent class for streams which must efficiently exchange application-specific messages (e.g., those consisting of a fixed-length header and a variable-length body).