Base class to pull data from a base class into asynchronous devices such as QProcess or QTcpSocket. More...

Inheritance diagram for QtlDataPull:

Classes
class	Context
	Describe the context of one device. More...

Public Slots
bool	start (QIODevice *device)
	Start to transfer data into the specified device. More...

bool	start (const QList< QIODevice *> &devices)
	Start to transfer data into the several devices in parallel. More...

void	stop ()
	Force a premature stop of the data transfer. More...

void	stopCaller ()
	This slot stops the transfer on the device which sent the signal. More...

void	stopDevice (QIODevice *device)
	Stop the transfer on the specified device. More...

Signals
void	completed (bool success)
	Emitted when the transfer is completed on all devices. More...

void	deviceCompleted (QIODevice *device, bool success)
	Emitted when the transfer is completed on one device. More...

void	progress (qint64 current, qint64 maximum)
	Emitted when some progress in the data transfer is available. More...

void	started ()
	Emitted when the transfer is started. More...

Public Member Functions
	QtlDataPull (int minBufferSize=DEFAULT_MIN_BUFFER_SIZE, QtlLogger log=0, QObject parent=0)
	Constructor. More...

virtual	~QtlDataPull ()
	Destructor. More...

bool	isStarted () const
	Check if the data transfer is started. More...

QtlLogger *	log () const
	Get the message logger. More...

bool	progressAvailable () const
	Check if progress report is meaningful. More...

qint64	pulledSize () const
	Get the total size of all pulled data. More...

void	setAutoDelete (bool on)
	Set automatic object deletion on transfer completion. More...

void	setMaxPulledSize (qint64 size)
	Set the maximum number of bytes to pull. More...

void	setProgressIntervalInBytes (qint64 size)
	Set the interval between two emissions of progress(). More...

void	setProgressMaxHint (qint64 size)
	Set the probable ("hint") total size of the transfer. More...

Static Public Attributes
static const int	DEFAULT_MIN_BUFFER_SIZE = 128 * 1024
	Default minimum buffer size in bytes (128 kB). More...

Protected Member Functions
virtual void	cleanupTransfer (bool closed)
	Cleanup the transfer. More...

void	close ()
	Properly terminate the transfer. More...

virtual bool	initializeTransfer ()
	Initialize the transfer. More...

virtual bool	needTransfer (qint64 maxSize)=0
	Invoked when more data is needed. More...

bool	write (const void *data, int dataSize)
	Write data to all devices. More...

Private Slots
void	bytesWritten (qint64 bytes)
	Invoked when a device has written data. More...

void	deviceDestroyed (QObject *object)
	Invoked when a device object is destroyed. More...

void	processNewState ()
	Invoked from the event loop to process a new state. More...

Private Member Functions
void	deviceSpecificCleanup (QIODevice *dev, bool closed)
	Perform specific cleanup on a device, depending on its class. More...

void	deviceSpecificSetup (QIODevice *dev)
	Perform specific setup on a device, depending on its class. More...

bool	needMoreData () const
	Check if more data need to be pulled from the subclass. More...

void	processBytesWritten (QIODevice *dev, qint64 bytes)
	Invoked when a device has written data. More...

void	processNewStateLater ()
	The appropriate processing of the new state will be performed later, after returning in the event loop. More...

Private Attributes
bool	_autoDelete
	Automatic object deletion on transfer completion. More...

bool	_closed
	True when close() is requested by subclass. More...

QList< Context >	_devices
	Active output devices. More...

QtlLogger *	_log
	Message logger. More...

qint64	_maxIn
	Maximum data size to transfer. More...

int	_minBufferSize
	Lower limit of buffer size. More...

bool	_newStatePosted
	processNewState() is posted for execution. More...

QtlNullLogger	_nullLog
	Default logger. More...

int	_processingState
	A counter to protect processNewState(). More...

qint64	_progressInterval
	Emit progress() at this interval (input size in bytes). More...

qint64	_progressMaxHint
	Probable max input size, as reported by progress(). More...

qint64	_progressNext
	Emit next progress() at this input size. More...

QTime	_startTime
	Time of start operation. More...

qint64	_totalIn
	Total data transfered by write(). More...

Detailed Description

Base class to pull data from a base class into asynchronous devices such as QProcess or QTcpSocket.

This class is based on a "pull" model where the data are "pulled" from the subclass when it is appropriate to write to the device's input. QProcess and other asynchronous devices use an internal buffer mechanism. If the application writes data into the device much faster that the process or network can read, then the data accumulate in memory. I have not seen any limiting mechanism in the Qt source code. So, for huge amounts of data (such as video files), the application might saturate its virtual memory.

This class provides a regulation mechanism which avoids that issue. The subclass is "pulled" only when some space is available. On the other hand, this class assumes that input data are always available from the base class.

Constructor & Destructor Documentation

◆ QtlDataPull()

QtlDataPull::QtlDataPull	(	int	minBufferSize = `DEFAULT_MIN_BUFFER_SIZE`,
		QtlLogger *	log = `0`,
		QObject *	parent = `0`
	)

explicit

Constructor.

Parameters

[in]	minBufferSize	The minimum buffer size is the lower limit of the buffered data. When the amount of data not yet written to the device is lower than this size, new data is pulled from the subclass.
[in]	log	Where to log errors.
[in]	parent	Optional parent object.

◆ ~QtlDataPull()

QtlDataPull::~QtlDataPull ( )

virtual

Destructor.

Member Function Documentation

◆ setAutoDelete()

void QtlDataPull::setAutoDelete ( bool on )

inline

Set automatic object deletion on transfer completion.

Parameters

[in] on When true, the object deletes itself automatically at the end of the transfer or if the transfer failed to start. Use with care, the object must have been created on the heap.

◆ setMaxPulledSize()

void QtlDataPull::setMaxPulledSize ( qint64 size )

inline

Set the maximum number of bytes to pull.

After that number of bytes is read, a proper close is triggered.

Parameters

[in] size Maximum size in bytes. If negative, no maximum is applied.

◆ setProgressIntervalInBytes()

void QtlDataPull::setProgressIntervalInBytes ( qint64 size )

inline

Set the interval between two emissions of progress().

The interval is specified in number of input bytes. The signal progress() is emitted at most once in each interval but it not guaranteed that it is emitted on strict multiples of the interval size.

Parameters

[in] size Emit progress() each time that number of input bytes is read. If negative or zero, progress() is never emitted.

◆ setProgressMaxHint()

void QtlDataPull::setProgressMaxHint ( qint64 size )

inline

Set the probable ("hint") total size of the transfer.

This size is reported by progress() as maximum. This is useful only if a GUI needs to report the current percentage of the transfer.

Parameters

[in] size Probable total size of the transfer.

◆ progressAvailable()

bool QtlDataPull::progressAvailable ( ) const

inline

Check if progress report is meaningful.

Returns: True if progress interval and maximum hint are both set, false otherwise.

◆ isStarted()

bool QtlDataPull::isStarted ( ) const

inline

Check if the data transfer is started.

Returns: True if the transfer is started.

◆ pulledSize()

qint64 QtlDataPull::pulledSize ( ) const

inline

Get the total size of all pulled data.

Returns: Total pulled data size in bytes.

◆ log()

QtlLogger* QtlDataPull::log ( ) const

inline

Get the message logger.

Returns: The message logger.

◆ start [1/2]

bool QtlDataPull::start ( QIODevice * device )

slot

Start to transfer data into the specified device.

Parameters

[in] device Data destination. Must be open for write.

Returns: True if successfully started.

◆ start [2/2]

bool QtlDataPull::start ( const QList< QIODevice *> & devices )

slot

Start to transfer data into the several devices in parallel.

The data are pulled only once but duplicated to all devices.

Parameters

[in] devices Data destinations. Must be open for write.

Returns: True if successfully started.

◆ stop

void QtlDataPull::stop ( )

slot

Force a premature stop of the data transfer.

◆ stopDevice

void QtlDataPull::stopDevice ( QIODevice * device )

slot

Stop the transfer on the specified device.

Transfer will continue to the other devices. If the device was the last one, then the transfer is aborted.

Parameters

[in] device The device to remove from the transfer.

