PTEMS  0.1.0-dev+git.81fd0e4
PolyTopic Element Method Solver
ptems::ParallelComm Class Reference

This class is designed to abstract away the details of whether the project is built with MPI, or in single thread mode. More...

#include <ptems/parallelcomm.hpp>

Public Member Functions

 ParallelComm ()
 Initialise a reference to the "world" communicator. More...
 
 ParallelComm (ParallelComm &&rhs)
 Move constructor. More...
 
ParallelCommoperator= (ParallelComm &&rhs)
 Move assignment. More...
 
 ParallelComm (const ParallelComm &rhs)
 Copy constructor. More...
 
ParallelCommoperator= (const ParallelComm &rhs)
 Copy assignment. More...
 
 ~ParallelComm ()
 Destroy the communicator object. More...
 
template<typename Dist >
auto GenerateRandomNumber (Dist &dist)
 Generates a random number using the specified distribution. More...
 
void DiscardRandomNumbers ([[maybe_unused]] unsigned long long amount)
 Discard the specified number of random numbers from the random number generator. More...
 
std::size_t ProcessRank () const
 Gets the index of the current process in the communicator. More...
 
std::size_t NumberProcessors () const
 Gets the number of processes in the communicator. More...
 
bool IsMainProcess () const
 Gets whether the current process is the "main" process (first process in communicator) More...
 
template<typename T >
void ThrowExceptionOnMain (const std::string &message) const
 Raises the specified exception on the main process (actually raises on all calling processes, but should only be called from code running only on main). More...
 
template<typename T >
void CheckExceptionOnMain () const
 Checks if an exception was raised on the main process. More...
 
template<typename T = std::logic_error>
void ThrowExceptionIfAny (const std::string &message, bool condition) const
 Raises the specified exception on all processors if the specified condition is true on ANY processor. More...
 
template<typename T = std::logic_error>
void ThrowExceptionIfAll (const std::string &message, bool condition) const
 Raises the specified exception on all processors if the specified condition is true on ALL processors. More...
 
template<typename T >
std::enable_if< std::is_scalar< T >::value >::type BroadcastFromMain (T &data) const
 Broadcast the specified value from the "main" process to all other processes. More...
 
template<typename T >
std::enable_if< std::is_scalar< T >::value >::type BroadcastFrom (std::size_t processID, T &data) const
 Broadcast the specified value from the specified process to all other processes. More...
 
