The SystemSignalWatcher class provides a convenient and comprehensive way to react to system defined signals. More...

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

Inheritance diagram for Qx::SystemSignalWatcher:

Public Types
enum	Signal { None = 0x0 , Interrupt = 0x1 , HangUp = 0x2 , Quit = 0x4 , Terminate = 0x8 , Abort = 0x10 }

typedef QFlags< Signal >	Signals

Signals
void	signaled (Signal s, bool *handled)

Public Member Functions
	SystemSignalWatcher ()

	~SystemSignalWatcher ()

bool	isRegistered () const

bool	isWatching () const

void	stop ()

void	watch (Signals s)

Signals	watching () const

void	yield ()

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)

void	killTimer (Qt::TimerId 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::nanoseconds interval, Qt::TimerType timerType)

QThread *	thread () const const

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

SystemSignalWatcher acts as user friendly replacement for the troubled std::signal, in a similar vein to sigaction(), but is cross-platform and features a Qt-oriented interface, unlike the latter.

Any number of watchers can be created in any thread and are initially inactive, with the first call to watch() with a value other than Signal::None registering the watcher to listen for system signals. Signals are delivered to watchers on a last-registered, first-served basis, where each watcher can choose whether to block the signal from further handling, or allow it to proceed to the next watcher in the list in a similar fashion to event filters. If no watcher marks the signal as handled, the default system handler for the signal is called.

Which system signals a given watcher is waiting for can be changed at any time, but its position in the delivery priority list is maintained until it's destroyed or yield() is called.

See also: watch() and signaled().

Member Typedef Documentation

◆ Signals

Qx::SystemSignalWatcher::Signals

The SystemSignalWatcher::Signals type is a typedef for QFlags< SystemSignalWatcher::Signal>. It stores an OR combination of SystemSignalWatcher::Signal values.

See also: signaled().

Member Enumeration Documentation

◆ Signal

enum Qx::SystemSignalWatcher::Signal

This enum specifies the system signal that was received by the watcher.

Each system signal is based on a standard POSIX signal, though only a subset are supported. On Windows, native signals are mapped to their nearest POSIX equivalents, or a reasonable alternative if there is none, as shown below:

Mapping of native signals to SystemSignalWatcher::Signal
Signal	Linux	Windows
Interrupt	SIGINT	CTRL_C_EVENT
HangUp	SIGHUP	CTRL_CLOSE_EVENT
Quit	SIGQUIT	CTRL_BREAK_EVENT
Terminate	SIGTERM	CTRL_SHUTDOWN_EVENT
Abort	SIGABRT	CTRL_LOGOFF_EVENT

Enumerator
None	No signals to watch for.
Interrupt	Terminal interrupt signal.
HangUp	Hangup signal.
Quit	Terminal quit signal.
Terminate	Termination signal.
Abort	Process abort signal.

Constructor & Destructor Documentation

◆ SystemSignalWatcher()

Qx::SystemSignalWatcher::SystemSignalWatcher ( )

Creates an inactive SystemSignalWatcher without a dispatch priority.

◆ ~SystemSignalWatcher()

Qx::SystemSignalWatcher::~SystemSignalWatcher ( )

Deactivates and deletes the SystemSignalWatcher.

Member Function Documentation

◆ isRegistered()

bool Qx::SystemSignalWatcher::isRegistered ( ) const

Returns true if the watcher has been used before at any point (that is, watch() has been called with a value other than Signal::None), and has a position in the dispatch priority list; otherwise, returns false.

See also: isWatching().

◆ isWatching()

bool Qx::SystemSignalWatcher::isWatching ( ) const

Returns true if the watcher is waiting for at least one system signal; otherwise, returns false.

See also: watching().

◆ signaled

void Qx::SystemSignalWatcher::signaled	(	Signal	s,
		bool *	handled )

signal

This signal is emitted when the watcher has received a system signal that it's waiting for, with s containing the signal.

The slot connected to this signal should set handled to true in order to indicate that the system signal has been fully handled and it should be discarded, or false to allow the signal to pass on to the next SystemSignalWatcher in the dispatch list. If all applicable watchers set handled to false, the system default handler for s is triggered.

Warning: It is not possible to use a QueuedConnection to connect to this signal and control further handling of s, as the signal will return immediately and use the default value of handled (false). If you do connect to this signal with a QueuedConnection just to be notified of when s has been received, but not to have influence on whether or not further watchers should be notified, do not deference the handled pointer as it will no longer be valid.

◆ stop()

void Qx::SystemSignalWatcher::stop ( )

Stops the watcher from responding to any system signal. This is equivalent to:

myWatcher.watch(Signal::None)

Note: Although this effectively disables the watcher, its position in the dispatch queue is not changed, should it start watching for system signals again later.

See also: watch() and isWatching().

◆ watch()

void Qx::SystemSignalWatcher::watch ( Signals s )

Starts watching for any of the system signals that make up s, or stops the watcher if s is only Signal::None, in which case the watch is stopped immediately and any "in-flight" signals are ignored.

Note: The first time this function is called with any signal flags set in s, the watcher is registered as the first to receive any applicable signals, and will remain so until additional watchers are registered, this watcher is destroyed, or yield() is called. The dispatch order is independent of signals watched, so once a watcher has been registered, calling this function again will only change which signals it pays attention to, but will not change its dispatch priority.

See also: stop(), isRegistered(), and isWatching().

◆ watching()

SystemSignalWatcher::Signals Qx::SystemSignalWatcher::watching ( ) const

Returns the system signals that the watcher is waiting for, or Signal::None if the watcher is not currently waiting for any.

See also: isWatching().

◆ yield()

void Qx::SystemSignalWatcher::yield ( )

If the watcher has been registered, it's moved to the back of dispatch priority list so that it is the last to be able to handle system signals; otherwise, this function does nothing.

See also: stop().

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

qx-systemsignalwatcher.h
qx-systemsignalwatcher.cpp

Public Types

Signals

Public Member Functions

Additional Inherited Members