hpx/synchronization/latch.hpp#

See Public API for a list of names and headers that are part of the public HPX API.

namespace hpx
class latch#
#include <latch.hpp>

Latches are a thread coordination mechanism that allow one or more threads to block until an operation is completed. An individual latch is a singleuse object; once the operation has been completed, the latch cannot be reused.

Subclassed by hpx::lcos::local::latch

Public Functions

HPX_NON_COPYABLE(latch)#
inline explicit latch(std::ptrdiff_t count)#

Initialize the latch

Requires: count >= 0. Synchronization: None Postconditions: counter_ == count.

~latch() = default#

Requires: No threads are blocked at the synchronization point.

Note

May be called even if some threads have not yet returned from wait() or count_down_and_wait(), provided that counter_ is 0.

Note

The destructor might not return until all threads have exited wait() or count_down_and_wait().

Note

It is the caller’s responsibility to ensure that no other thread enters wait() after one thread has called the destructor. This may require additional coordination.

inline void count_down(std::ptrdiff_t update)#

Decrements counter_ by n. Does not block.

Requires: counter_ >= n and n >= 0.

Synchronization: Synchronizes with all calls that block on this latch and with all try_wait calls on this latch that return true .

Throws

Nothing.

inline bool try_wait() const noexcept#

Returns: With very low probability false. Otherwise counter == 0.

inline void wait() const#

If counter_ is 0, returns immediately. Otherwise, blocks the calling thread at the synchronization point until counter_ reaches 0.

Throws

Nothing.

inline void arrive_and_wait(std::ptrdiff_t update = 1)#

Effects: Equivalent to: count_down(update); wait();

Public Static Functions

static inline constexpr std::ptrdiff_t() max () noexcept

Returns: The maximum value of counter that the implementation supports.

Protected Types

using mutex_type = hpx::spinlock#

Protected Attributes

mutable util::cache_line_data<mutex_type> mtx_#
mutable util::cache_line_data<hpx::lcos::local::detail::condition_variable> cond_#
std::atomic<std::ptrdiff_t> counter_#
bool notified_#
namespace lcos
namespace local
class latch : public hpx::latch#
#include <latch.hpp>

A latch maintains an internal counter_ that is initialized when the latch is created. Threads may block at a synchronization point waiting for counter_ to be decremented to 0. When counter_ reaches 0, all such blocked threads are released.

Calls to countdown_and_wait() , count_down() , wait() , is_ready(), count_up() , and reset() behave as atomic operations.

Note

A hpx::latch is not an LCO in the sense that it has no global id and it can’t be triggered using the action (parcel) mechanism. Use hpx::distributed::latch instead if this is required. It is just a low level synchronization primitive allowing to synchronize a given number of threads.

Public Functions

HPX_NON_COPYABLE(latch)#
inline explicit latch(std::ptrdiff_t count)#

Initialize the latch

Requires: count >= 0. Synchronization: None Postconditions: counter_ == count.

~latch() = default#

Requires: No threads are blocked at the synchronization point.

Note

May be called even if some threads have not yet returned from wait() or count_down_and_wait(), provided that counter_ is 0.

Note

The destructor might not return until all threads have exited wait() or count_down_and_wait().

Note

It is the caller’s responsibility to ensure that no other thread enters wait() after one thread has called the destructor. This may require additional coordination.

inline void count_down_and_wait()#

Decrements counter_ by 1 . Blocks at the synchronization point until counter_ reaches 0.

Requires: counter_ > 0.

Synchronization: Synchronizes with all calls that block on this latch and with all is_ready calls on this latch that return true.

Throws

Nothing.

inline bool is_ready() const noexcept#

Returns: counter_ == 0. Does not block.

Throws

Nothing.

inline void abort_all()#
inline void count_up(std::ptrdiff_t n)#

Increments counter_ by n. Does not block.

Requires: n >= 0.

Throws

Nothing.

inline void reset(std::ptrdiff_t n)#

Reset counter_ to n. Does not block.

Requires: n >= 0.

Throws

Nothing.

inline bool reset_if_needed_and_count_up(std::ptrdiff_t n, std::ptrdiff_t count)#

Effects: Equivalent to: if (is_ready()) reset(count); count_up(n); Returns: true if the latch was reset