template<typename T >
auto BroadcastFromMain ([[maybe_unused]] T &data) const -> decltype(data.data(), void())
 Broadcast the specified C++ random access container from the "main" process to all other processes (this covers std::string, std::vector, etc. More...
 
template<typename T >
auto BroadcastFrom ([[maybe_unused]] std::size_t processID, [[maybe_unused]] T &data) const -> decltype(data.data(), void())
 Broadcast the specified C++ random access container from the specified process to all other processes (this covers std::string, std::vector, etc. More...
 
template<typename T >
void BroadcastFromMain ([[maybe_unused]] T *data, [[maybe_unused]] std::size_t count) const
 Broadcast the specified array of data from the "main" process to all other processes. More...
 
template<typename T >
std::enable_if<!std::is_enum< T >::value >::type BroadcastFrom ([[maybe_unused]] std::size_t processID, [[maybe_unused]] T *data, [[maybe_unused]] std::size_t count) const
 Broadcast the specified array of data from the specified process to all other processes. More...
 
template<typename T >
std::enable_if< std::is_enum< T >::value >::type BroadcastFrom ([[maybe_unused]] std::size_t processID, [[maybe_unused]] T *data, [[maybe_unused]] std::size_t count) const
 Broadcast the specified array of data from the specified process to all other processes. More...
 
template<typename T >
void Gather ([[maybe_unused]] T *data, [[maybe_unused]] std::size_t count) const
 Gather (concatenates) the specified number of elements from the array in each process into the array of the main (first) process. More...
 
template<typename T >
void Gather ([[maybe_unused]] T *data, [[maybe_unused]] std::size_t offset, [[maybe_unused]] std::size_t count) const
 Gather the specified elements from the array in each process into the array of the main (first) process. More...
 
template<typename T >
void Gather ([[maybe_unused]] T &data) const
 Gather (concatenates) the specified elements from the STL container in each process into the STL container of the main (first) process. More...
 
template<typename T >
void AllGather (T *data, std::size_t count, T *out) const
 Gather (concatenates) the specified number of elements from the array in each process into the specified destination array of all processes. More...
 
template<typename T >
void AllGather (T *data, std::size_t offset, std::size_t count, T *out) const
 Gather the specified elements from the array in each process into the destination array of all processes. More...
 
template<typename T >
void AllGather ([[maybe_unused]] T &data) const
 Gather (concatenates) the specified elements from the STL container in each process into the STL container of all processes. More...
 
template<typename T >
void Add (const T *data, T *output, std::size_t count) const
 Performs elementwise addition of the array from each process, and stores it into the destination array of the main process. More...
 
template<typename T >
void AllAdd (const T *data, T *output, std::size_t count) const
 Performs elementwise addition of the array from each process, and stores it into the destination array of all processes. More...
 
template<typename T >
Add (T value) const
 Performs addition of the value from each process and returns the result on main process only. More...
 
template<typename T >
AllAdd (T value) const
 Performs addition of the value from each process and returns the value. More...
 
template<typename T >
Max (T value) const
 Performs maximum of the value from each process and returns the result on main process only. More...
 
template<typename T >
AllMax (T value) const
 Performs maximum of the value from each process and returns the value. More...
 
template<typename T >
Min (T value) const
 Performs minimum of the value from each process and returns the result on main process only. More...
 
template<typename T >
AllMin (T value) const
 Performs minimum of the value from each process and returns the value. More...
 
void And (const bool *data, bool *output, std::size_t count) const
 Performs elementwise logical AND of the array from each process, and stores it into the destination array of the main process. More...
 
void AllAnd (const bool *data, bool *output, std::size_t count) const
 Performs elementwise logical AND of the array from each process, and stores it into the destination array of all processes. More...
 
bool And (bool value) const
 Performs elementwise logical AND of the boolean value from each process and returns the result on main process only. More...
 
bool AllAnd (bool value) const
 Performs elementwise logical AND of the boolean value from each process and returns the value. More...
 
void Or (const bool *data, bool *output, std::size_t count) const
 Performs elementwise logical AND of the array from each process, and stores it into the destination array of the main process. More...
 
void AllOr (const bool *data, bool *output, std::size_t count) const
 Performs elementwise logical AND of the array from each process, and stores it into the destination array of all processes. More...
 
bool Or (bool value) const
 Performs elementwise logical OR of the boolean value from each process and returns the result on main process only. More...
 
bool AllOr (bool value) const
 Performs elementwise logical OR of the boolean value from each process and returns the value. More...
 
ParallelComm Clone () const
 Creates a duplicate of the current communicator. More...
 
ParallelComm Split (int colour, int key) const
 Splits the current communicator into multiple sub communicators. More...
 

Static Public Member Functions

static ParallelComm World ()
 The main "world" communicator. More...
 

Detailed Description

This class is designed to abstract away the details of whether the project is built with MPI, or in single thread mode.

The general principle is to allow the rest of the code to use this class as the MPI communication assuming MPI is available. If, however, the application is built in single process mode this class "fakes" the MPI details (such as returning that only one process is available, the only process is the main process, and all gather/broadcast calls are no-ops).

It also manages a random number generator so that in a multiple processor system each processor uses the same seeded generator but SHOULD skip the generation of numbers generated by other processors

Constructor & Destructor Documentation

◆ ParallelComm() [1/3]

ptems::ParallelComm::ParallelComm ( )

Initialise a reference to the "world" communicator.

◆ ParallelComm() [2/3]

ptems::ParallelComm::ParallelComm ( ParallelComm &&  rhs)

Move constructor.

Parameters
rhsThe ParallelComm object to move to this

◆ ParallelComm() [3/3]

ptems::ParallelComm::ParallelComm ( const ParallelComm rhs)

Copy constructor.

Parameters
rhsThe ParallelComm object to copy to this

◆ ~ParallelComm()

ptems::ParallelComm::~ParallelComm ( )

Destroy the communicator object.

Member Function Documentation

◆ Add() [1/2]

template<typename T >
void ptems::ParallelComm::Add ( const T *  data,
T *  output,
std::size_t  count 
) const
inline

Performs elementwise addition of the array from each process, and stores it into the destination array of the main process.

Template Parameters
TThe type of data to add
Parameters
dataPointer to the array of data to add elementwise
outputPointer to the destination array to store the result (main process only)
countNumber of elements in the input and output arrays

◆ Add() [2/2]

template<typename T >
T ptems::ParallelComm::Add ( value) const
inline

Performs addition of the value from each process and returns the result on main process only.

Parameters
valueValue from current process to add
Returns
The sum of values from all processes (on main process); or just value on other processes (no addition performed)

◆ AllAdd() [1/2]

template<typename T >
void ptems::ParallelComm::AllAdd ( const T *  data,
T *  output,
std::size_t  count 
) const
inline

Performs elementwise addition of the array from each process, and stores it into the destination array of all processes.

Template Parameters
TThe type of data to add
Parameters
dataPointer to the array of data to add elementwise
outputPointer to the destination array to store the result
countNumber of elements in the input and output arrays

◆ AllAdd() [2/2]

template<typename T >
T ptems::ParallelComm::AllAdd ( value) const
inline

Performs addition of the value from each process and returns the value.

Parameters
valueValue from current process to add
Returns
The sum of values from all processes.

◆ AllAnd() [1/2]

bool ptems::ParallelComm::AllAnd ( bool  value) const
inline

Performs elementwise logical AND of the boolean value from each process and returns the value.

Parameters
valueBoolean value from current process to AND
Returns
The logical AND of values from all processes.

◆ AllAnd() [2/2]

void ptems::ParallelComm::AllAnd ( const bool *  data,
bool *  output,
std::size_t  count 
) const
inline

Performs elementwise logical AND of the array from each process, and stores it into the destination array of all processes.

Parameters
dataPointer to the array of data to AND elementwise
outputPointer to the destination array to store the result
countNumber of elements in the input and output arrays

◆ AllGather() [1/3]

template<typename T >
void ptems::ParallelComm::AllGather ( [[maybe_unused] ] T &  data) const
inline

Gather (concatenates) the specified elements from the STL container in each process into the STL container of all processes.

The number of entries in each process can be different.

Wrapper around MPI_Allgatherv

Template Parameters
TThe type of the STL container to gather
Parameters
dataThe STL container containing data to gather. On the main process the gathered data is placed into this container.

◆ AllGather() [2/3]

template<typename T >
void ptems::ParallelComm::AllGather ( T *  data,
std::size_t  count,
T *  out 
) const
inline

Gather (concatenates) the specified number of elements from the array in each process into the specified destination array of all processes.

Wrapper around MPI_Allgather

Template Parameters
TThe type of data to gather
Parameters
dataPointer to the array of data to gather.
countThe number of elements to send. Must be the same for all processes.
outArray to gather the data into. The array in the main process MUST be large enough to store the data from all processes. This array can be the same as data.

◆ AllGather() [3/3]

template<typename T >
void ptems::ParallelComm::AllGather ( T *  data,
std::size_t  offset,
std::size_t  count,
T *  out 
) const
inline

Gather the specified elements from the array in each process into the destination array of all processes.

The number of entries in each process can be different, and can be gathered into an arbitrary offset in the destination.

Wrapper around MPI_Allgatherv

Template Parameters
TThe type of data to gather
Parameters
dataPointer to the array of data to gather.
offsetOffset into the destination array of the location to gather the data from this process
countThe number of elements to send. Can be different for different processes.
outArray to gather the data into. The array in the main process MUST be large enough to store the data from all processes. This array can be the same as data.

◆ AllMax()

template<typename T >
T ptems::ParallelComm::AllMax ( value) const
inline

Performs maximum of the value from each process and returns the value.

Parameters
valueValue from current process to add
Returns
The maximum of values from all processes.

◆ AllMin()

template<typename T >
T ptems::ParallelComm::AllMin ( value) const
inline

Performs minimum of the value from each process and returns the value.

Parameters
valueValue from current process to add
Returns
The minimum of values from all processes.

◆ AllOr() [1/2]

bool ptems::ParallelComm::AllOr ( bool  value) const
inline

Performs elementwise logical OR of the boolean value from each process and returns the value.

Parameters
valueBoolean value from current process to OR
Returns
The logical OR of values from all processes.

◆ AllOr() [2/2]

void ptems::ParallelComm::AllOr ( const bool *  data,
bool *  output,
std::size_t  count 
) const
inline

Performs elementwise logical AND of the array from each process, and stores it into the destination array of all processes.

Parameters
dataPointer to the array of data to AND elementwise
outputPointer to the destination array to store the result
countNumber of elements in the input and output arrays

◆ And() [1/2]

bool ptems::ParallelComm::And ( bool  value) const
inline

Performs elementwise logical AND of the boolean value from each process and returns the result on main process only.

Parameters
valueBoolean value from current process to AND
Returns
The logical AND of values from all processes (on main process); or just value on other processes (no logical AND performed)

◆ And() [2/2]

void ptems::ParallelComm::And ( const bool *  data,
bool *  output,
std::size_t  count 
) const
inline

Performs elementwise logical AND of the array from each process, and stores it into the destination array of the main process.

Parameters
dataPointer to the array of data to AND elementwise
outputPointer to the destination array to store the result (main process only)
countNumber of elements in the input and output arrays

◆ BroadcastFrom() [1/4]

template<typename T >
auto ptems::ParallelComm::BroadcastFrom ( [[maybe_unused] ] std::size_t  processID,
[[maybe_unused] ] T &  data 
) const -> decltype(data.data(), void())
inline

Broadcast the specified C++ random access container from the specified process to all other processes (this covers std::string, std::vector, etc.

but not std::list etc.)

Template Parameters
TThe container type to broadcast
Parameters
processIDThe process ID to broadcast from
dataData to broadcast

◆ BroadcastFrom() [2/4]

template<typename T >
std::enable_if<!std::is_enum<T>::value>::type ptems::ParallelComm::BroadcastFrom ( [[maybe_unused] ] std::size_t  processID,
[[maybe_unused] ] T *  data,
[[maybe_unused] ] std::size_t  count 
) const
inline

Broadcast the specified array of data from the specified process to all other processes.

Template Parameters
TThe type of data to broadcast, where T is NOT an enumeration type
Parameters
processIDThe process ID to broadcast from
dataPointer to the array of data to broadcast
countThe size of the array

◆ BroadcastFrom() [3/4]

template<typename T >
std::enable_if<std::is_enum<T>::value>::type ptems::ParallelComm::BroadcastFrom ( [[maybe_unused] ] std::size_t  processID,
[[maybe_unused] ] T *  data,
[[maybe_unused] ] std::size_t  count 
) const
inline

Broadcast the specified array of data from the specified process to all other processes.

Template Parameters
TThe type of data to broadcast, where T is an enumeration type
Parameters
processIDThe process ID to broadcast from
dataPointer to the array of data to broadcast
countThe size of the array

◆ BroadcastFrom() [4/4]

template<typename T >
std::enable_if<std::is_scalar<T>::value>::type ptems::ParallelComm::BroadcastFrom ( std::size_t  processID,
T &  data 
) const
inline

Broadcast the specified value from the specified process to all other processes.

Template Parameters
TThe type of data to broadcast
Parameters
processIDThe process ID to broadcast from
dataData to broadcast

◆ BroadcastFromMain() [1/3]

template<typename T >
auto ptems::ParallelComm::BroadcastFromMain ( [[maybe_unused] ] T &  data) const -> decltype(data.data(), void())
inline

Broadcast the specified C++ random access container from the "main" process to all other processes (this covers std::string, std::vector, etc.

but not std::list etc.)

Template Parameters
TThe container type to broadcast
Parameters
dataData to broadcast

◆ BroadcastFromMain() [2/3]

template<typename T >
void ptems::ParallelComm::BroadcastFromMain ( [[maybe_unused] ] T *  data,
[[maybe_unused] ] std::size_t  count 
) const
inline

Broadcast the specified array of data from the "main" process to all other processes.

Template Parameters
TThe type of data to broadcast, where T is NOT an enumeration type
Parameters
dataPointer to the array of data to broadcast
countThe size of the array

◆ BroadcastFromMain() [3/3]

template<typename T >
std::enable_if<std::is_scalar<T>::value>::type ptems::ParallelComm::BroadcastFromMain ( T &  data) const
inline

Broadcast the specified value from the "main" process to all other processes.

Template Parameters
TThe type of data to broadcast
Parameters
dataData to broadcast

◆ CheckExceptionOnMain()

template<typename T >
void ptems::ParallelComm::CheckExceptionOnMain ( ) const
inline

Checks if an exception was raised on the main process.

Should be called on ALL processes (even main if no exception was raised) after any block of code that may have called ThrowExceptionOnMain

Template Parameters
TThe exception type to raise is an exception occurred on main
Exceptions
T(which may not be the same as the type raised by ThrowExceptionOnMain) if an exception occurred on main

◆ Clone()

ParallelComm ptems::ParallelComm::Clone ( ) const

Creates a duplicate of the current communicator.

Returns
The duplicated communicator.

◆ DiscardRandomNumbers()

void ptems::ParallelComm::DiscardRandomNumbers ( [[maybe_unused] ] unsigned long long  amount)
inline

Discard the specified number of random numbers from the random number generator.

◆ Gather() [1/3]

template<typename T >
void ptems::ParallelComm::Gather ( [[maybe_unused] ] T &  data) const
inline

Gather (concatenates) the specified elements from the STL container in each process into the STL container of the main (first) process.

The number of entries in each process can be different.

Wrapper around MPI_Gatherv

Template Parameters
TThe type of the STL container to gather
Parameters
dataThe STL container containing data to gather. On the main process the gathered data is placed into this container.

◆ Gather() [2/3]

template<typename T >
void ptems::ParallelComm::Gather ( [[maybe_unused] ] T *  data,
[[maybe_unused] ] std::size_t  count 
) const
inline

Gather (concatenates) the specified number of elements from the array in each process into the array of the main (first) process.

Wrapper around MPI_Gather

Template Parameters
TThe type of data to gather
Parameters
dataPointer to the array of data to gather. On the main process the gathered data is placed into this array (the main process should already have the data in the first count entries). The array in the main process MUST be large enough to store the data from all processes.
countThe number of elements to send. Must be the same for all processes.

◆ Gather() [3/3]

template<typename T >
void ptems::ParallelComm::Gather ( [[maybe_unused] ] T *  data,
[[maybe_unused] ] std::size_t  offset,
[[maybe_unused] ] std::size_t  count 
) const
inline

Gather the specified elements from the array in each process into the array of the main (first) process.

The number of entries in each process can be different, and can be gathered into an arbitrary offset in the main process.

Wrapper around MPI_Gatherv

Template Parameters
TThe type of data to gather
Parameters
dataPointer to the array of data to gather. On the main process the gathered data is placed into this array (the main process should already have the data in the correct location). The array in the main process MUST be large enough to store the data from all processes.
offsetOffset into the array in the main process of the location to gather the data from this process
countThe number of elements to send. Can be different for different processes.

◆ GenerateRandomNumber()

template<typename Dist >
auto ptems::ParallelComm::GenerateRandomNumber ( Dist &  dist)
inline

Generates a random number using the specified distribution.

Note
This method assumes that each processor calls this function the same number of times. This may not be 100% accurate, which may cause issues with the PNG properties. As such, possibly best to at least call DiscardRandomNumbers() to attempt to even the calls
Template Parameters
Thetype of the random number distribution
Parameters
distThe random number distribution to use
Returns
The generated random number

◆ IsMainProcess()

bool ptems::ParallelComm::IsMainProcess ( ) const
inline

Gets whether the current process is the "main" process (first process in communicator)

Returns
true If the current process is the first processor in the communicator
false If the current process is not the first processor in communicator

◆ Max()

template<typename T >
T ptems::ParallelComm::Max ( value) const
inline

Performs maximum of the value from each process and returns the result on main process only.

Parameters
valueValue from current process to calculate max of
Returns
The maximum of values from all processes (on main process); or just value on other processes (no max performed)

◆ Min()

template<typename T >
T ptems::ParallelComm::Min ( value) const
inline

Performs minimum of the value from each process and returns the result on main process only.

Parameters
valueValue from current process to calculate min of
Returns
The minimum of values from all processes (on main process); or just value on other processes (no min performed)

◆ NumberProcessors()

std::size_t ptems::ParallelComm::NumberProcessors ( ) const
inline

Gets the number of processes in the communicator.

Returns
Number of processes

◆ operator=() [1/2]

ParallelComm& ptems::ParallelComm::operator= ( const ParallelComm rhs)

Copy assignment.

Parameters
rhsThe ParallelComm object to move to this

◆ operator=() [2/2]

ParallelComm& ptems::ParallelComm::operator= ( ParallelComm &&  rhs)

Move assignment.

Parameters
rhsThe ParallelComm object to move to this

◆ Or() [1/2]

bool ptems::ParallelComm::Or ( bool  value) const
inline

Performs elementwise logical OR of the boolean value from each process and returns the result on main process only.

Parameters
valueBoolean value from current process to OR
Returns
The logical OR of values from all processes (on main process); or just value on other processes (no logical OR performed)

◆ Or() [2/2]

void ptems::ParallelComm::Or ( const bool *  data,
bool *  output,
std::size_t  count 
) const
inline

Performs elementwise logical AND of the array from each process, and stores it into the destination array of the main process.

Parameters
dataPointer to the array of data to AND elementwise
outputPointer to the destination array to store the result (main process only)
countNumber of elements in the input and output arrays

◆ ProcessRank()

std::size_t ptems::ParallelComm::ProcessRank ( ) const
inline

Gets the index of the current process in the communicator.

Returns
Index of current process

◆ Split()

ParallelComm ptems::ParallelComm::Split ( int  colour,
int  key 
) const

Splits the current communicator into multiple sub communicators.

Wrapper around MPI_Comm_split. All processes which passes the same value for colour will end up in the subcommunicator, ordered such that the lowest key of all processes in the same communicator is the "first" process.

Parameters
colourIndex denoting subcommunicator process will be added to
keyKey to use to indicate order of processes in new communicators
Returns
The subcommunicator containing this process

◆ ThrowExceptionIfAll()

template<typename T = std::logic_error>
void ptems::ParallelComm::ThrowExceptionIfAll ( const std::string message,
bool  condition 
) const
inline

Raises the specified exception on all processors if the specified condition is true on ALL processors.

Template Parameters
TThe exception type to raise
Parameters
messageThe exception error message
conditionCondition that if true on ALL processors causes the excpetion to be thrown
Exceptions
Tif condition is true on ALL process

◆ ThrowExceptionIfAny()

template<typename T = std::logic_error>
void ptems::ParallelComm::ThrowExceptionIfAny ( const std::string message,
bool  condition 
) const
inline

Raises the specified exception on all processors if the specified condition is true on ANY processor.

Template Parameters
TThe exception type to raise
Parameters
messageThe exception error message
conditionCondition that if true on ANY processors causes the excpetion to be thrown
Exceptions
Tif condition is true on ALL process

◆ ThrowExceptionOnMain()

template<typename T >
void ptems::ParallelComm::ThrowExceptionOnMain ( const std::string message) const
inline

Raises the specified exception on the main process (actually raises on all calling processes, but should only be called from code running only on main).

After any block of code which calls ThrowExceptionOnMain a call to CheckExceptionOnMain should be made on ALL processes (including main process if no exception was raised)

Template Parameters
TThe exception type to raise
Parameters
messageThe exception error message
Exceptions
Tis always thrown

◆ World()

static ParallelComm ptems::ParallelComm::World ( )
static

The main "world" communicator.


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