Definition

Enables multiple tasks to cooperatively work on an algorithm in parallel through multiple phases.

Header: #include <xtd/threading/barrier>

Namespace: xtd::threading

Library: xtd.core

Examples: #include <xtd/threading/barrier>
#include <xtd/threading/interlocked>
#include <xtd/threading/thread_pool>
#include <xtd/console>
#include <xtd/startup>
using namespace xtd;
using namespace xtd::threading;
namespace barrier_example {
class program {
public:
static void main() {
auto count = 0;

// Create a barrier with three participants
// Provide a post-phase action that will print out certain information
// And the third time through, it will throw an exception
auto barrier = threading::barrier {3, action<threading::barrier&> {[&](threading::barrier& b) {
console::write_line("Post-Phase action: count={0}, phase={1}", count, b.current_phase_number());
if (b.current_phase_number() == 2) throw system_exception("D'oh!", csf_);
}}};

// Nope -- changed my mind. Let's make it five participants.
barrier.add_participants(2);

// Nope -- let's settle on four participants.
barrier.remove_participant();

auto action = [&] {
interlocked::increment(count);
barrier.signal_and_wait(); // during the post-phase action, count should be 4 and phase should be 0
interlocked::increment(count);
barrier.signal_and_wait(); // during the post-phase action, count should be 8 and phase should be 1

// The third time, SignalAndWait() will throw an exception and all participants will see it
interlocked::increment(count);
try {
barrier.signal_and_wait();
} catch (const barrier_post_phase_exception& bppe) {
console::write_line("Caught barrier_post_phase_exception: {0}", bppe.message());
}

// The fourth time should be hunky-dory
interlocked::increment(count);
barrier.signal_and_wait(); // during the post-phase action, count should be 16 and phase should be 3
};
// Now launch 4 parallel actions to serve as 4 participants
for (auto index = 0; index < 4; ++index)
thread_pool::queue_user_work_item(action);

// It's good form to join all thread and close() a barrier when you're done with it.
thread::join_all();
barrier.close();
}
};
}
startup_(barrier_example::program::main);
// This example produces output similar to the following:
//
// Post-Phase action: count=4, phase=0
// Post-Phase action: count=8, phase=1
// Post-Phase action: count=12, phase=2
// Post-Phase action: count=16, phase=3

Remarks: A group of tasks cooperate by moving through a series of phases, where each in the group signals it has arrived at the xtd::threading::barrier in a given phase and implicitly waits for all others to arrive. The same xtd::threading::barrier can be used for multiple phases.

Aliases
using	post_phase_action = action< barrier & >
	Represents the xtd::threading::barrier::post_phase_action delegate. More...

Constructors
	barrier (int32 participant_count)
	Initializes a new instance of the xtd::threading::barrier class. More...

	barrier (int32 participant_count, barrier::post_phase_action post_phase_action)
	Initializes a new instance of the xtd::threading::barrier class. More...

Properties
int32	current_phase_number () const
	Gets the number of the barrier's current phase. More...

int32	participant_count () const
	Gets the total number of participants in the barrier. More...

int32	participants_remaining () const
	Gets the number of participants in the barrier that haven't yet signaled in the current phase. More...

Methods
int32	add_participant ()
	Notifies the xtd::threading::barrier that there will be an additional participant. More...

int32	add_participants (int32 participant_count)
	Notifies the xtd::threading::barrier that there will be additional participants. More...

void	close ()
	Close the current instance of the xtd::threading::barrier class. More...

int32	remove_participant ()
	Notifies the Barrier that there will be one less participant. More...

int32	remove_participants (int32 participant_count)
	Notifies the Barrier that there will be fewer participants. More...

void	signal_and_wait ()
	Signals that a participant has reached the barrier and waits for all other participants to reach the barrier as well. More...

bool	signal_and_wait (int32 milliseconds_timeout)
	Signals that a participant has reached the barrier and waits for all other participants to reach the barrier as well, using a 32-bit signed integer to measure the timeout. More...

