QLatch Class Reference

#include <qlatch_p.h>

Collaboration diagram for QLatch:

Public Member Functions
constexpr	QLatch (int expected) noexcept
	Initializes the QLatch to indicate that countDown() will be called expected times.
int	pending () const noexcept
void	countDown (int n=1) noexcept
bool	tryWait () const noexcept
void	wait () noexcept
	Waits for the internal counter in this latch to drop to zero.
void	arriveAndWait (int n=1) noexcept
void	count_down (int n=1) noexcept
	Decrements the internal counter by n.
bool	try_wait () const noexcept
	Returns true if the internal counter in this latch has dropped to zero, false otherwise.
void	arrive_and_wait (int n=1) noexcept
	This function decrements the internal counter by n.

Static Public Member Functions
static constexpr int	max () noexcept
	Returns the maximum number that can be passed to the constructor.

Detailed Description

Implements the same API as std::latch (C++20), allowing a single synchronization between threads.

For this use-case, one or more threads perform some work, which needs to finish before the caller thread can proceed. For this, each worker thread calls countDown() once they have finished their work, while the caller thread suspends execution by calling wait().

The operation is best seen in:

QLatch latch(segments);
int y = 0;
for (int i = 0; i < segments; ++i) {
    int yn = (data->height - y) / (segments - i);
    threadPool->start([&, y, yn]() {
        convertSegment(y, y + yn);
        latch.countDown();
    });
    y += yn;
}
latch.wait();

Or, for a single thread:

QLatch latch(1);
QMetaObject::invokeMethod(object, [&]() {
    doSomething();
    latch.countDown();
}, Qt::QueuedConnection);
latch.wait();

In fact, the above is exactly what Qt::BlockingQueued connection does.

For this use-case, multiple threads must reach a particular state before any of them may proceed. In this case, all of them call arriveAndWait(), causing all but the last one of them to suspend execution until that last one also arrives.

QLatch latch(n);
for (int i = 0; i < n; ++i) {
    threadPool->start([] {
        latch.arriveAndWait();
        doStressfulWork();
    });
}

\list

• Uses {int} in the API instead of {ptrdiff_t} (note that the max() is the same as libstdc++'s on Linux).
• count_down() is not {const} (libstdc++ implementation is). \endlist

\omit

countDown() must call wakeUp() if the latch counter reaches zero and there are threads waiting to be woken up. Or, conversely, countDown() needs to do nothing after decrementing if the latch counter is still non-zero or there are no waiters. Therefore, we choose the bits so that a non-zero {counter} member implies no action required.

\endomit

Definition at line 28 of file qlatch_p.h.

Constructor & Destructor Documentation

QLatch()

QLatch::QLatch ( int expected )

inlineexplicitconstexprnoexcept

Initializes the QLatch to indicate that countDown() will be called expected times.

You probably want to pass a value greater than zero.

Definition at line 31 of file qlatch_p.h.

Member Function Documentation

arrive_and_wait()

void QLatch::arrive_and_wait ( int n = 1 )

inlinenoexcept

This function decrements the internal counter by n.

If the counter remains non-zero after this operation, it suspends the current thread until it does become zero. Otherwise it wakes all other current waiters.

This function is useful to synchronize multiple threads so they may start some execution at (nearly) exactly the same time.

This function is exactly equivalent to:

countDown(n);
wait();

This function implements acquire-and-release memory ordering.

See also

countDown(), wait()

Definition at line 73 of file qlatch_p.h.

arriveAndWait()

void QLatch::arriveAndWait ( int n = 1 )

inlinenoexcept

Definition at line 63 of file qlatch_p.h.

count_down()

void QLatch::count_down ( int n = 1 )

inlinenoexcept

Decrements the internal counter by n.

If the internal counter drops to zero after this operation, any threads currently waiting will be woken up. If n is greater than the value of the internal counter or is negative, the behavior is undefined.

This function does not block and may be used to notify waiters that this thread has reached a particular point and they may proceed. To synchronize all threads so they all resume work at the same time, use arriveAndWait().

This function implements release memory ordering.

See also

arriveAndWait(), wait()

Definition at line 71 of file qlatch_p.h.

countDown()

void QLatch::countDown ( int n = 1 )

inlinenoexcept

Definition at line 40 of file qlatch_p.h.

max()

constexpr int QLatch::max ( )

inlinestaticconstexprnoexcept

Returns the maximum number that can be passed to the constructor.

Definition at line 70 of file qlatch_p.h.

pending()

int QLatch::pending ( ) const

inlinenoexcept

Returns the counter.

Don't use; for the unit test only.

Definition at line 35 of file qlatch_p.h.

try_wait()

bool QLatch::try_wait ( ) const

inlinenoexcept

Returns true if the internal counter in this latch has dropped to zero, false otherwise.

This function does not block.

This function implements acquire memory ordering.

See also

wait(), countDown()

Definition at line 72 of file qlatch_p.h.

tryWait()

bool QLatch::tryWait ( ) const

inlinenoexcept

Definition at line 47 of file qlatch_p.h.

wait()

void QLatch::wait ( )

inlinenoexcept

Waits for the internal counter in this latch to drop to zero.

This function implements acquire memory ordering.

See also

tryWait(), arriveAndWait(), countDown()

Definition at line 55 of file qlatch_p.h.

---

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

• qtbase/src/corelib/thread/qlatch_p.h (a795b442638f35faab15c1b6d06d268948865f56)
• qtbase/src/corelib/thread/qlatch.cpp (a795b442638f35faab15c1b6d06d268948865f56)