QSemaphoreReleaser Class Reference

The QSemaphoreReleaser class provides exception-safe deferral of a QSemaphore::release() call. More...

#include <qsemaphore.h>

Collaboration diagram for QSemaphoreReleaser:

Public Member Functions
Q_NODISCARD_CTOR	QSemaphoreReleaser ()=default
	Default constructor.
Q_NODISCARD_CTOR	QSemaphoreReleaser (QSemaphore &sem, int n=1) noexcept
	Constructor.
Q_NODISCARD_CTOR	QSemaphoreReleaser (QSemaphore *sem, int n=1) noexcept
	Constructor.
Q_NODISCARD_CTOR	QSemaphoreReleaser (QSemaphoreReleaser &&other) noexcept
	Move constructor.
	~QSemaphoreReleaser ()
	Unless canceled, calls QSemaphore::release() with the arguments provided to the constructor, or by the last move assignment.
void	swap (QSemaphoreReleaser &other) noexcept
	Exchanges the responsibilities of {*this} and other.
QSemaphore *	semaphore () const noexcept
	Returns a pointer to the QSemaphore object provided to the constructor, or by the last move assignment, if any.
QSemaphore *	cancel () noexcept
	Cancels this QSemaphoreReleaser such that the destructor will no longer call {semaphore()->release()}.

Detailed Description

The QSemaphoreReleaser class provides exception-safe deferral of a QSemaphore::release() call.

Since

5.10

\inmodule QtCore

\reentrant

QSemaphoreReleaser can be used wherever you would otherwise use QSemaphore::release(). Constructing a QSemaphoreReleaser defers the release() call on the semaphore until the QSemaphoreReleaser is destroyed (see \l{http://en.cppreference.com/w/cpp/language/raii}{RAII pattern}).

You can use this to reliably release a semaphore to avoid dead-lock in the face of exceptions or early returns:

// ... do something that may throw or return early
sem.release();

If an early return is taken or an exception is thrown before the {sem.release()} call is reached, the semaphore is not released, possibly preventing the thread waiting in the corresponding {sem.acquire()} call from ever continuing execution.

When using RAII instead:

const QSemaphoreReleaser releaser(sem);
// ... do something that may throw or early return
// implicitly calls sem.release() here and at every other return in between

this can no longer happen, because the compiler will make sure that the QSemaphoreReleaser destructor is always called, and therefore the semaphore is always released.

QSemaphoreReleaser is move-enabled and can therefore be returned from functions to transfer responsibility for releasing a semaphore out of a function or a scope:

{ // some scope
    QSemaphoreReleaser releaser; // does nothing
    // ...
    if (someCondition) {
        releaser = QSemaphoreReleaser(sem);
        // ...
    }
    // ...
} // conditionally calls sem.release(), depending on someCondition

A QSemaphoreReleaser can be canceled by a call to cancel(). A canceled semaphore releaser will no longer call QSemaphore::release() in its destructor.

See also

QMutexLocker

Definition at line 66 of file qsemaphore.h.

Constructor & Destructor Documentation

QSemaphoreReleaser() [1/4]

Q_NODISCARD_CTOR QSemaphoreReleaser::QSemaphoreReleaser ( )

default

Default constructor.

Creates a QSemaphoreReleaser that does nothing.

QSemaphoreReleaser() [2/4]

Q_NODISCARD_CTOR QSemaphoreReleaser::QSemaphoreReleaser ( QSemaphore & sem, int n = 1 )

inlineexplicitnoexcept

Constructor.

Stores the arguments and calls {sem}.release({n}) in the destructor.

Definition at line 72 of file qsemaphore.h.

QSemaphoreReleaser() [3/4]

Q_NODISCARD_CTOR QSemaphoreReleaser::QSemaphoreReleaser ( QSemaphore * sem, int n = 1 )

inlineexplicitnoexcept

Constructor.

Stores the arguments and calls {sem}->release({n}) in the destructor.

Definition at line 75 of file qsemaphore.h.

QSemaphoreReleaser() [4/4]

Q_NODISCARD_CTOR QSemaphoreReleaser::QSemaphoreReleaser ( QSemaphoreReleaser && other )

inlinenoexcept

Move constructor.

Takes over responsibility to call QSemaphore::release() from other, which in turn is canceled.

See also

cancel()

Definition at line 78 of file qsemaphore.h.

~QSemaphoreReleaser()

QSemaphoreReleaser::~QSemaphoreReleaser ( )

inline

Unless canceled, calls QSemaphore::release() with the arguments provided to the constructor, or by the last move assignment.

Definition at line 82 of file qsemaphore.h.

Member Function Documentation

cancel()

QSemaphore * QSemaphoreReleaser::cancel ( )

inlinenoexcept

Cancels this QSemaphoreReleaser such that the destructor will no longer call {semaphore()->release()}.

Returns the value of semaphore() before this call. After this call, semaphore() will return \nullptr.

To enable again, assign a new QSemaphoreReleaser:

releaser.cancel(); // avoid releasing old semaphore()
releaser = QSemaphoreReleaser(sem, 42);
// now will call sem.release(42) when 'releaser' is destroyed

Definition at line 97 of file qsemaphore.h.

semaphore()

QSemaphore * QSemaphoreReleaser::semaphore ( ) const

inlinenoexcept

Returns a pointer to the QSemaphore object provided to the constructor, or by the last move assignment, if any.

Otherwise, returns \nullptr.

Definition at line 94 of file qsemaphore.h.

swap()

void QSemaphoreReleaser::swap ( QSemaphoreReleaser & other )

inlinenoexcept

Exchanges the responsibilities of {*this} and other.

Unlike move assignment, neither of the two objects ever releases its semaphore, if any, as a consequence of swapping.

Therefore this function is very fast and never fails.

Definition at line 88 of file qsemaphore.h.

---

The documentation for this class was generated from the following files:

• qtbase/src/corelib/thread/qsemaphore.h (7a33a08376a30bb7b788cafc2343378131fd1e8d)
• qtbase/src/corelib/thread/qsemaphore.cpp (763ab0e6236de80a0b589fc574c75a414d86d374)