QSystemSemaphore 类提供常规计数系统信号量。 更多...
| 头： | #include <QSystemSemaphore> |
| CMake: |
find_package(Qt6 COMPONENTS Core REQUIRED)
target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
| enum | AccessMode { Open, Create } |
| enum | SystemSemaphoreError { NoError, PermissionDenied, KeyError, AlreadyExists, NotFound, …, UnknownError } |
| QSystemSemaphore (const QString & key , int initialValue = 0, QSystemSemaphore::AccessMode mode = Open) | |
| ~QSystemSemaphore () | |
| bool | acquire () |
| QSystemSemaphore::SystemSemaphoreError | error () const |
| QString | errorString () const |
| QString | key () const |
| bool | release (int n = 1) |
| void | setKey (const QString & key , int initialValue = 0, QSystemSemaphore::AccessMode mode = Open) |
信号量是互斥的一般化。互斥只可以锁定一次，而信号量可以多次获取。通常，信号量用于保护一定数量的恒等资源。
像其更轻搭档 QSemaphore ，可以访问 QSystemSemaphore 从多个 threads 。不像 QSemaphore ，还可以访问 QSystemSemaphore 从多个 processes 。这意味着 QSystemSemaphore 是更重的类，因此，若应用程序不需要跨多个进程访问信号量，则可能想要使用 QSemaphore .
信号量支持 2 基础操作 acquire () 和 release ():
acquire () tries to acquire one resource. If there isn't a resource available, the call blocks until a resource becomes available. Then the resource is acquired and the call returns.
release () releases one resource so it can be acquired by another process. The function can also be called with a parameter n > 1, which releases n resources.
A system semaphore is created with a string key that other processes can use to use the same semaphore.
范例：创建系统信号量
QSystemSemaphore sem("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
A typical application of system semaphores is for controlling access to a circular buffer shared by a producer process and a consumer processes.
当使用此类时，要意识到以下平台差异：
Windows: QSystemSemaphore does not own its underlying system semaphore. Windows owns it. This means that when all instances of QSystemSemaphore for a particular key have been destroyed, either by having their destructors called, or because one or more processes crash, Windows removes the underlying system semaphore.
Unix：
Apple platforms:
Sandboxed applications (including apps shipped through the Apple App Store) require the key to be in the form
<application group identifier>/<custom identifier>
，如文档化
here
and
here
, and the key length is limited to 30 characters.
另请参阅 QSharedMemory and QSemaphore .
This enum is used by the constructor and setKey (). Its purpose is to enable handling the problem in Unix implementations of semaphores that survive a crash. In Unix, when a semaphore survives a crash, we need a way to force it to reset its resource count, when the system reuses the semaphore. In Windows, where semaphores can't survive a crash, this enum has no effect.
| 常量 | 值 | 描述 |
|---|---|---|
QSystemSemaphore::Open
|
0
|
If the semaphore already exists, its initial resource count is not reset. If the semaphore does not already exist, it is created and its initial resource count set. |
QSystemSemaphore::Create
|
1
|
QSystemSemaphore takes ownership of the semaphore and sets its resource count to the requested value, regardless of whether the semaphore already exists by having survived a crash. This value should be passed to the constructor, when the first semaphore for a particular key is constructed and you know that if the semaphore already exists it could only be because of a crash. In Windows, where a semaphore can't survive a crash, Create and Open have the same behavior. |
| 常量 | 值 | 描述 |
|---|---|---|
QSystemSemaphore::NoError
|
0
|
没有出现错误。 |
QSystemSemaphore::PermissionDenied
|
1
|
操作失败，因为调用者没有所需权限。 |
QSystemSemaphore::KeyError
|
2
|
操作失败，因为键无效。 |
QSystemSemaphore::AlreadyExists
|
3
|
The operation failed because a system semaphore with the specified key already existed. |
QSystemSemaphore::NotFound
|
4
|
The operation failed because a system semaphore with the specified key could not be found. |
QSystemSemaphore::OutOfResources
|
5
|
The operation failed because there was not enough memory available to fill the request. |
QSystemSemaphore::UnknownError
|
6
|
发生其它事情且很糟糕。 |
Requests a system semaphore for the specified key 。参数 initialValue and mode are used according to the following rules, which are system dependent.
在 Unix，若 mode is 打开 and the system already has a semaphore identified by key , that semaphore is used, and the semaphore's resource count is not changed, i.e., initialValue is ignored. But if the system does not already have a semaphore identified by key , it creates a new semaphore for that key and sets its resource count to initialValue .
在 Unix，若 mode is 创建 and the system already has a semaphore identified by key , that semaphore is used, and its resource count is set to initialValue . If the system does not already have a semaphore identified by key , it creates a new semaphore for that key and sets its resource count to initialValue .
In Windows, mode is ignored, and the system always tries to create a semaphore for the specified key . If the system does not already have a semaphore identified as key , it creates the semaphore and sets its resource count to initialValue . But if the system already has a semaphore identified as key it uses that semaphore and ignores initialValue .
mode parameter is only used in Unix systems to handle the case where a semaphore survives a process crash. In that case, the next process to allocate a semaphore with the same key will get the semaphore that survived the crash, and unless mode is 创建 , the resource count will not be reset to initialValue but will retain the initial value it had been given by the crashed process.
析构函数销毁 QSystemSemaphore object, but the underlying system semaphore is not removed from the system unless this instance of QSystemSemaphore is the last one existing for that system semaphore.
Two important side effects of the destructor depend on the system. In Windows, if acquire () has been called for this semaphore but not release (), release () will not be called by the destructor, nor will the resource be released when the process exits normally. This would be a program bug which could be the cause of a deadlock in another process trying to acquire the same resource. In Unix, acquired resources that are not released before the destructor is called are automatically released when the process exits.
Acquires one of the resources guarded by this semaphore, if there is one available, and returns
true
. If all the resources guarded by this semaphore have already been acquired, the call blocks until one of them is released by another process or thread having a semaphore with the same key.
若返回 false，有出现系统错误。调用 error () to get a value of QSystemSemaphore::SystemSemaphoreError that indicates which error occurred.
另请参阅 release ().
返回指示是否发生错误的值，且若如此，指示错误是什么。
另请参阅 errorString ().
返回最后发生错误的文本描述。若 error () 返回 错误值 ，调用此函数以获取描述错误的文本字符串。
另请参阅 error ().
Returns the key assigned to this system semaphore. The key is the name by which the semaphore can be accessed from other processes.
另请参阅 setKey ().
发行
n
资源守卫通过信号量。返回
true
除非存在系统错误。
Example: Create a system semaphore having five resources; acquire them all and then release them all.
QSystemSemaphore sem("market", 5, QSystemSemaphore::Create); for (int i = 0; i < 5; ++i) // acquire all 5 resources sem.acquire(); sem.release(5); // release the 5 resources
This function can also "create" resources. For example, immediately following the sequence of statements above, suppose we add the statement:
sem.release(10); // "create" 10 new resources
Ten new resources are now guarded by the semaphore, in addition to the five that already existed. You would not normally use this function to create more resources.
另请参阅 acquire ().
This function works the same as the constructor. It reconstructs this QSystemSemaphore 对象。若新的 key is different from the old key, calling this function is like calling the destructor of the semaphore with the old key, then calling the constructor to create a new semaphore with the new key 。 initialValue and mode parameters are as defined for the constructor.
另请参阅 QSystemSemaphore () 和 key ().
