The ProcessBider class monitors the presence of a process and signals when that process ends. More...

#include <qx/core/qx-processbider.h>

Collaboration diagram for Qx::ProcessBider:

Public Types
enum	ResultType { Fail , Expired , Abandoned }

Public Slots
void	closeProcess (std::chrono::milliseconds timeout=1000ms, bool force=false)

void	start ()

void	stop ()

Signals
void	errorOccurred (ProcessBiderError error)

void	established ()

void	finished (ResultType result)

void	graceStarted ()

void	processClosing ()

void	processStopped ()

void	started ()

void	stopped ()

Public Member Functions
	ProcessBider (QObject *parent=nullptr, const QString &processName={})

bool	initialGrace () const

bool	isBiding () const

std::chrono::milliseconds	pollRate () const

QString	processName () const

std::chrono::milliseconds	respawnGrace () const

void	setInitialGrace (bool initialGrace)

void	setPollRate (std::chrono::milliseconds rate)

void	setProcessName (const QString &name)

void	setRespawnGrace (std::chrono::milliseconds grace)

Public Member Functions inherited from QObject
	QObject (QObject *parent)

QBindable< QString >	bindableObjectName ()

bool	blockSignals (bool block)

const QObjectList &	children () const const

QMetaObject::Connection	connect (const QObject sender, const char signal, const char *method, Qt::ConnectionType type) const const

void	deleteLater ()

void	destroyed (QObject *obj)

bool	disconnect (const char signal, const QObject receiver, const char *method) const const

bool	disconnect (const QObject receiver, const char method) const const

void	dumpObjectInfo () const const

void	dumpObjectTree () const const

QList< QByteArray >	dynamicPropertyNames () const const

virtual bool	event (QEvent *e)

virtual bool	eventFilter (QObject watched, QEvent event)

T	findChild (QAnyStringView name, Qt::FindChildOptions options) const const

T	findChild (Qt::FindChildOptions options) const const

QList< T >	findChildren (const QRegularExpression &re, Qt::FindChildOptions options) const const

QList< T >	findChildren (QAnyStringView name, Qt::FindChildOptions options) const const

QList< T >	findChildren (Qt::FindChildOptions options) const const

bool	inherits (const char *className) const const

void	installEventFilter (QObject *filterObj)

bool	isQuickItemType () const const

bool	isWidgetType () const const

bool	isWindowType () const const

void	killTimer (int id)

virtual const QMetaObject *	metaObject () const const

bool	moveToThread (QThread *targetThread)

QString	objectName () const const

void	objectNameChanged (const QString &objectName)

QObject *	parent () const const

QVariant	property (const char *name) const const

	Q_CLASSINFO (Name, Value)

	Q_EMIT Q_EMIT

	Q_ENUM (...)

	Q_ENUM_NS (...)

	Q_ENUMS (...)

	Q_FLAG (...)

	Q_FLAG_NS (...)

	Q_FLAGS (...)

	Q_GADGET Q_GADGET

	Q_GADGET_EXPORT (EXPORT_MACRO)

	Q_INTERFACES (...)

	Q_INVOKABLE Q_INVOKABLE

	Q_MOC_INCLUDE Q_MOC_INCLUDE

	Q_NAMESPACE Q_NAMESPACE

	Q_NAMESPACE_EXPORT (EXPORT_MACRO)

	Q_OBJECT Q_OBJECT

	Q_PROPERTY (...)

	Q_REVISION Q_REVISION

	Q_SET_OBJECT_NAME (Object)

	Q_SIGNAL Q_SIGNAL

	Q_SIGNALS Q_SIGNALS

	Q_SLOT Q_SLOT

	Q_SLOTS Q_SLOTS

T	qobject_cast (const QObject *object)

T	qobject_cast (QObject *object)

	QT_NO_CONTEXTLESS_CONNECT QT_NO_CONTEXTLESS_CONNECT

	QT_NO_NARROWING_CONVERSIONS_IN_CONNECT QT_NO_NARROWING_CONVERSIONS_IN_CONNECT

void	removeEventFilter (QObject *obj)

