Aleph::Testing::Deterministic_Start_Gate Class Reference

Single-use deterministic start gate for concurrent tests. More...

#include <concurrency_test_utils.H>

Collaboration diagram for Aleph::Testing::Deterministic_Start_Gate:

Public Member Functions
	Deterministic_Start_Gate (const size_t expected)
	Construct a gate for the given number of workers.
bool	arrive_and_wait ()
	Mark the caller ready and block until release() or cancel().
void	wait_until_ready ()
	Wait until all expected workers are ready, or the gate is cancelled.
void	release ()
	Release all waiting workers.
void	cancel () noexcept
	Abort the gate, waking every worker currently blocked in arrive_and_wait() or wait_until_ready().
size_t	arrived () const
	Return the number of arrived workers.

Private Attributes
const size_t	expected_ = 0
size_t	arrived_ = 0
bool	released_ = false
bool	cancelled_ = false
std::mutex	mutex_
std::condition_variable	cv_

Detailed Description

Single-use deterministic start gate for concurrent tests.

Worker threads call arrive_and_wait(). The test thread calls wait_until_ready() and release(). This ensures all workers are parked before the measured/stressed section starts.

Thread-safety

arrive_and_wait(), wait_until_ready(), release(), cancel(), and arrived() may all be called concurrently; each synchronizes internally on the gate's own mutex.

Definition at line 71 of file concurrency_test_utils.H.

Constructor & Destructor Documentation

Deterministic_Start_Gate()

Aleph::Testing::Deterministic_Start_Gate::Deterministic_Start_Gate ( const size_t  expected )

inlineexplicit

Construct a gate for the given number of workers.

Parameters

[in]

expected

Number of workers that must arrive before release.

Exceptions

std::invalid_argument

if expected == 0 (a gate with no participants would never distinguish "nobody has arrived yet" from "everybody has arrived", which is almost always a miscounted caller rather than an intentional no-op gate).

Definition at line 89 of file concurrency_test_utils.H.

References ah_invalid_argument_if.

Member Function Documentation

arrive_and_wait()

bool Aleph::Testing::Deterministic_Start_Gate::arrive_and_wait ( )

inline

Mark the caller ready and block until release() or cancel().

This function is intended for worker threads.

Returns

true if the gate was released normally, false if cancel() unblocked this call instead.

Definition at line 103 of file concurrency_test_utils.H.

References arrived_, Aleph::blossom_maximum_cardinality_matching(), cancelled_, cv_, mutex_, and released_.

arrived()

size_t Aleph::Testing::Deterministic_Start_Gate::arrived ( ) const

inline

Return the number of arrived workers.

Returns

Number of workers that already called arrive_and_wait().

Definition at line 157 of file concurrency_test_utils.H.

References arrived_, and mutex_.

Referenced by TEST().

cancel()

void Aleph::Testing::Deterministic_Start_Gate::cancel ( )

inlinenoexcept

Abort the gate, waking every worker currently blocked in arrive_and_wait() or wait_until_ready().

Woken participants observe arrive_and_wait() returning false instead of waiting forever. Intended for exception-safety cleanup: if launching one worker thread of a cohort fails partway through, the threads already started would otherwise stay parked indefinitely, since the full expected count will never arrive.

Note

Cancelling an already-released gate is a harmless no-op.

Definition at line 146 of file concurrency_test_utils.H.

References cancelled_, cv_, and mutex_.

Referenced by Aleph::Testing::detail::Joining_Thread_Guard::~Joining_Thread_Guard().

release()

void Aleph::Testing::Deterministic_Start_Gate::release ( )

inline

Release all waiting workers.

Calling release() before all workers arrive is valid; late workers will pass through immediately after incrementing the arrival count.

Definition at line 128 of file concurrency_test_utils.H.

References cv_, mutex_, and released_.

Referenced by TEST().

wait_until_ready()

void Aleph::Testing::Deterministic_Start_Gate::wait_until_ready ( )

inline

Wait until all expected workers are ready, or the gate is cancelled.

This function is intended for the controlling test thread.

Definition at line 117 of file concurrency_test_utils.H.

References arrived_, Aleph::blossom_maximum_cardinality_matching(), cancelled_, cv_, expected_, and mutex_.

Referenced by TEST().

Member Data Documentation

arrived_

size_t Aleph::Testing::Deterministic_Start_Gate::arrived_ = 0

private

Definition at line 74 of file concurrency_test_utils.H.

Referenced by arrive_and_wait(), arrived(), and wait_until_ready().

cancelled_

bool Aleph::Testing::Deterministic_Start_Gate::cancelled_ = false

private

Definition at line 76 of file concurrency_test_utils.H.

Referenced by arrive_and_wait(), cancel(), and wait_until_ready().

cv_

std::condition_variable Aleph::Testing::Deterministic_Start_Gate::cv_

private

Definition at line 78 of file concurrency_test_utils.H.

Referenced by arrive_and_wait(), cancel(), release(), and wait_until_ready().

expected_

const size_t Aleph::Testing::Deterministic_Start_Gate::expected_ = 0

private

Definition at line 73 of file concurrency_test_utils.H.

Referenced by wait_until_ready().

mutex_

std::mutex Aleph::Testing::Deterministic_Start_Gate::mutex_

mutableprivate

Definition at line 77 of file concurrency_test_utils.H.

Referenced by arrive_and_wait(), arrived(), cancel(), release(), and wait_until_ready().

released_

bool Aleph::Testing::Deterministic_Start_Gate::released_ = false

private

Definition at line 75 of file concurrency_test_utils.H.

Referenced by arrive_and_wait(), and release().

---

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

• Tests/concurrency_test_utils.H