◆ stopCaller

void QtlDataPull::stopCaller ( )

slot

This slot stops the transfer on the device which sent the signal.

This is a convenience slot which can be connected to a signal from a destination device, any form of signal such as "finished", "completed", "aborted" or "disconnected" that the device may support.

Note that the following device's signals are automatically connected to this slot:

QProcess::finished()
QAbstractSocket::disconnected()

◆ started

void QtlDataPull::started ( )

signal

Emitted when the transfer is started.

◆ progress

void QtlDataPull::progress	(	qint64	current,
		qint64	maximum
	)

signal

Emitted when some progress in the data transfer is available.

Parameters

[in]	current	Current number of input bytes.
[in]	maximum	Total size of the data transfer. It is only a hint. When neither setProgressMaxHint() not setMaxPulledSize() were called, maximum is -1.

◆ deviceCompleted

void QtlDataPull::deviceCompleted	(	QIODevice *	device,
		bool	success
	)

signal

Emitted when the transfer is completed on one device.

This signal can be used to close, flush, disconnect or any other appropriate operation on the device.

Note that the following actions are automatically performed on various subclasses of QIODevice and the application does not need to take care about it.

QProcess::closeWriteChannel()
QAbstractSocket::disconnectFromHost()

Parameters

[in]	device	Device for which the transfer is completed.
[in]	success	True if all data were successfully transmitted to this device, false on premature error.

◆ completed

void QtlDataPull::completed ( bool success )

signal

Emitted when the transfer is completed on all devices.

The signal deviceCompleted() is sent once for each device. Then the signal completed() is sent once.

Parameters

[in] success True if all data were successfully transmitted to all device, false on premature error on at least one device.

◆ initializeTransfer()

virtual bool QtlDataPull::initializeTransfer ( )

inlineprotectedvirtual

Initialize the transfer.

May be reimplemented by subclass.

Returns: True on success, false on error. In case of error, the transfer is not started.

Reimplemented in QtsDvdDataPull, QtlFileDataPull, and QtsDvdProgramChainDemux.

◆ needTransfer()

virtual bool QtlDataPull::needTransfer ( qint64 maxSize )

protectedpure virtual

Invoked when more data is needed.

Must be reimplemented by subclass. An implementation will typically call write() to provide data. If no more data is available, an implementation must call close().

Parameters

[in] maxSize Maximum size in bytes of the requested transfer. If negative, there is not limit.

Returns: True on success, false on error. In case of error, the transfer is aborted and cleanupTransfer() will be called later.

Implemented in QtsDvdDataPull, QtlFileDataPull, and QtsDvdProgramChainDemux.

◆ cleanupTransfer()

virtual void QtlDataPull::cleanupTransfer ( bool closed )

inlineprotectedvirtual

Cleanup the transfer.

May be reimplemented by subclass.

Parameters

[in] closed If true, this is a clean termination, after the subclass called close(). When false, the transfer has been interrupted for an external reason.

Reimplemented in QtsDvdDataPull, QtlFileDataPull, and QtsDvdProgramChainDemux.

◆ write()

bool QtlDataPull::write	(	const void *	data,
		int	dataSize
	)

protected

Write data to all devices.

Must be called by subclass to transfer data.

Parameters

[in]	data	Address of data to transfer.
[in]	dataSize	Size in bytes of data to transfer.

Returns: True if all bytes are written on at least one device. False if all transfers failed. On error on one device, the transfer will be aborted automatically on this device and deviceCompleted() will be signalled.

◆ close()

void QtlDataPull::close ( )

protected

Properly terminate the transfer.

Must be called by subclass to signal the end of the transfer. The method cleanupTransfer() will be called later with closed set to true.

◆ bytesWritten

void QtlDataPull::bytesWritten ( qint64 bytes )

privateslot

Invoked when a device has written data.

Parameters

[in] bytes Number of bytes written.

◆ deviceDestroyed

void QtlDataPull::deviceDestroyed ( QObject * object )

privateslot

Invoked when a device object is destroyed.

◆ processNewState

void QtlDataPull::processNewState ( )

privateslot

Invoked from the event loop to process a new state.

◆ processNewStateLater()

