- class QSystemSemaphore#
The
QSystemSemaphore
class provides a general counting system semaphore. More…Synopsis#
Methods#
def
__init__()
def
acquire()
def
error()
def
errorString()
def
key()
def
nativeIpcKey()
def
release()
def
setKey()
def
setNativeKey()
Static functions#
Note
This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE
Detailed Description#
Warning
This section contains snippets that were automatically translated from C++ to Python and may contain errors.
A system semaphore is a generalization of
QSemaphore
. Typically, a semaphore is used to protect a certain number of identical resources.Like its lighter counterpart, a
QSystemSemaphore
can be accessed from multiplethreads
. UnlikeQSemaphore
, aQSystemSemaphore
can also be accessed from multipleprocesses
. This meansQSystemSemaphore
is a much heavier class, so if your application doesn’t need to access your semaphores across multiple processes, you will probably want to useQSemaphore
.Semaphores support two fundamental operations,
acquire()
andrelease()
: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.System semaphores are identified by a key, represented by
QNativeIpcKey
. A key can be created in a cross-platform manner by using platformSafeKey(). A system semaphore is created by theQSystemSemaphore
constructor when passed an access mode parameter of AccessMode::Create. Once it is created, other processes may attach to the same semaphore using the same key and an access mode parameter of AccessMode::Open.Example: Create a system semaphore
sem = QSystemSemaphore(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
For details on the key types, platform-specific limitations, and interoperability with older or non-Qt applications, see the Native IPC Keys documentation. That includes important information for sandboxed applications on Apple platforms, including all apps obtained via the Apple App Store.
- class AccessMode#
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.Constant
Description
QSystemSemaphore.Open
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
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.
- class SystemSemaphoreError#
Constant
Description
QSystemSemaphore.NoError
No error occurred.
QSystemSemaphore.PermissionDenied
The operation failed because the caller didn’t have the required permissions.
QSystemSemaphore.KeyError
The operation failed because of an invalid key.
QSystemSemaphore.AlreadyExists
The operation failed because a system semaphore with the specified key already existed.
QSystemSemaphore.NotFound
The operation failed because a system semaphore with the specified key could not be found.
QSystemSemaphore.OutOfResources
The operation failed because there was not enough memory available to fill the request.
QSystemSemaphore.UnknownError
Something else happened and it was bad.
- __init__(key[, initialValue=0[, arg__3=QSystemSemaphore.AccessMode.Open]])#
- Parameters:
key –
QNativeIpcKey
initialValue – int
arg__3 –
AccessMode
Requests a system semaphore for the specified
key
. The parametersinitialValue
andmode
are used according to the following rules, which are system dependent.In Unix, if the
mode
isOpen
and the system already has a semaphore identified bykey
, 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 bykey
, it creates a new semaphore for that key and sets its resource count toinitialValue
.In Unix, if the
mode
isCreate
and the system already has a semaphore identified bykey
, that semaphore is used, and its resource count is set toinitialValue
. If the system does not already have a semaphore identified bykey
, it creates a new semaphore for that key and sets its resource count toinitialValue
.In Windows,
mode
is ignored, and the system always tries to create a semaphore for the specifiedkey
. If the system does not already have a semaphore identified askey
, it creates the semaphore and sets its resource count toinitialValue
. But if the system already has a semaphore identified askey
it uses that semaphore and ignoresinitialValue
.The
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 samekey
will get the semaphore that survived the crash, and unlessmode
isCreate
, the resource count will not be reset toinitialValue
but will retain the initial value it had been given by the crashed process.- __init__(key[, initialValue=0[, mode=QSystemSemaphore.AccessMode.Open]])
- Parameters:
key – str
initialValue – int
mode –
AccessMode
Requests a system semaphore identified by the legacy key
key
.- acquire()#
- Return type:
bool
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.If false is returned, a system error has occurred. Call
error()
to get a value ofSystemSemaphoreError
that indicates which error occurred.See also
- error()#
- Return type:
Returns a value indicating whether an error occurred, and, if so, which error it was.
See also
- errorString()#
- Return type:
str
Returns a text description of the last error that occurred. If
error()
returns anerror value
, call this function to get a text string that describes the error.See also
- key()#
- Return type:
str
Returns the legacy key assigned to this system semaphore. The key is the name by which the semaphore can be accessed from other processes.
See also
- static legacyNativeKey(key[, type=QNativeIpcKey.legacyDefaultTypeForOs()])#
- Parameters:
key – str
type –
Type
- Return type:
- nativeIpcKey()#
- Return type:
Returns the key assigned to this system semaphore. The key is the name by which the semaphore can be accessed from other processes.
You can use the native key to access system semaphores that have not been created by Qt, or to grant access to non-Qt applications. See Native IPC Keys for more information.
See also
- static platformSafeKey(key[, type=QNativeIpcKey.DefaultTypeForOs])#
- Parameters:
key – str
type –
Type
- Return type:
- release([n=1])#
- Parameters:
n – int
- Return type:
bool
Warning
This section contains snippets that were automatically translated from C++ to Python and may contain errors.
Releases
n
resources guarded by the semaphore. Returnstrue
unless there is a system error.Example: Create a system semaphore having five resources; acquire them all and then release them all.
sem = QSystemSemaphore(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
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 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.
See also
- setKey(key[, initialValue=0[, mode=QSystemSemaphore.AccessMode.Open]])#
- Parameters:
key – str
initialValue – int
mode –
AccessMode
This function works the same as the constructor. It reconstructs this
QSystemSemaphore
object. If the newkey
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 newkey
. TheinitialValue
andmode
parameters are as defined for the constructor.See also
QSystemSemaphore()
key()
- setNativeKey(key[, initialValue=0[, arg__3=QSystemSemaphore.AccessMode.Open]])#
- Parameters:
key –
QNativeIpcKey
initialValue – int
arg__3 –
AccessMode
This function works the same as the constructor. It reconstructs this
QSystemSemaphore
object. If the newkey
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 newkey
. TheinitialValue
andmode
parameters are as defined for the constructor.This function is useful if the native key was shared from another process. See Native IPC Keys for more information.
See also
QSystemSemaphore()
nativeIpcKey()
- setNativeKey(key[, initialValue=0[, mode=QSystemSemaphore.AccessMode.Open[, type=QNativeIpcKey.legacyDefaultTypeForOs()]]])
- Parameters:
key – str
initialValue – int
mode –
AccessMode
type –
Type