QSemaphore¶
The
QSemaphore
class provides a general counting semaphore. More…
Synopsis¶
Functions¶
def
acquire
([n=1])def
available
()def
release
([n=1])def
tryAcquire
([n=1])def
tryAcquire
(n, timeout)
Detailed Description¶
A semaphore is a generalization of a mutex. While a mutex can only be locked once, it’s possible to acquire a semaphore multiple times. Semaphores are typically used to protect a certain number of identical resources.
Semaphores support two fundamental operations,
acquire()
andrelease()
:
acquire(n) tries to acquire n resources. If there aren’t that many resources available, the call will block until this is the case.
release(n) releases n resources.
There’s also a
tryAcquire()
function that returns immediately if it cannot acquire the resources, and anavailable()
function that returns the number of available resources at any time.Example:
sem = QSemaphore(5) # sem.available() == 5 sem.acquire(3) # sem.available() == 2 sem.acquire(2) # sem.available() == 0 sem.release(5) # sem.available() == 5 sem.release(5) # sem.available() == 10 sem.tryAcquire(1) # sem.available() == 9, returns true sem.tryAcquire(250) # sem.available() == 9, returns falseA typical application of semaphores is for controlling access to a circular buffer shared by a producer thread and a consumer thread. The Semaphores Example shows how to use
QSemaphore
to solve that problem.A non-computing example of a semaphore would be dining at a restaurant. A semaphore is initialized with the number of chairs in the restaurant. As people arrive, they want a seat. As seats are filled,
available()
is decremented. As people leave, theavailable()
is incremented, allowing more people to enter. If a party of 10 people want to be seated, but there are only 9 seats, those 10 people will wait, but a party of 4 people would be seated (taking the available seats to 5, making the party of 10 people wait longer).
- class PySide2.QtCore.QSemaphore([n=0])¶
- param n:
int
Creates a new semaphore and initializes the number of resources it guards to
n
(by default, 0).See also
- PySide2.QtCore.QSemaphore.acquire([n=1])¶
- Parameters:
n – int
Tries to acquire
n
resources guarded by the semaphore. Ifn
>available()
, this call will block until enough resources are available.See also
- PySide2.QtCore.QSemaphore.available()¶
- Return type:
int
Returns the number of resources currently available to the semaphore. This number can never be negative.
- PySide2.QtCore.QSemaphore.release([n=1])¶
- Parameters:
n – int
Releases
n
resources guarded by the semaphore.This function can be used to “create” resources as well. For example:
sem = QSemaphore(5) # a semaphore that guards 5 resources sem.acquire(5) # acquire all 5 resources sem.release(5) # release the 5 resources sem.release(10) # "create" 10 new resources
QSemaphoreReleaser
is a RAII wrapper around this function.See also
- PySide2.QtCore.QSemaphore.tryAcquire([n=1])¶
- Parameters:
n – int
- Return type:
bool
Tries to acquire
n
resources guarded by the semaphore and returnstrue
on success. Ifavailable()
<n
, this call immediately returnsfalse
without acquiring any resources.Example:
sem = QSemaphore(5) # sem.available() == 5 sem.tryAcquire(250) # sem.available() == 5, returns false sem.tryAcquire(3) # sem.available() == 2, returns true
See also
- PySide2.QtCore.QSemaphore.tryAcquire(n, timeout)
- Parameters:
n – int
timeout – int
- Return type:
bool
Tries to acquire
n
resources guarded by the semaphore and returnstrue
on success. Ifavailable()
<n
, this call will wait for at mosttimeout
milliseconds for resources to become available.Note: Passing a negative number as the
timeout
is equivalent to callingacquire()
, i.e. this function will wait forever for resources to become available iftimeout
is negative.Example:
sem = QSemaphore(5) # sem.available() == 5 sem.tryAcquire(250, 1000) # sem.available() == 5, waits 1000 milliseconds and returns false sem.tryAcquire(3, 30000) # sem.available() == 2, returns true without waiting
See also
© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.