QSystemSemaphore 类

QSystemSemaphore 类提供了通用计数信号量。更多...

头文件	#include <QSystemSemaphore>
CMake	find_package(Qt6 REQUIRED COMPONENTS Core) target_link_libraries(mytarget PRIVATE Qt6::Core)
qmake	QT += core

包含所有成员，包括继承的成员

公共类型

枚举	AccessMode { Open, Create }
枚举	SystemSemaphoreError { NoError, PermissionDenied, KeyError, AlreadyExists, NotFound, …, UnknownError }

公共函数

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

详细描述

系统信号量是 QSemaphore 的一种泛化。通常，信号量用于保护一定数量的相同资源。

与较轻的对应物类似，QSystemSemaphore 可以从多个线程访问。与 QSemaphore 不同，QSystemSemaphore 也可以从多个进程访问。这意味着 QSystemSemaphore 是一个更重的类，所以如果你的应用程序没有在多个进程间访问信号量的需求，你可能会想使用 QSemaphore。

信号量支持两种基本操作，acquire() 和 release()

acquire() 尝试获取一个资源。如果资源不可用，调用将阻塞，直到资源变得可用。然后获取资源并返回。

release() 释放一个资源以便其他进程可以获取。该函数也可以带有一个参数 n > 1，此时会释放 n 个资源。

系统信号量通过一个键来标识，键由QNativeIpcKey表示。可以使用platformSafeKey()跨平台地创建一个键。通过使用QSystemSemaphore构造函数并且传递参数AccessMode::Create时，可以创建一个系统信号量。一旦创建成功，其他进程可以使用相同的键和一个AccessMode::Open的访问模式参数附加到同一个信号量。

示例：创建一个系统信号量

QSystemSemaphore sem(QSystemSemaphore::platformSafeKey("market"), 3, QSystemSemaphore::Create);
                             // resources available == 3
sem.acquire();               // resources available == 2
sem.acquire();               // resources available == 1
sem.acquire();               // resources available == 0
sem.release();               // resources available == 1
sem.release(2);              // resources available == 3

有关关键类型、特定平台的限制以及与较旧或非Qt应用程序的互操作性的详细信息，请参阅原生IPC键文档。这包括了苹果平台上沙箱应用的必要信息，包括通过苹果应用商店获得的全部应用。

也请参见进程间通信、QSharedMemory和QSemaphore。

成员类型文档

枚举 QSystemSemaphore::AccessMode

此枚举用于构造函数和setKey()。它的目的是在Unix系统上解决信号量在崩溃中恢复的问题。在Unix中，当一个信号量在崩溃中恢复后，我们需要一种方法来强制它在系统重新使用信号量时重置其资源计数。在信号量无法在崩溃中恢复的Windows上，此枚举没有效果。

常量	值	描述
`QSystemSemaphore::Open`	`0`	如果信号量已存在，则其初始资源计数不会重置。如果信号量不存在，则创建它并设置其初始资源计数。
`QSystemSemaphore::Create`	`1`	QSystemSemaphore会将信号量设为所有者并设置其资源计数为所需的值，无论信号量是否已存在并通过崩溃恢复。当构造第一个特定键的信号量并且知道如果信号量已存在，则它可能只因为崩溃而存在时，应将此值传递给构造函数。在信号量无法在崩溃中恢复的Windows上，Create和Open具有相同的操作行为。

枚举 QSystemSemaphore::SystemSemaphoreError

常量	值	描述
`QSystemSemaphore::NoError`	`0`	未发生错误。
`QSystemSemaphore::PermissionDenied`	`1`	操作失败，因为调用者没有所需的权限。
`QSystemSemaphore::KeyError`	`2`	操作失败，因为键无效。
`QSystemSemaphore::AlreadyExists`	`3`	操作失败，因为指定键的系统信号量已经存在。
`QSystemSemaphore::NotFound`	`4`	操作失败，因为无法找到指定键的系统信号量。
`QSystemSemaphore::OutOfResources`	`5`	操作失败，因为可用内存不足。
`QSystemSemaphore::UnknownError`	`6`	发生了其他事情，结果很差。

成员函数文档

QSystemSemaphore::QSystemSemaphore(const QNativeIpcKey &key, int initialValue = 0, QSystemSemaphore::AccessMode mode = Open)

请求指定键的系统信号量。参数initialValue和mode的使用规则如下，这些规则取决于系统。

