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