Abstract IODevice with an internal read buffer. More...

#include <bufferediodevice.h>

Inheritance diagram for BufferedIODevice:

[legend]

Collaboration diagram for BufferedIODevice:

[legend]

Public Member Functions
	BufferedIODevice (ObjectBase *parent=nullptr)
	Constructs a BufferedIODevice.

virtual	~BufferedIODevice ()
	Destructor.

int64_t	read (void *data, int64_t maxSize) override
	Reads up to maxSize bytes into data.

int64_t	bytesAvailable () const override
	Returns the number of bytes available for reading.

Error	setReadBuffer (Buffer &&buf)
	Replaces the internal read buffer.

const Buffer &	readBuffer () const
	Returns a const reference to the current read buffer.

size_t	readBufferSize () const
	Returns the capacity of the read buffer.

Buffer	readLine (size_t maxLength=0)
	Reads a line of text up to a newline character.

Buffer	readAll ()
	Reads all available data from the device.

Buffer	readBytes (size_t maxBytes)
	Reads up to maxBytes bytes and returns as a Buffer.

bool	canReadLine () const
	Returns true if a complete line is available for reading.

int64_t	peek (void *buf, size_t maxBytes) const
	Reads up to maxBytes without consuming them.

Buffer	peek (size_t maxBytes) const
	Reads up to maxBytes without consuming them.

void	setUnbuffered (bool enable)
	Enables or disables unbuffered mode.

bool	isUnbuffered () const
	Returns true if unbuffered mode is enabled.

Public Member Functions inherited from IODevice
	IODevice (ObjectBase *parent=nullptr)
	Constructs an IODevice.

virtual	~IODevice ()
	Destructor.

virtual Error	open (OpenMode mode)=0
	Opens the device with the specified mode.

virtual Error	close ()=0
	Closes the device.

virtual bool	isOpen () const =0
	Returns true if the device is open.

virtual int64_t	write (const void *data, int64_t maxSize)=0
	Writes up to maxSize bytes from data.

virtual void	flush ()
	Flushes any buffered output data to the underlying device.

virtual bool	waitForReadyRead (unsigned int timeoutMs=0)
	Waits until data is available for reading or timeout.

virtual bool	waitForBytesWritten (unsigned int timeoutMs=0)
	Waits until all pending data has been written or timeout.

virtual bool	isSequential () const
	Returns true if the device is sequential (non-seekable).

virtual Error	seek (int64_t pos)
	Seeks to the given byte offset from the beginning.

virtual int64_t	pos () const
	Returns the current read/write position.

virtual Result< int64_t >	size () const
	Returns the total size of the device in bytes.

virtual bool	atEnd () const
	Returns true if the current position is at the end.

OpenMode	openMode () const
	Returns the current open mode.

bool	isReadable () const
	Returns true if the device is readable.

bool	isWritable () const
	Returns true if the device is writable.

Error	error () const
	Returns the current error state.

void	clearError ()
	Clears the error state to Ok.

	PROMEKI_SIGNAL (readyRead)
	Emitted when data is available for reading.

	PROMEKI_SIGNAL (bytesWritten, int64_t)
	Emitted when bytes have been written.

	PROMEKI_SIGNAL (errorOccurred, Error)
	Emitted when an error occurs.

	PROMEKI_SIGNAL (aboutToClose)
	Emitted just before the device is closed.

Public Member Functions inherited from ObjectBase
	ObjectBase (ObjectBase *p=nullptr)
	Default ObjectBase constructor.

virtual	~ObjectBase ()
	Destructor. Emits aboutToDestroy, detaches from parent, and destroys children.

ObjectBase *	parent () const
	Returns the parent object, if one. nullptr if none.

void	setParent (ObjectBase *p)
	Sets the parent of this object. If the object already has a parent, it will be removed as a child from the old parent and added as a child to the new one.

const ObjectBaseList &	childList () const
	Returns a list of children of this object.

template<typename... Args>
int	registerSlot (Slot< Args... > *slot)
	Registers a slot with this object and assigns it an ID.

EventLoop *	eventLoop () const
	Returns the EventLoop this object is affiliated with.

void	moveToThread (EventLoop *loop)
	Changes the EventLoop affinity of this object.

int	startTimer (unsigned int intervalMs, bool singleShot=false)
	Starts a timer on this object's EventLoop.

void	stopTimer (int timerId)
	Stops a timer previously started with startTimer().

template<typename... Args>
PROMEKI_NAMESPACE_BEGIN void	connect (Signal< Args... > signal, Slot< Args... > slot)