bool	signal_and_wait (const cancellation_token &cancellation_token)
	Signals that a participant has reached the barrier and waits for all other participants to reach the barrier, while observing a cancellation token. More...

bool	signal_and_wait (const time_span &timeout)
	Signals that a participant has reached the barrier and waits for all other participants to reach the barrier as well, using a xtd::time_span object to measure the time interval. More...

bool	signal_and_wait (int32 milliseconds_timeout, const cancellation_token &cancellation_token)
	Signals that a participant has reached the barrier and waits for all other participants to reach the barrier as well, using a 32-bit signed integer to measure the timeout, while observing a cancellation token. More...

bool	signal_and_wait (const time_span &timeout, const cancellation_token &cancellation_token)
	Signals that a participant has reached the barrier and waits for all other participants to reach the barrier as well, using a xtd::time_span object to measure the time interval, while observing a cancellation token. More...

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object. More...

bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object. More...

virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type. More...

virtual type_object	get_type () const noexcept
	Gets the type of the current instance. More...

template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Creates a shallow copy of the current object. More...

virtual xtd::ustring	to_string () const noexcept
	Returns a sxd::ustring that represents the current object. More...

Static Public Member Functions inherited from xtd::object
static bool	equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are considered equal. More...

static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance. More...

Member Typedef Documentation

◆ post_phase_action

using xtd::threading::barrier::post_phase_action = action<barrier&>

Represents the xtd::threading::barrier::post_phase_action delegate.

Constructor & Destructor Documentation

◆ barrier() [1/2]

xtd::threading::barrier::barrier ( int32 participant_count )

explicit

Initializes a new instance of the xtd::threading::barrier class.

Parameters

participant_count The number of participating threads.

Exceptions

xtd::argument_out_of_range_exception participant_count is less than 0 or greater than 32,767.

◆ barrier() [2/2]

xtd::threading::barrier::barrier	(	int32	participant_count,
		barrier::post_phase_action	post_phase_action
	)

Initializes a new instance of the xtd::threading::barrier class.

Parameters

participant_count	The number of participating threads.
post_phase_action	The xtd::action< barrier& > to be executed after each phase. Empty may be passed to indicate no action is taken.

Exceptions

xtd::argument_out_of_range_exception participant_count is less than 0 or greater than 32,767.

Remarks: The post_phase_action delegate will be executed after all participants have arrived at the barrier in one phase. The participants will not be released to the next phase until the post_phase_action delegate has completed execution.

Member Function Documentation

◆ add_participant()

int32 xtd::threading::barrier::add_participant ( )

Notifies the xtd::threading::barrier that there will be an additional participant.

Returns: The phase number of the barrier in which the new participants will first participate.

Exceptions

xtd::object_closed_exception	The current instance has already been disposed.
xtd::argument_out_of_range_exception	Adding a participant would cause the barrier's participant count to exceed 32,767.

Remarks: If the barrier is currently executing a post phase action, this call is blocked until the post phase action completes and the barrier has moved on to the next phase.

◆ add_participants()

int32 xtd::threading::barrier::add_participants ( int32 participant_count )

Notifies the xtd::threading::barrier that there will be additional participants.

Parameters

participant_count The number of additional participants to add to the barrier.

Returns: The phase number of the barrier in which the new participants will first participate.

Exceptions

xtd::object_closed_exception	The current instance has already been disposed.
xtd::argument_out_of_range_exception	participant_count is less than 0 -or- Adding participant_count participants would cause the barrier's participant count to exceed 32,767..

Remarks: If the barrier is currently executing a post phase action, this call is blocked until the post phase action completes and the barrier has moved on to the next phase.

◆ close()

void xtd::threading::barrier::close ( )

Close the current instance of the xtd::threading::barrier class.

◆ current_phase_number()

int32 xtd::threading::barrier::current_phase_number ( ) const

Gets the number of the barrier's current phase.

Returns: Returns the number of the barrier's current phase.

