#include <kbufferedio.h>

Inheritance diagram for TDEBufferedIO:

Public Types
enum	closeModes { availRead = 0x01 , dirtyWrite = 0x02 , involuntary = 0x10 , delayed = 0x20 , closedNow = 0x40 }

Signals
void	bytesWritten (int nbytes)

void	closed (int state)

Signals inherited from KAsyncIO
void	readyRead ()

void	readyWrite ()

Public Member Functions
virtual	~TDEBufferedIO ()

virtual void	closeNow ()=0

virtual bool	setBufferSize (int rsize, int wsize=-2)

virtual int	bytesAvailable () const

virtual int	waitForMore (int msec)=0

virtual int	bytesToWrite () const

virtual bool	canReadLine () const

virtual int	peekBlock (char *data, uint maxlen)=0

virtual int	unreadBlock (const char *data, uint len)

Public Member Functions inherited from KAsyncIO
virtual void	enableRead (bool enable)=0

virtual void	enableWrite (bool enable)=0

Protected Member Functions
	TDEBufferedIO ()

virtual unsigned	consumeReadBuffer (unsigned nbytes, char *destbuffer, bool discard=true)

virtual void	consumeWriteBuffer (unsigned nbytes)

virtual unsigned	feedReadBuffer (unsigned nbytes, const char *buffer, bool atBeginning=false)

virtual unsigned	feedWriteBuffer (unsigned nbytes, const char *buffer)

virtual unsigned	readBufferSize () const

virtual unsigned	writeBufferSize () const

virtual void	virtual_hook (int id, void *data)

virtual void	virtual_hook (int id, void *data)

Protected Attributes
TQPtrList< TQByteArray >	inBuf

TQPtrList< TQByteArray >	outBuf

unsigned	inBufIndex

unsigned	outBufIndex

Detailed Description

This abstract class implements basic functionality for buffered input/output.

Through the available methods, you can find out how many bytes are available for reading, how many are still unsent and you can peek at the buffered data.

This class was intentionally written to resemble TQSocket, because KExtendedSocket is a subclass of this one. This is so that applications written using QSocket's buffering characteristics will be more easily ported to the more powerful KExtendedSocket class.

TDEBufferedIO already provides a powerful internal buffering algorithm. However, this does not include the I/O itself, which must be implemented in derived classes. Thus, to implement a class that does some I/O, you must override, in addition to the pure virtual TQIODevice methods, these two:

If your derived class reimplements the buffering algorithm, you must then decide which buffering functions to override. For instance, you may want to change the protected functions like feedReadBuffer() and consumeReadBuffer().

Author: Thiago Macieira thiag.nosp@m.om@m.nosp@m.ail.c.nosp@m.om

Buffered I/O

Definition at line 56 of file kbufferedio.h.

Member Enumeration Documentation

◆ closeModes

enum TDEBufferedIO::closeModes

The modes for closed() signal.

Definition at line 69 of file kbufferedio.h.

Constructor & Destructor Documentation

◆ TDEBufferedIO()

TDEBufferedIO::TDEBufferedIO ( )

protected

Implementation Details

The TDEBufferedIO class has two purposes: first, it defines an API on how that classes providing buffered I/O should provide. Next, it implements on top of that API a generic buffering, that should suffice for most cases.

The buffering implemented consists of two separate buffer areas, one for the input (or read) buffer, and one for the output (or write) buffer. Each of those buffers is implemented through a QList of QByteArrays instead of simply QByteArrays. The idea is that, instead of having one large, contiguous buffer area, we have several small ones. Even though this could be seen as a waste of memory, it makes our life easier, because we can just append a new TQByteArray to the list and not have to worry with copying the rest of the buffer, should we need to expand.

This way, we have the capability of unlimited buffering, which can grow to the extent of available memory.

For each buffer, we provide three kinds of functions, available as protected members: consume, feed and size. The size functions calculate the current size of the buffer, by adding each individual TQByteArray size. The feed functions are used by the I/O functions that receive data from somewhere, i.e., from the system, in the case of the input buffer, and from the user, in the case of the output buffer. These two functions are used to give the buffers more data. And the consume functions are used by the functions that send out data (to the system, for the write buffer, and to the user, for the read buffer).

Note that for your own implementation, you can have your readBlock function merely call consumeReadBuffer, similarly to peekBlock. As for the writeBlock function, you'd call feedWriteBuffer.

Now, the function receiving data from the system will need to simply call feedReadBuffer, much in the same way of unreadBlock. The tricky part is for the output function. We do not provide a member function that copies data from the output buffer into another buffer for sending. We believe that would be a waste of resources and CPU time, since you'd have to allocate that buffer, copy data into it and then call the OS, which will likely just copy data out of it.

Instead, we found it better to leave it to you to access outBuf member variable directly and use the buffers there. Should you want to copy that into a larger buffer before sending, that's up to you.