Protected Member Functions
virtual int64_t	readFromDevice (void *data, int64_t maxSize)=0
	Reads raw data from the underlying device.

virtual int64_t	deviceBytesAvailable () const
	Returns the number of bytes available from the device.

size_t	bufferedBytesUnconsumed () const
	Returns the number of buffered bytes not yet consumed.

void	ensureReadBuffer ()
	Ensures the read buffer is allocated.

void	resetReadBuffer ()
	Resets the read buffer cursors.

Protected Member Functions inherited from IODevice
void	setOpenMode (OpenMode mode)
	Sets the open mode.

void	setError (const Error &err)
	Sets the error state and emits errorOccurred.

Protected Member Functions inherited from ObjectBase
ObjectBase *	signalSender ()
	Returns the ObjectBase that emitted the signal currently being handled.

virtual void	event (Event *e)
	Called by EventLoop to deliver events to this object.

virtual void	timerEvent (TimerEvent *e)
	Called when a timer fires for this object.

Additional Inherited Members
Public Types inherited from IODevice
enum	OpenMode { NotOpen = 0x00 , ReadOnly = 0x01 , WriteOnly = 0x02 , ReadWrite = ReadOnly \| WriteOnly , Append = 0x04 \| WriteOnly }
	Mode flags controlling how a device is opened. More...

Public Types inherited from ObjectBase
using	SlotVariantFunc = std::function< void(const VariantList &)>
	Function type for invoking a slot with a list of Variants.

Static Public Member Functions inherited from ObjectBase
static const MetaInfo &	metaInfo ()
	Returns the MetaInfo for the ObjectBase class.

template<typename... Args>
static void	connect (Signal< Args... > signal, Slot< Args... > slot)
	connects a signal and slot together. This function assumes both the signal and slot exist in a ObjectBase or derived object

Public Attributes inherited from ObjectBase
Signal< ObjectBase * >	aboutToDestroySignal = Signal< ObjectBase * >(this, aboutToDestroySignalName)

Static Public Attributes inherited from ObjectBase
static constexpr const char *	aboutToDestroySignalName = PROMEKI_STRINGIFY( aboutToDestroy ) "(" PROMEKI_STRINGIFY_ARGS( ObjectBase * ) ")"

static SignalMeta	aboutToDestroySignalMeta = SignalMeta(metaInfo(), aboutToDestroySignalName)

Detailed Description

Abstract IODevice with an internal read buffer.

Derives from IODevice and overrides read() to serve data from an internal Buffer. Subclasses implement readFromDevice() for raw I/O; the remaining pure virtuals (open, close, isOpen, write) stay pure for concrete subclasses like File to provide.

The read buffer is allocated lazily on first open (default 8192 bytes) or can be replaced via setReadBuffer() before opening.

When unbuffered mode is enabled via setUnbuffered(), all reads bypass the internal buffer and go directly to readFromDevice().

Constructor & Destructor Documentation

◆ BufferedIODevice()

BufferedIODevice::BufferedIODevice ( ObjectBase * parent = nullptr )

Constructs a BufferedIODevice.

Parameters

parent The parent object, or nullptr.

Member Function Documentation

◆ bufferedBytesUnconsumed()

size_t BufferedIODevice::bufferedBytesUnconsumed ( ) const

inlineprotected

Returns the number of buffered bytes not yet consumed.

Subclasses that override pos() should subtract this value from the raw device position so that pos() reflects the logical read position rather than the device-level position (which may be ahead due to read-ahead buffering).

Returns: The number of unconsumed bytes in the read buffer.

◆ bytesAvailable()

int64_t BufferedIODevice::bytesAvailable ( ) const

overridevirtual

Returns the number of bytes available for reading.

Returns buffered bytes plus deviceBytesAvailable(). When unbuffered mode is enabled, returns only deviceBytesAvailable().

Returns: The number of bytes available.

Reimplemented from IODevice.

◆ canReadLine()

bool BufferedIODevice::canReadLine ( ) const

Returns true if a complete line is available for reading.

Checks whether a newline character exists in the buffered data. Returns false when Unbuffered is true.

Returns: true if a newline is present in the buffer.

◆ deviceBytesAvailable()

virtual int64_t BufferedIODevice::deviceBytesAvailable ( ) const

protectedvirtual

Returns the number of bytes available from the device.

The default implementation returns 0. Subclasses may override to report device-level availability.

Returns: The number of bytes available from the device.

Reimplemented in File.

◆ ensureReadBuffer()

void BufferedIODevice::ensureReadBuffer ( )

protected

