xtd::threading::barrier Class Reference

Inheritance diagram for xtd::threading::barrier:

Definition

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

class barrier : public xtd::object

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.

Examples

barrier.cpp, and barrier_simple.cpp.

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

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

Public Properties
int32	current_phase_number () const
	Gets the number of the barrier's current phase.
int32	participant_count () const
	Gets the total number of participants in the barrier.
int32	participants_remaining () const
	Gets the number of participants in the barrier that haven't yet signaled in the current phase.

Public Methods
int32	add_participant ()
	Notifies the xtd::threading::barrier that there will be an additional participant.
int32	add_participants (int32 participant_count)
	Notifies the xtd::threading::barrier that there will be additional participants.
void	close ()
	Close the current instance of the xtd::threading::barrier class.
int32	remove_participant ()
	Notifies the Barrier that there will be one less participant.
int32	remove_participants (int32 participant_count)
	Notifies the Barrier that there will be fewer participants.
void	signal_and_wait ()
	Signals that a participant has reached the barrier and waits for all other participants to reach the barrier as well.
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.
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.
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.
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.
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.

Additional Inherited Members
Public Member Functions inherited from xtd::object
	object ()=default
	Create a new instance of the ultimate base class object.
bool	equals (const object &obj) const noexcept
	Determines whether the specified object is equal to the current object.
virtual size_t	get_hash_code () const noexcept
	Serves as a hash function for a particular type.
virtual type_object	get_type () const noexcept
	Gets the type of the current instance.
template<typename object_t >
std::unique_ptr< object_t >	memberwise_clone () const noexcept
	Creates a shallow copy of the current object.
virtual xtd::ustring	to_string () const noexcept
	Returns a sxd::ustring that represents the current object.
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.
static bool	reference_equals (const object &object_a, const object &object_b) noexcept
	Determines whether the specified object instances are the same instance.

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.

Examples

barrier.cpp.

close()

void xtd::threading::barrier::close

(

)

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

Examples

barrier.cpp.

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.

Examples

barrier.cpp.

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.

Examples

barrier.cpp, and barrier_simple.cpp.

signal_and_wait() [2/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.

Exceptions

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() [3/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() [4/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.

signal_and_wait() [5/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() [6/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.

---

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

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