Exceptions

xtd::object_closed_exception The current instance has already been disposed.

◆ participant_count()

int32 xtd::threading::barrier::participant_count ( ) const

Gets the total number of participants in the barrier.

Returns: Returns the total number of participants in the barrier.

Exceptions

xtd::object_closed_exception The current instance has already been disposed.

◆ participants_remaining()

int32 xtd::threading::barrier::participants_remaining ( ) const

Gets the number of participants in the barrier that haven't yet signaled in the current phase.

Returns: Returns the number of participants in the barrier that haven't yet signaled in the current phase.

Exceptions

xtd::object_closed_exception The current instance has already been disposed.

Remarks: This could be 0 during a post-phase action delegate execution or if the participant_count is 0.

◆ remove_participant()

int32 xtd::threading::barrier::remove_participant ( )

Notifies the Barrier that there will be one less participant.

Returns: The phase number of the barrier in which the new participants will first participate.

Exceptions

xtd::object_closed_exception	The current instance has already been disposed.
xtd::argument_out_of_range_exception	The barrier already has 0 participants.

◆ remove_participants()

int32 xtd::threading::barrier::remove_participants ( int32 participant_count )

Notifies the Barrier that there will be fewer participants.

Parameters

participant_count The number of additional participants to remove from the barrier.

Returns: The phase number of the barrier in which the new participants will first participate.

Exceptions

xtd::object_closed_exception	The current instance has already been disposed.
xtd::argument_out_of_range_exception	participant_count is less than 0 -or- The total participant count is less than the specified participant_count

◆ signal_and_wait() [1/6]

void xtd::threading::barrier::signal_and_wait ( )

Signals that a participant has reached the barrier and waits for all other participants to reach the barrier as well.

Exceptions

xtd::object_closed_exception	The current instance has already been disposed.
xtd::threading::barrier_post_phase_exception	If an exception is thrown from the post phase action of a xtd::threading::barrier after all participating threads have called xtd::threading::barrier::signal_and_wait, the exception will be wrapped in a xtd::threading::barrier_post_phase_exception and be thrown on all participating threads.

◆ signal_and_wait() [2/6]

bool xtd::threading::barrier::signal_and_wait ( int32 milliseconds_timeout )

Signals that a participant has reached the barrier and waits for all other participants to reach the barrier as well, using a 32-bit signed integer to measure the timeout.

Parameters

milliseconds_timeout The number of milliseconds to wait, or xtd::threading::timeout::infinite(-1) to wait indefinitely.

Returns: true if all participants reached the barrier within the specified time; otherwise false.

Exceptions

xtd::argument_out_of_range_exception	milliseconds_timeout is a negative number other than -1, which represents an infinite time-out.
xtd::object_closed_exception	The current instance has already been disposed.
xtd::threading::barrier_post_phase_exception	If an exception is thrown from the post phase action of a xtd::threading::barrier after all participating threads have called xtd::threading::barrier::signal_and_wait, the exception will be wrapped in a xtd::threading::barrier_post_phase_exception and be thrown on all participating threads.

◆ signal_and_wait() [3/6]

bool xtd::threading::barrier::signal_and_wait ( const cancellation_token & cancellation_token )

Signals that a participant has reached the barrier and waits for all other participants to reach the barrier, while observing a cancellation token.

Parameters

cancellation_token The xtd::threading::cancellation_token to observe.

Returns: true if all participants reached the barrier within the specified time; otherwise false. xtd::operation_canceled_exception cancellation_token has been canceled.

Exceptions

xtd::object_closed_exception	The current instance has already been disposed.
xtd::threading::barrier_post_phase_exception	If an exception is thrown from the post phase action of a xtd::threading::barrier after all participating threads have called xtd::threading::barrier::signal_and_wait, the exception will be wrapped in a xtd::threading::barrier_post_phase_exception and be thrown on all participating threads.

◆ signal_and_wait() [4/6]

bool xtd::threading::barrier::signal_and_wait ( const time_span & timeout )

