xtd 0.2.0
Loading...
Searching...
No Matches
xtd::threading::barrier Class Reference
Inheritance diagram for xtd::threading::barrier:
xtd::object

Definition

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

class barrier : public xtd::object
Supports all classes in the xtd class hierarchy and provides low-level services to derived classes....
Definition object.h:42
Enables multiple tasks to cooperatively work on an algorithm in parallel through multiple phases.
Definition barrier.h:31
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
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!");
}}};
// Nope -- changed my mind. Let's make it five participants.
// Nope -- let's settle on four participants.
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 {
} 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();
}
};
}
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
virtual const xtd::string & message() const noexcept
Gets message associate to the exception.
The exception that is thrown when a method call is invalid for the object's current state.
Definition system_exception.h:18
The exception that is thrown when a Thread is in an invalid ThreadState for the method call.
Definition barrier_post_phase_exception.h:28
int32 remove_participant()
Notifies the Barrier that there will be one less 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.
void signal_and_wait()
Signals that a participant has reached the barrier and waits for all other participants to reach the ...
#define startup_(main_method)
Defines the entry point to be called when the application loads. Generally this is set either to the ...
Definition startup.h:175
delegate< void(arguments_t...)> action
Represents a xtd::delegate that has variable parameters and does not return a value.
Definition action.h:20
@ b
The B key.
The xtd::threading namespace provides classes and interfaces that enable multithreaded programming....
Definition abandoned_mutex_exception.h:11
The xtd namespace contains all fundamental classes to access Hardware, Os, System,...
Definition xtd_about_box.h:10
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.
 
virtual 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 >
xtd::uptr< object_t > memberwise_clone () const
 Creates a shallow copy of the current object.
 
virtual xtd::string to_string () const noexcept
 Returns a xtd::string that represents the current object.
 
- Static Public Member Functions inherited from xtd::object
template<typename object_a_t , typename object_b_t >
static bool equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are considered equal.
 
template<typename object_a_t , typename object_b_t >
static bool reference_equals (const object_a_t &object_a, const object_b_t &object_b) noexcept
 Determines whether the specified object instances are the same instance.
 

Member Typedef Documentation

◆ post_phase_action

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_countThe number of participating threads.
Exceptions
xtd::argument_out_of_range_exceptionparticipant_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_countThe number of participating threads.
post_phase_actionThe 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_exceptionparticipant_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

◆ 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_exceptionThe 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_exceptionThe 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_exceptionThe 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.

◆ 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_exceptionThe current instance has already been disposed.
xtd::argument_out_of_range_exceptionAdding 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_countThe 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_exceptionThe current instance has already been disposed.
xtd::argument_out_of_range_exceptionparticipant_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.

◆ 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_exceptionThe current instance has already been disposed.
xtd::argument_out_of_range_exceptionThe 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_countThe 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_exceptionThe current instance has already been disposed.
xtd::argument_out_of_range_exceptionparticipant_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_exceptionThe current instance has already been disposed.
xtd::threading::barrier_post_phase_exceptionIf 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 ( 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_timeoutThe 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_exceptionmilliseconds_timeout is a negative number other than -1, which represents an infinite time-out.
xtd::object_closed_exceptionThe current instance has already been disposed.
xtd::threading::barrier_post_phase_exceptionIf 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_tokenThe xtd::threading::cancellation_token to observe.
Returns
true if all participants reached the barrier within the specified time; otherwise false.
Exceptions
xtd::operation_canceled_exceptioncancellation_token has been canceled.
xtd::object_closed_exceptionThe current instance has already been disposed.
xtd::threading::barrier_post_phase_exceptionIf 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
timoutA 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_exceptionmilliseconds_timeout is a negative number other than -1, which represents an infinite time-out.
xtd::object_closed_exceptionThe current instance has already been disposed.
xtd::threading::barrier_post_phase_exceptionIf 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_timeoutThe number of milliseconds to wait, or xtd::threading::timeout::infinite(-1) to wait indefinitely.
cancellation_tokenThe 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_exceptionmilliseconds_timeout is a negative number other than -1, which represents an infinite time-out.
xtd::operation_canceled_exceptioncancellation_token has been canceled.
xtd::object_closed_exceptionThe current instance has already been disposed.
xtd::threading::barrier_post_phase_exceptionIf 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
timoutA xtd::time_span that represents the number of milliseconds to wait, or a xtd::time_span that represents -1 milliseconds to wait indefinitely.
cancellation_tokenThe 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_exceptionmilliseconds_timeout is a negative number other than -1, which represents an infinite time-out.
xtd::operation_canceled_exceptioncancellation_token has been canceled.
xtd::object_closed_exceptionThe current instance has already been disposed.
xtd::threading::barrier_post_phase_exceptionIf 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: