#include <mpi/communicator.hpp>

Detailed Description

C++ wrapper around MPI_Comm providing various convenience functions.

It stores an MPI_Comm object as its only member which by default is set to MPI_COMM_WORLD. The underlying MPI_Comm object is not freed when a communicator goes out of scope. It is the user's responsibility to do so, in case it is needed. Note that copying the communicator simply copies the MPI_Comm object, without calling MPI_Comm_dup.

All functions that make direct calls to the MPI C library throw an exception in case the call fails.

Definition at line 48 of file communicator.hpp.

Inheritance diagram for mpi::communicator:

Public Member Functions
	communicator ()=default
	Construct a communicator with MPI_COMM_WORLD.
	communicator (MPI_Comm c)
	Construct a communicator with a given MPI_Comm object.
void	abort (int error_code) const
	If mpi::has_env is true, MPI_Abort is called with the given error code, otherwise it calls std::abort.
void	barrier (long poll_msec=1) const
	Barrier synchronization.
communicator	duplicate () const
	Duplicate the communicator.
void	free ()
	Free the communicator.
MPI_Comm	get () const noexcept
	Get the wrapped MPI_Comm object.
bool	is_null () const noexcept
	Check if the contained MPI_Comm is MPI_COMM_NULL.
int	rank () const
	Get the rank of the calling process in the communicator.
int	size () const
	Get the size of the communicator.
communicator	split (int color, int key=0) const
	Split the communicator into disjoint subgroups.
shared_communicator	split_shared (int split_type=MPI_COMM_TYPE_SHARED, int key=0) const
	Partition the communicator into subcommunicators according to their type.

Constructor & Destructor Documentation

◆ communicator()

mpi::communicator::communicator ( MPI_Comm c )

inline

Construct a communicator with a given MPI_Comm object.

The MPI_Comm object is copied without calling MPI_Comm_dup.

Parameters

c	MPI_Comm object to wrap.

Definition at line 58 of file communicator.hpp.

Member Function Documentation

◆ abort()

void mpi::communicator::abort ( int error_code ) const

inline

If mpi::has_env is true, MPI_Abort is called with the given error code, otherwise it calls std::abort.

Parameters

error_code The error code to pass to MPI_Abort.

Definition at line 158 of file communicator.hpp.

◆ barrier()

void mpi::communicator::barrier ( long poll_msec = 1 ) const

inline

Barrier synchronization.

Does nothing if mpi::has_env is false. Otherwise, it either uses a blocking MPI_Barrier (if the given argument is 0) or a non-blocking MPI_Ibarrier call. The given parameter determines in milliseconds how often each process calls MPI_Test to check if all processes have reached the barrier.

This can considerably reduce the CPU load:

1 msec ~ 1% cpu load
10 msec ~ 0.5% cpu load
100 msec ~ 0.01% cpu load

For a very unbalanced load that takes a long time to finish, 1000 msec is a good choice.

Parameters

poll_msec Polling interval in milliseconds. If set to 0, a simple MPI_Barrier call is used.

Definition at line 188 of file communicator.hpp.

◆ duplicate()

communicator mpi::communicator::duplicate ( ) const

inlinenodiscard

Duplicate the communicator.

Calls MPI_Comm_dup to duplicate the communicator. See the MPI documentation for more details, e.g. open-mpi docs.

Warning: This allocates a new communicator object. Make sure to call free on the returned communicator when it is no longer needed.

Returns: If mpi::has_env is true, return the duplicated MPI_Comm object wrapped in a new mpi::communicator, otherwise return a default constructed mpi::communicator.

Definition at line 135 of file communicator.hpp.

◆ free()

void mpi::communicator::free ( )

inline

Free the communicator.

Calls MPI_Comm_free to mark the communicator for deallocation. See the MPI documentation for more details, e.g. open-mpi docs .

Does nothing, if mpi::has_env is false.

Definition at line 150 of file communicator.hpp.

◆ rank()

int mpi::communicator::rank ( ) const

inlinenodiscard

Get the rank of the calling process in the communicator.

Returns: The result of MPI_Comm_rank if mpi::has_env is true, otherwise 0.

Definition at line 70 of file communicator.hpp.

◆ size()

int mpi::communicator::size ( ) const

inlinenodiscard

Get the size of the communicator.

Returns: The result of MPI_Comm_size if mpi::has_env is true, otherwise 1.

Definition at line 80 of file communicator.hpp.

◆ split()

communicator mpi::communicator::split	(	int	color,
		int	key = 0 ) const

inlinenodiscard

Split the communicator into disjoint subgroups.

Calls MPI_Comm_split with the given color and key arguments. See the MPI documentation for more details, e.g. open-mpi docs.

Warning: This allocates a new communicator object. Make sure to call free() on the returned communicator when it is no longer needed.

Parameters

color	Determines which processes are put into the same group.
key	Determines the rank of the process in the new communicator.

Returns: If mpi::has_env is true, return the split MPI_Comm object wrapped in a new mpi::communicator, otherwise return a default constructed mpi::communicator.

Definition at line 101 of file communicator.hpp.

◆ split_shared()

shared_communicator mpi::communicator::split_shared	(	int	split_type = MPI_COMM_TYPE_SHARED,
		int	key = 0 ) const

inlinenodiscard

Partition the communicator into subcommunicators according to their type.

In the MPI3.0 standard the only supported split type is MPI_COMM_TYPE_SHARED. OpenMPI (and possibly other implementations) provide more custom split types, however, they are not portable.

Warning: This allocates a new communicator object. Make sure to call free on the returned communicator when it is no longer needed.

Parameters

split_type	Type of processes to be grouped together.
key	Determines the rank of the process in the new communicator.

Returns: If mpi::has_env is true, return the split MPI_Comm object wrapped in a new mpi::communicator, otherwise return a default constructed mpi::communicator.

Definition at line 225 of file communicator.hpp.

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

mpi/communicator.hpp

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

◆ communicator()

Member Function Documentation

◆ abort()

◆ barrier()

◆ duplicate()

◆ free()

◆ rank()

◆ size()

◆ split()

◆ split_shared()