Signals that a participant has reached the barrier and waits for all other participants to reach the barrier as well, using a xtd::time_span object to measure the time interval.

Parameters

timout A xtd::time_span that represents the number of milliseconds to wait, or a xtd::time_span that represents -1 milliseconds to wait indefinitely.

Returns: true if all participants reached the barrier within the specified time; otherwise false.

Exceptions

xtd::argument_out_of_range_exception	milliseconds_timeout is a negative number other than -1, which represents an infinite time-out.
xtd::object_closed_exception	The current instance has already been disposed.
xtd::threading::barrier_post_phase_exception	If an exception is thrown from the post phase action of a xtd::threading::barrier after all participating threads have called xtd::threading::barrier::signal_and_wait, the exception will be wrapped in a xtd::threading::barrier_post_phase_exception and be thrown on all participating threads.

◆ signal_and_wait() [5/6]

bool xtd::threading::barrier::signal_and_wait	(	int32	milliseconds_timeout,
		const cancellation_token &	cancellation_token
	)

Signals that a participant has reached the barrier and waits for all other participants to reach the barrier as well, using a 32-bit signed integer to measure the timeout, while observing a cancellation token.

Parameters

milliseconds_timeout	The number of milliseconds to wait, or xtd::threading::timeout::infinite(-1) to wait indefinitely.
cancellation_token	The xtd::threading::cancellation_token to observe.

Returns: true if all participants reached the barrier within the specified time; otherwise false.

Exceptions

xtd::argument_out_of_range_exception	milliseconds_timeout is a negative number other than -1, which represents an infinite time-out. xtd::operation_canceled_exception cancellation_token has been canceled.
xtd::object_closed_exception	The current instance has already been disposed.
xtd::threading::barrier_post_phase_exception	If an exception is thrown from the post phase action of a xtd::threading::barrier after all participating threads have called xtd::threading::barrier::signal_and_wait, the exception will be wrapped in a xtd::threading::barrier_post_phase_exception and be thrown on all participating threads.

◆ signal_and_wait() [6/6]

bool xtd::threading::barrier::signal_and_wait	(	const time_span &	timeout,
		const cancellation_token &	cancellation_token
	)

Signals that a participant has reached the barrier and waits for all other participants to reach the barrier as well, using a xtd::time_span object to measure the time interval, while observing a cancellation token.

Parameters

timout	A xtd::time_span that represents the number of milliseconds to wait, or a xtd::time_span that represents -1 milliseconds to wait indefinitely.
cancellation_token	The xtd::threading::cancellation_token to observe.

Returns: true if all participants reached the barrier within the specified time; otherwise false.

Exceptions

xtd::argument_out_of_range_exception	milliseconds_timeout is a negative number other than -1, which represents an infinite time-out. xtd::operation_canceled_exception cancellation_token has been canceled.
xtd::object_closed_exception	The current instance has already been disposed.
xtd::threading::barrier_post_phase_exception	If an exception is thrown from the post phase action of a xtd::threading::barrier after all participating threads have called xtd::threading::barrier::signal_and_wait, the exception will be wrapped in a xtd::threading::barrier_post_phase_exception and be thrown on all participating threads.

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

xtd.core/include/xtd/threading/barrier.h

Definition

Aliases

Constructors

Properties

Methods

Additional Inherited Members

Member Typedef Documentation

◆ post_phase_action

Constructor & Destructor Documentation

◆ barrier() [1/2]

◆ barrier() [2/2]

Member Function Documentation

◆ add_participant()

◆ add_participants()

◆ close()

◆ current_phase_number()

◆ participant_count()

◆ participants_remaining()

◆ remove_participant()

◆ remove_participants()

◆ signal_and_wait() [1/6]

◆ signal_and_wait() [2/6]

◆ signal_and_wait() [3/6]

◆ signal_and_wait() [4/6]

◆ signal_and_wait() [5/6]

◆ signal_and_wait() [6/6]