Ensures the read buffer is allocated.

Called during open(). If no custom buffer has been set, allocates a default 8192-byte buffer.

◆ isUnbuffered()

bool BufferedIODevice::isUnbuffered ( ) const

inline

Returns true if unbuffered mode is enabled.

Returns: true if reads bypass the internal buffer.

◆ peek() [1/2]

Buffer BufferedIODevice::peek ( size_t maxBytes ) const

Reads up to maxBytes without consuming them.

Returns empty Buffer when Unbuffered is true.

Parameters

maxBytes Maximum number of bytes to peek.

Returns: A Buffer containing the peeked data.

◆ peek() [2/2]

int64_t BufferedIODevice::peek	(	void *	buf,
		size_t	maxBytes
	)		const

Reads up to maxBytes without consuming them.

Returns 0 when Unbuffered is true.

Parameters

buf	Pointer to the destination buffer.
maxBytes	Maximum number of bytes to peek.

Returns: The number of bytes peeked.

◆ read()

int64_t BufferedIODevice::read	(	void *	data,
		int64_t	maxSize
	)

overridevirtual

Reads up to maxSize bytes into data.

Serves data from the internal read buffer when possible. Large reads (>= buffer capacity) bypass the buffer and go directly to readFromDevice(). When unbuffered mode is enabled, all reads bypass the buffer.

Parameters

data	Pointer to the buffer to read into.
maxSize	Maximum number of bytes to read.

Returns: The number of bytes read, or -1 on error.

Implements IODevice.

◆ readAll()

Buffer BufferedIODevice::readAll ( )

Reads all available data from the device.

Returns: A Buffer containing all data.

◆ readBuffer()

const Buffer & BufferedIODevice::readBuffer ( ) const

inline

Returns a const reference to the current read buffer.

Returns: The internal read buffer.

◆ readBufferSize()

size_t BufferedIODevice::readBufferSize ( ) const

inline

Returns the capacity of the read buffer.

Returns: The buffer size in bytes, or 0 if not yet allocated.

◆ readBytes()

Buffer BufferedIODevice::readBytes ( size_t maxBytes )

Reads up to maxBytes bytes and returns as a Buffer.

Parameters

maxBytes Maximum number of bytes to read.

Returns: A Buffer containing the read data.

◆ readFromDevice()

virtual int64_t BufferedIODevice::readFromDevice	(	void *	data,
		int64_t	maxSize
	)

protectedpure virtual

Reads raw data from the underlying device.

Subclasses must implement this to perform actual I/O.

Parameters

data	Pointer to the buffer to read into.
maxSize	Maximum number of bytes to read.

Returns: The number of bytes read, or -1 on error.

Implemented in File.

◆ readLine()

Buffer BufferedIODevice::readLine ( size_t maxLength = 0 )

Reads a line of text up to a newline character.

Reads until a newline ('\n') is found or maxLength bytes have been read. The newline is included in the result.

Parameters

maxLength Maximum bytes to read (0 = no limit).

Returns: A Buffer containing the line data.

◆ resetReadBuffer()

void BufferedIODevice::resetReadBuffer ( )

protected

Resets the read buffer cursors.

Called during close() to reset the buffer state. The buffer itself is retained for reuse.

◆ setReadBuffer()

Error BufferedIODevice::setReadBuffer ( Buffer && buf )

Replaces the internal read buffer.

Only allowed when the device is not open. The buffer must be host-accessible (e.g. system RAM or secure memory).

Parameters

buf	The replacement buffer.

Returns: Error::Ok on success, Error::AlreadyOpen if the device is open, or Error::NotHostAccessible if the buffer is not host-accessible.

◆ setUnbuffered()

void BufferedIODevice::setUnbuffered ( bool enable )

Enables or disables unbuffered mode.

When switching to unbuffered while the device is open, the internal read buffer is drained and reset. When switching back to buffered while open, the read buffer is re-ensured.

Parameters

enable true to bypass the internal buffer.

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

include/promeki/core/bufferediodevice.h

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ BufferedIODevice()

Member Function Documentation

◆ bufferedBytesUnconsumed()

◆ bytesAvailable()

◆ canReadLine()

◆ deviceBytesAvailable()

◆ ensureReadBuffer()

◆ isUnbuffered()

◆ peek() [1/2]

◆ peek() [2/2]

◆ read()

◆ readAll()

◆ readBuffer()

◆ readBufferSize()

◆ readBytes()

◆ readFromDevice()

◆ readLine()

◆ resetReadBuffer()

◆ setReadBuffer()

◆ setUnbuffered()