Both buffers work in the same way: they're an "array" of buffers, each concatenated to the other. All data in all buffers is valid data, except for the first TQByteArray, whose valid data starts at inBufIndex/outBufIndex bytes from the start. That is, the data starts in the first TQByteArray buffer that many bytes from the start and goes on contiguously until the last TQByteArray. This has been decided like that because we didn't want to create a new TQByteArray of the remaining bytes in the first buffer, after a consume operation, because that could take some time. It is faster this way, although not really easy.

If you want to take a look at an implementation of a buffered I/O class, refer to KExtendedSocket's source code.

Definition at line 89 of file kbufferedio.cpp.

◆ ~TDEBufferedIO()

TDEBufferedIO::~TDEBufferedIO ( )

virtual

Destroys this class.

The flushing of the buffers is implementation dependant. The default implementation discards the contents

Definition at line 97 of file kbufferedio.cpp.

Member Function Documentation

◆ bytesAvailable()

int TDEBufferedIO::bytesAvailable ( ) const

virtual

Returns the number of bytes available for reading in the read buffer.

Returns: the number of bytes available for reading

Reimplemented in KExtendedSocket.

Definition at line 114 of file kbufferedio.cpp.

◆ bytesToWrite()

int TDEBufferedIO::bytesToWrite ( ) const

virtual

Returns the number of bytes yet to write, still in the write buffer.

Returns: the number of unwritten bytes in the write buffer

Definition at line 119 of file kbufferedio.cpp.

◆ bytesWritten

void TDEBufferedIO::bytesWritten ( int nbytes )

signal

This signal gets sent whenever bytes are written from the buffer.

Parameters

nbytes the number of bytes sent.

◆ canReadLine()

bool TDEBufferedIO::canReadLine ( ) const

virtual

Checks whether there is enough data in the buffer to read a line.

The default implementation reads directly from inBuf, so if your implementation changes the meaning of that member, then you must override this function.

Returns: true when there is enough data in the buffer to read a line

Definition at line 125 of file kbufferedio.cpp.

◆ closed

void TDEBufferedIO::closed ( int state )

signal

This signal gets sent when the stream is closed.

The state parameter will give the current state, in OR-ed bits:

availRead: read buffer contains data to be read
dirtyWrite: write buffer wasn't empty when the stream closed
involuntary: the stream wasn't closed due to user request (i.e., call to close). Probably remote end closed it
delayed: the stream was closed voluntarily by the user, but it happened only after the write buffer was emptied
closedNow: the stream was closed voluntarily by the user, by explicitly calling closeNow, which means the write buffer's contents may have been discarded
Parameters

state the state (see function description)

◆ closeNow()

virtual void TDEBufferedIO::closeNow ( )

pure virtual

Closes the stream now, discarding the contents of the write buffer.

That is, we won't try to flush that buffer before closing. If you want that buffer to be flushed, you can call TQIODevice::flush(), which is blocking, and then closeNow, or you can call TQIODevice::close() for a delayed close.

Implemented in KExtendedSocket.

◆ consumeReadBuffer()

unsigned TDEBufferedIO::consumeReadBuffer	(	unsigned	nbytes,
		char *	destbuffer,
		bool	discard = `true`
	)

protectedvirtual

Consumes data from the input buffer.

That is, this will copy the data stored in the input (read) buffer into the given destbuffer, as much as nbytes.

Parameters

nbytes	the maximum amount of bytes to copy into the buffer
destbuffer	the destination buffer into which to copy the data
discard	whether to discard the copied data after the operation

Returns: the real amount of data copied. If it is less than nbytes, then all the buffer was copied.

Definition at line 164 of file kbufferedio.cpp.

◆ consumeWriteBuffer()

void TDEBufferedIO::consumeWriteBuffer ( unsigned nbytes )

protectedvirtual

Consumes data from the output buffer.

Since this is called whenever we managed to send data out the wire, we can only discard this amount from the buffer. There is no copying and no "peeking" for the output buffer.

Note this function should be called AFTER the data was sent. After it is called, the data is no longer available in the buffer. And don't pass wrong nbytes values.

Parameters

nbytes the amount of bytes to discard

Definition at line 214 of file kbufferedio.cpp.

◆ feedReadBuffer()

unsigned TDEBufferedIO::feedReadBuffer	(	unsigned	nbytes,
		const char *	buffer,
		bool	atBeginning = `false`
	)

protectedvirtual

Feeds data into the input buffer.

This happens when we detected available data in the device and read it.

The data will be appended to the buffer or inserted at the beginning, depending on whether atBeginning is set or not.

Parameters

nbytes	the number of bytes in the buffer
buffer	the data that was read
atBeginning	whether to append or insert at the beginning

Returns: the number of bytes that have been appended

Definition at line 243 of file kbufferedio.cpp.

◆ feedWriteBuffer()

unsigned TDEBufferedIO::feedWriteBuffer	(	unsigned	nbytes,
		const char *	buffer
	)

protectedvirtual

Feeds data into the output buffer.

This happens when the user told us to write some data. The data will be appended to the buffer.