void	setObjectName (const QString &name)

void	setObjectName (QAnyStringView name)

void	setParent (QObject *parent)

bool	setProperty (const char *name, const QVariant &value)

bool	setProperty (const char *name, QVariant &&value)

bool	signalsBlocked () const const

int	startTimer (int interval, Qt::TimerType timerType)

int	startTimer (std::chrono::milliseconds interval, Qt::TimerType timerType)

QThread *	thread () const const

Friends
class	ProcessBiderManager

Additional Inherited Members
Static Public Member Functions inherited from QObject
QMetaObject::Connection	connect (const QObject sender, const char signal, const QObject receiver, const char method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject context, Functor functor, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method, Qt::ConnectionType type)

QMetaObject::Connection	connect (const QObject *sender, PointerToMemberFunction signal, Functor functor)

bool	disconnect (const QMetaObject::Connection &connection)

bool	disconnect (const QObject sender, const char signal, const QObject receiver, const char method)

bool	disconnect (const QObject sender, const QMetaMethod &signal, const QObject receiver, const QMetaMethod &method)

bool	disconnect (const QObject sender, PointerToMemberFunction signal, const QObject receiver, PointerToMemberFunction method)

QString	tr (const char sourceText, const char disambiguation, int n)

Public Attributes inherited from QObject
typedef	QObjectList

Protected Member Functions inherited from QObject
virtual void	childEvent (QChildEvent *event)

virtual void	connectNotify (const QMetaMethod &signal)

virtual void	customEvent (QEvent *event)

virtual void	disconnectNotify (const QMetaMethod &signal)

bool	isSignalConnected (const QMetaMethod &signal) const const

int	receivers (const char *signal) const const

QObject *	sender () const const

int	senderSignalIndex () const const

virtual void	timerEvent (QTimerEvent *event)

Properties inherited from QObject
	objectName

Detailed Description

Processes are specified by name in order to allow for an optional grace period in which the process is not considered to be finished if it restarts. The ability to specify an initial process ID may be added in the future.

On Windows this directly requests a wait from the OS. On Linux this uses polling.

Note: Monitoring external processes you don't have direct control over is tricky in that they can terminate at any time, and potentially be replaced with a different process using the same ID, including during the brief setup of the bide. While generally this won't be a problem, it's something to be kept in mind, especially when using slower poll rates.

See also: setPollRate().

Member Enumeration Documentation

◆ ResultType

enum Qx::ProcessBider::ResultType

This enum specifies the different conditions under which the finished() signal is emitted.

Enumerator

Fail

The bider was unable to hook the process for waiting, potentially due to a permissions issue.

Expired

The process ended and the grace period, if any, expired.

Abandoned

The bide was abandoned before the process ended.

See also: finished().

Constructor & Destructor Documentation

◆ ProcessBider()

Qx::ProcessBider::ProcessBider	(	QObject *	parent = nullptr,
		const QString &	processName = {} )

explicit

Constructs a process bider with parent, set to bide on the process with the name processName.

Member Function Documentation

◆ closeProcess

void Qx::ProcessBider::closeProcess	(	std::chrono::milliseconds	timeout = 1000ms,
		bool	force = false )

slot

Attempts to close the process.

First the process is signaled to shutdown gracefully, with timeout controlling how long the process has to terminate. Then, if the process is still running and force is true, the process will be terminated forcefully. errorOccurred() will be emitted if the closure ultimately fails.

On Windows if the process is elevated and the current process is not, this will attempt to run taskkill as an administrator to close the process, which may trigger a UAC prompt. Trying to close processes with greater permissions on Linux is not supported.

See also: processIsClosing().

◆ errorOccurred

void Qx::ProcessBider::errorOccurred ( ProcessBiderError error )

signal

This signal is emitted when a bide error occurs, with error containing details.

◆ established

void Qx::ProcessBider::established ( )

signal

This signal is emitted when the process is found and hooked for waiting, so it may be emitted multiple times if a grace period is set.

See also: processStopped().

◆ finished

void Qx::ProcessBider::finished ( ResultType result )

signal

