QSystemSemaphore Class

The QSystemSemaphore class provides a general counting system semaphore. More…

Header	`#include <QSystemSemaphore>`
CMake	`target_link_libraries(app PRIVATE Nt::Core)`
Module	Nt Core C++ Classes

List of all members, including inherited members

Public Types

enum	AccessMode
enum	SystemSemaphoreError

Public Functions

	QSystemSemaphore(const QString &key, int initialValue = 0, AccessMode mode = Open)
	~QSystemSemaphore()
void	setKey(const QString &key, int initialValue = 0, AccessMode mode = Open)
QString	key() const
bool	acquire()
bool	release(int n = 1)
SystemSemaphoreError	error() const
QString	errorString() const

Detailed Description

A system semaphore is a semaphore that several processes share, found by its key. Like a QSemaphore it guards a number of resources: acquire() takes one, waiting until there is one, and release() gives resources back.

QSystemSemaphore printers(u"org.example.printers"_s, 3, QSystemSemaphore::Create);
printers.acquire();
usePrinter();
printers.release();

The process that sets the system up passes Create, which makes the semaphore anew with the given count; the others pass Open and share it. A semaphore outlives a process that crashes, with whatever count it had; creating it with Create resets it.

See also QSharedMemory and QSemaphore.

Differences from Qt

The semaphore is a POSIX named semaphore, so the class works on Linux and macOS. A process cannot find a semaphore that another library made with a System V key. The semaphore is removed from the system when the object that created it is destroyed: processes that have it open keep using it, but a process that opens the key afterwards gets a new one. There is no QNativeIpcKey, and so no constructor that takes one and no nativeIpcKey().

The class is not built for Zephyr, where QT_NO_SYSTEMSEMAPHORE is defined instead. See Nt on Zephyr.

Member Type Documentation

enum QSystemSemaphore::AccessMode

How the semaphore of a key is taken up.

Constant	Description
`QSystemSemaphore::Open`	Use the semaphore if it exists, and create it with the initial count if it does not.
`QSystemSemaphore::Create`	Create the semaphore with the initial count, replacing one that a crashed process may have left behind.

enum QSystemSemaphore::SystemSemaphoreError

The errors that error() reports.

Constant	Description
`QSystemSemaphore::NoError`	The last operation succeeded.
`QSystemSemaphore::PermissionDenied`	The process may not use the semaphore.
`QSystemSemaphore::KeyError`	The key is empty or cannot be used.
`QSystemSemaphore::AlreadyExists`	The semaphore exists already.
`QSystemSemaphore::NotFound`	There is no semaphore with the key.
`QSystemSemaphore::OutOfResources`	The system has no room for another semaphore.
`QSystemSemaphore::UnknownError`	Something else went wrong; errorString() has the text of the system.

Member Function Documentation

[explicit] QSystemSemaphore::QSystemSemaphore(const QString &key, int initialValue = 0, AccessMode mode = Open)

Constructs a semaphore for key. With the mode Open the semaphore of the system is used if it exists and created with the count initialValue if not; with Create it is always created with that count. A negative initialValue counts as 0.

If the semaphore cannot be opened, error() says why and acquire() and release() fail.

See also setKey().

QSystemSemaphore::~QSystemSemaphore()

Destroys the object and closes the semaphore. Resources that were acquired are not released.

bool QSystemSemaphore::acquire()

Takes one resource, waiting until one is free. Returns true when it has it, and false if the semaphore is not open or the system reports an error.

See also release().

SystemSemaphoreError QSystemSemaphore::error() const

Returns what went wrong in the last operation, or NoError.

See also errorString().

QString QSystemSemaphore::errorString() const

Returns a text for the error of the last operation, or an empty string if it succeeded.

See also error().

QString QSystemSemaphore::key() const

Returns the key of the semaphore.

See also setKey().

bool QSystemSemaphore::release(int n = 1)

Gives n resources back, which need not have been acquired by this object. Returns true on success; releasing no resources succeeds, and a negative n fails.

See also acquire().

void QSystemSemaphore::setKey(const QString &key, int initialValue = 0, AccessMode mode = Open)

Closes the semaphore and takes up the one for key instead, with initialValue and mode as in the constructor.

See also key().