在Unix系统中，如果模式为Open且系统已有一个通过键标识的信号量，则使用该信号量，并且不改变信号量的资源计数，即初始值被忽略。但如果系统没有通过键标识的信号量，它会为该键创建一个新的信号量并将资源计数设置为初始值。

在Unix系统中，如果模式为Create且系统已有一个通过键标识的信号量，则使用该信号量，并将其资源计数设置为初始值。如果系统没有通过键标识的信号量，它会为该键创建一个新的信号量并将资源计数设置为初始值。

在Windows中，忽略模式，系统总是尝试为指定的键创建信号量。如果系统中没有已通过键标识的信号量，则创建该信号量并将资源计数设置为初始值。但如果系统已有一个通过键标识的信号量，则使用该信号量并忽略初始值。

模式参数仅在Unix系统中用于处理信号量在一个进程崩溃后仍存在的情形。在这种情况下，下一个为具有相同键分配信号量的进程将获得那个在崩溃中幸存下来的信号量，并且除非模式为Create，否则资源计数将不会重置为初始值，而是保留由崩溃进程赋予的初始值。

另请参阅acquire() 和 key()。

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

请求一个由旧式键key标识的系统信号量。

`[noexcept]` QSystemSemaphore::~QSystemSemaphore()

析构函数销毁QSystemSemaphore对象，但如果这个QSystemSemaphore实例是该系统信号量的最后一个是存在的，则不会从系统中删除底层的系统信号量。

析构函数的两个重要副作用依赖于系统。在Windows中，如果已经为该信号量调用过acquire()但未调用release，则析构函数不会调用release()，也不会在进程正常退出时释放资源。这将是程序中的一个错误，可能是另一个尝试获取相同资源的进程出现死锁的原因。在Unix中，在调用析构函数之前未释放的已获取资源将在进程退出时自动释放。

bool QSystemSemaphore::acquire()

如果可用，则获取由该信号量保护的资源中的一个，如果有一个可用就返回true。如果所有由该信号量保护的资源已经被获取，调用将阻塞直到在其他进程或线程有相同键的信号量释放其中之一。

如果返回值是false，则表示系统发生了错误。通过调用error()来获取指示发生哪个错误的QSystemSemaphore::SystemSemaphoreError的值。

另请参阅release。

QSystemSemaphore::SystemSemaphoreError QSystemSemaphore::error() const

返回一个值，指示是否发生错误以及错误的类型。

另请参阅errorString。

QString QSystemSemaphore::errorString() const

返回上次发生错误的文本描述。如果error()返回一个错误值，请调用此函数以获取描述错误的文本字符串。

另请参阅error。

QString QSystemSemaphore::key() const

返回分配给此系统信号量的遗留关键字。关键字是从其他进程访问信号量时使用的名称。

另请参阅setKey。

QNativeIpcKey QSystemSemaphore::nativeIpcKey() const

返回分配给此系统信号量的关键字。关键字是从其他进程访问信号量时使用的名称。

您可以使用本地关键字来访问未由 Qt 创建的系统信号量或授权非 Qt 应用程序。有关更多信息，请参阅本地 IPC 关键字。

另请参阅setNativeKey。

bool QSystemSemaphore::release(int n = 1)

释放信号量保护的 n 资源。除非发生系统错误，否则返回 true。

示例：创建一个具有五个资源的系统信号量；获取它们并释放它们。

QSystemSemaphore sem(QSystemSemaphore::platformSafeKey("market"), 5, QSystemSemaphore::Create);
for (int i = 0; i < 5; ++i)  // acquire all 5 resources
    sem.acquire();
sem.release(5);              // release the 5 resources

此函数还可以“创建”资源。例如，在上述语句序列之后，如果我们添加以下语句

sem.release(10);          // "create" 10 new resources

现在由信号量保护的资源有十个，再加上已有的五个。通常不应使用此函数来创建更多资源。

另请参阅acquire。

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

此函数与构造函数的功能相同。它重建此 QSystemSemaphore 对象。如果新的 key 与旧关键字不同，调用此函数就像调用带有旧关键字的信号量析构函数，然后调用构造函数以使用新的 key 创建新的信号量一样。 initialValue 和 mode 参数的定义与构造函数中定义的一样。

另请参阅QSystemSemaphore() 和 key。

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

此函数在原生前缀从另一个进程共享时很有用。有关更多信息，请参阅原生 IPC 键。

另请参阅QSystemSemaphore() 和 nativeIpcKey。