void QtlDataPull::processNewStateLater ( )

private

The appropriate processing of the new state will be performed later, after returning in the event loop.

◆ processBytesWritten()

void QtlDataPull::processBytesWritten	(	QIODevice *	dev,
		qint64	bytes
	)

private

Invoked when a device has written data.

Parameters

[in]	dev	Destination device.
[in]	bytes	Number of bytes written.

◆ needMoreData()

bool QtlDataPull::needMoreData ( ) const

private

Check if more data need to be pulled from the subclass.

Returns: True is all active devices are underflow.

◆ deviceSpecificSetup()

void QtlDataPull::deviceSpecificSetup ( QIODevice * dev )

private

Perform specific setup on a device, depending on its class.

Parameters

[in] dev Device to setup.

◆ deviceSpecificCleanup()

void QtlDataPull::deviceSpecificCleanup	(	QIODevice *	dev,
		bool	closed
	)

private

Perform specific cleanup on a device, depending on its class.

Parameters

[in]	dev	Device to setup.
[in]	closed	True on normal termination, false if the transfer was aborted.

Member Data Documentation

◆ DEFAULT_MIN_BUFFER_SIZE

const int QtlDataPull::DEFAULT_MIN_BUFFER_SIZE = 128 * 1024

static

Default minimum buffer size in bytes (128 kB).

◆ _nullLog

QtlNullLogger QtlDataPull::_nullLog

private

Default logger.

◆ _log

QtlLogger* QtlDataPull::_log

private

Message logger.

◆ _autoDelete

bool QtlDataPull::_autoDelete

private

Automatic object deletion on transfer completion.

◆ _minBufferSize

int QtlDataPull::_minBufferSize

private

Lower limit of buffer size.

◆ _startTime

QTime QtlDataPull::_startTime

private

Time of start operation.

◆ _closed

bool QtlDataPull::_closed

private

True when close() is requested by subclass.

◆ _maxIn

qint64 QtlDataPull::_maxIn

private

Maximum data size to transfer.

◆ _progressInterval

qint64 QtlDataPull::_progressInterval

private

Emit progress() at this interval (input size in bytes).

◆ _progressMaxHint

qint64 QtlDataPull::_progressMaxHint

private

Probable max input size, as reported by progress().

◆ _progressNext

qint64 QtlDataPull::_progressNext

private

Emit next progress() at this input size.

◆ _totalIn

qint64 QtlDataPull::_totalIn

private

Total data transfered by write().

◆ _devices

QList<Context> QtlDataPull::_devices

private

Active output devices.

◆ _newStatePosted

bool QtlDataPull::_newStatePosted

private

processNewState() is posted for execution.

◆ _processingState

int QtlDataPull::_processingState

private

A counter to protect processNewState().

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

Classes

Public Slots

Signals

Public Member Functions

Static Public Attributes

Protected Member Functions

Private Slots

Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ QtlDataPull()

◆ ~QtlDataPull()

Member Function Documentation

◆ setAutoDelete()

◆ setMaxPulledSize()

◆ setProgressIntervalInBytes()

◆ setProgressMaxHint()

◆ progressAvailable()

◆ isStarted()

◆ pulledSize()

◆ log()

◆ start [1/2]

◆ start [2/2]

◆ stop

◆ stopDevice

◆ stopCaller

◆ started

◆ progress

◆ deviceCompleted

◆ completed

◆ initializeTransfer()

◆ needTransfer()

◆ cleanupTransfer()

◆ write()

◆ close()

◆ bytesWritten

◆ deviceDestroyed

◆ processNewState

◆ processNewStateLater()

◆ processBytesWritten()

◆ needMoreData()

◆ deviceSpecificSetup()

◆ deviceSpecificCleanup()

Member Data Documentation

◆ DEFAULT_MIN_BUFFER_SIZE

◆ _nullLog

◆ _log

◆ _autoDelete

◆ _minBufferSize

◆ _startTime

◆ _closed

◆ _maxIn

◆ _progressInterval

◆ _progressMaxHint

◆ _progressNext

◆ _totalIn

◆ _devices

◆ _newStatePosted

◆ _processingState