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

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

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 ()

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

typedef QFlags< Signal > 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