Parameters

nbytes	the number of bytes in the buffer
buffer	the data that is to be written

Returns: the number of bytes that have been appended

Definition at line 259 of file kbufferedio.cpp.

◆ peekBlock()

virtual int TDEBufferedIO::peekBlock	(	char *	data,
		uint	maxlen
	)

pure virtual

Reads into the user buffer at most maxlen bytes, but does not consume that data from the read buffer.

This is useful to check whether we already have the needed data to process something.

This function may want to try and read more data from the system provided it won't block.

Parameters

data	the user buffer pointer, at least maxlen bytes long
maxlen	the maximum length to be peeked

Returns: the number of bytes actually copied.

Implemented in KExtendedSocket.

◆ readBufferSize()

unsigned TDEBufferedIO::readBufferSize ( ) const

protectedvirtual

Returns the number of bytes in the read buffer.

Returns: the size of the read buffer in bytes

Definition at line 270 of file kbufferedio.cpp.

◆ setBufferSize()

bool TDEBufferedIO::setBufferSize	(	int	rsize,
		int	wsize = `-2`
	)

virtual

Sets the internal buffer size to value.

Not all implementations support this.

The parameters may be 0 to make the class unbuffered or -1 to let the class choose the size (which may be unlimited) or -2 to leave the buffer size untouched.

Note that setting the write buffer size to any value smaller than the current size of the buffer will force it to flush first, which can make this call blocking.

The default implementation does not support setting the buffer sizes. You can only call this function with values -1 for "don't care" or -2 for "unchanged"

Parameters

rsize	the size of the read buffer
wsize	the size of the write buffer

Returns: true if setting both was ok. If false is returned, the buffers were left unchanged.

Reimplemented in KExtendedSocket.

Definition at line 104 of file kbufferedio.cpp.

◆ unreadBlock()

int TDEBufferedIO::unreadBlock	(	const char *	data,
		uint	len
	)

virtual

Unreads some data.

That is, write the data to the beginning of the read buffer, so that next calls to readBlock or peekBlock will see this data instead.

Note not all devices implement this since this could mean a semantic problem. For instance, sockets are sequential devices, so they won't accept unreading.

Parameters

data	the data to be unread
len	the size of the data

Returns: the number of bytes actually unread

Reimplemented in KExtendedSocket.

Definition at line 155 of file kbufferedio.cpp.

◆ virtual_hook()

void TDEBufferedIO::virtual_hook	(	int	id,
		void *	data
	)

protectedvirtual

Reimplemented from KAsyncIO.

Definition at line 296 of file kbufferedio.cpp.

◆ waitForMore()

virtual int TDEBufferedIO::waitForMore ( int msec )

pure virtual

Waits for more data to be available and returns the amount of available data then.

Parameters

msec	number of milliseconds to wait, -1 to wait forever

Returns: -1 if we cannot wait (e.g., that doesn't make sense in this stream)

Implemented in KExtendedSocket.

◆ writeBufferSize()

unsigned TDEBufferedIO::writeBufferSize ( ) const

protectedvirtual

Returns the number of bytes in the write buffer.

Returns: the size of the write buffer in bytes

Definition at line 283 of file kbufferedio.cpp.

Member Data Documentation

◆ inBuf

TQPtrList<TQByteArray> TDEBufferedIO::inBuf

protected

For an explanation on how this buffer work, please refer to the comments at the top of kbufferedio.cpp, Implementation Details .

Definition at line 213 of file kbufferedio.h.

◆ inBufIndex

unsigned TDEBufferedIO::inBufIndex

protected

Offset into first input buffer.

Definition at line 221 of file kbufferedio.h.

◆ outBuf

TQPtrList<TQByteArray> TDEBufferedIO::outBuf

protected

For an explanation on how this buffer work, please refer to the comments at the top of kbufferedio.cpp, Implementation Details .

Definition at line 219 of file kbufferedio.h.

◆ outBufIndex

unsigned TDEBufferedIO::outBufIndex

protected

Offset into first output buffer.

Definition at line 222 of file kbufferedio.h.

The documentation for this class was generated from the following files:

tdecore

Public Types

Signals

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Enumeration Documentation

◆ closeModes

Constructor & Destructor Documentation

◆ TDEBufferedIO()

Implementation Details

◆ ~TDEBufferedIO()

Member Function Documentation

◆ bytesAvailable()

◆ bytesToWrite()

◆ bytesWritten

◆ canReadLine()

◆ closed

◆ closeNow()

◆ consumeReadBuffer()

◆ consumeWriteBuffer()

◆ feedReadBuffer()

◆ feedWriteBuffer()

◆ peekBlock()

◆ readBufferSize()

◆ setBufferSize()

◆ unreadBlock()

◆ virtual_hook()

◆ waitForMore()

◆ writeBufferSize()

Member Data Documentation

◆ inBuf

◆ inBufIndex

◆ outBuf

◆ outBufIndex

tdecore

tdecore