This signal is emitted when the bide is complete, with result containing the reason.

See also: processStopped().

◆ graceStarted

void Qx::ProcessBider::graceStarted ( )

signal

This signal is emitted when the respawn grace begins, if set, and may be emitted multiple times if the process restarts.

It will be emitted immediately after processStopped(), and once after started() if the initial grace period is enabled.

See also: processStopped().

◆ initialGrace()

bool Qx::ProcessBider::initialGrace ( ) const

Returns true if the bider is currently configured to start with a grace period; otherwise, returns false.

The deafault is false.

See also: setInitialGrace() and respawnGrace().

◆ isBiding()

bool Qx::ProcessBider::isBiding ( ) const

Returns true if the bide is ongoing; otherwise, returns false.

See also: start() and finished().

◆ pollRate()

std::chrono::milliseconds Qx::ProcessBider::pollRate ( ) const

Note: This function is only available on Linux

Returns the rate at which the process is checked.

The default is 500ms.

See also: setPollRate().

◆ processClosing

void Qx::ProcessBider::processClosing ( )

signal

This signal is emitted when an attempt is made to close the process via closeProcess().

See also: closeProcess().

◆ processName()

QString Qx::ProcessBider::processName ( ) const

Returns the name of the process to bide on.

See also: setProcessName().

◆ processStopped

void Qx::ProcessBider::processStopped ( )

signal

This signal is emitted when the process stops, which means it may be emitted multiple times if a grace period is set.

See also: established().

◆ respawnGrace()

std::chrono::milliseconds Qx::ProcessBider::respawnGrace ( ) const

Returns how long the process has to restart in order to not be considered stopped.

The default is 0, which means there is no grace period.

See also: setRespawnGrace() and initialGrace().

◆ setInitialGrace()

void Qx::ProcessBider::setInitialGrace ( bool initialGrace )

Enables or disables the initial grace period.

If enabled, the bider will begin the bide with a grace period, which is useful if the process may be stopped when the bide starts and you want to wait for it to come back up.

When disabled, the bider will assume the proess is already running and try to hook it for waiting immediately after starting.

This setting has no effect if there is no grace set.

See also: initialGrace() and setRespawnGrace().

◆ setPollRate()

void Qx::ProcessBider::setPollRate ( std::chrono::milliseconds rate )

Note: This function is only available on Linux

Sets the rate at which the process is checked.

See also: pollRate().

◆ setProcessName()

void Qx::ProcessBider::setProcessName ( const QString & name )

Sets the name of the process to bide on to name.

See also: processName().

◆ setRespawnGrace()

void Qx::ProcessBider::setRespawnGrace ( std::chrono::milliseconds grace )

Sets how long the process has to restart in order to not be considered stopped.

The grace period does not end early if the process starts sooner and always runs to completion before checking if it's running due to technical limitations.

A value of 0 disables the grace period.

See also: respawnGrace() and setInitialGrace().

◆ start

void Qx::ProcessBider::start ( )

slot

Begins monitoring the process for closure.

See also: stop() and started().

◆ started

void Qx::ProcessBider::started ( )

signal

This signal is emitted when the bide is started.

See also: start() and stop().

◆ stop

void Qx::ProcessBider::stop ( )

slot

Abandons the bide, regardless of whether or not the process has closed.

See also: start() and stopped().

◆ stopped

void Qx::ProcessBider::stopped ( )

signal

This signal is emitted when the bide is abandoned via stop().

See also: stop() and start().

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

qx-processbider.h
qx-processbider.cpp

Public Types

Public Slots

Signals

Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ ResultType

Constructor & Destructor Documentation

◆ ProcessBider()

Member Function Documentation

◆ closeProcess

◆ errorOccurred

◆ established

◆ finished

◆ graceStarted

◆ initialGrace()

◆ isBiding()

◆ pollRate()

◆ processClosing

◆ processName()

◆ processStopped

◆ respawnGrace()

◆ setInitialGrace()

◆ setPollRate()

◆ setProcessName()

◆ setRespawnGrace()

◆ start

◆ started

◆ stop

◆ stopped