stapl::runtime::mpi_communicator Class Reference

Implements a communicator based on MPI-2. More...

Public Member Functions
	mpi_communicator (mpi_communicator const &)=delete
mpi_communicator &	operator= (mpi_communicator const &)=delete
void	initialize (option const &opts)
	Initializes this mpi_communicator object. More...
void	finalize (void)
	Finalizes this mpi_communicator object. More...
void	start (void)
	Starts this mpi_communicator object. More...
void	stop (void)
	Stops this mpi_communicator object. More...
bool	initialized (void) const noexcept
int	get_id (void) const noexcept
int	size (void) const noexcept
int	get_num_procs_per_node (void) const noexcept
void	exit (int exit_code) const
void	set_default_message_size (const std::size_t size)
	Sets the default communication message size. More...
void	lock (void)
void	unlock (void)
MPI_Request &	request_get (message &m)
	Returns an MPI_Request object associated with m.
request_container_type &	request_get (message &m, const size_type n)
	Returns n MPI_Request objects associated with m.
request_container_type &	request_get_all (message &m)
	Returns all the n MPI_Request objects associated with m.
void	post_receive_message (message *m)
	Posts an MPI_Irecv() with the given message. More...
void	create_receive_message (const size_type n=1)
	Creates a number of MPI_Irecv(), waiting for messages to be received. More...
void	cancel_receive_messages (void)
	Cancels all pending MPI_Irecv().
message *	try_receive_long (int source, const std::size_t s)
	Tries to receive a long message from process source of size s. More...
message *	wait_receive_long (int source, const std::size_t s)
	Waits to receive a long message from process source of size s.
void	notify_sent_message (int dest, message &m)
	Notifies that m has been sent to dest. More...
void	notify_sent_message (message &m)
	Notifies that m has been sent to multiple destinations. More...
void	test_sent_messages (void)
	Removes all the successfully sent messages from the pending queues.
void	wait_sent_messages (void)
	Waits for all the messages in the pending and forwarded queues to be sent.
void	notify_fwd_message (message &m)
	Notifies that m has been forwarded.
template<typename Container >
void	test_fwd_messages (Container &c)
	Removes all the successfully forwarded messages from the pending queue and pushes them back in c.
void	send_impl (const int dest, message &m)
	Sends m to dest.
void	send_long_impl (const int dest, message &m)
	Sends m, which is a long message, to dest. More...
template<typename ForwardRange >
void	send_impl (ForwardRange const &r, message &m, const bool keep)
	Sends m to processes in r. More...
template<typename ForwardRange >
void	send_long_impl (ForwardRange &&r, message &m, const bool keep)
	Sends m, which is a long message, to processes in r. More...
void	send (const int dest, message_ptr p)
	Sends the message to the given destination. More...
template<typename ForwardRange >
void	send (ForwardRange &&r, message_ptr p, const bool keep)
	Sends the message to multiple destinations. More...
message_slist	receive (const bool wait)
	Receives all messages that can be received and puts them in the given list. More...

Static Public Member Functions
static bool	environment_is_initialized (void) noexcept
	Returns true if the environment is initialized.
static void	environment_initialize (option const &opts)
	Initializes the environment. More...
static void	environment_finalize (void) noexcept
	Finalizes the environment. More...
static std::pair< int, std::size_t >	test_receive (message &m) noexcept
	Tests m if it was received. More...
static std::pair< int, std::size_t >	wait_receive (message &m) noexcept
	Waits for m to be received.
static bool	test_sent_message (message &m) noexcept
	Returns true if m was successfully sent.
static void	wait_sent_message (message &m) noexcept
	Waits for m to be sent.

Public Types
using	size_type = std::size_t

Detailed Description

Implements a communicator based on MPI-2.

The number of processes to use is determined by the underlying MPI implementation. Usually, this is set by the mpiexec -n command, although some implementations use command line flags.

Assumptions:

1. MPI errors are fatal (i.e., abort), as specified by the standard.
2. homogeneous runtime environment (i.e., all MPI processes are running on the same platform).
3. MPI is not thread-safe.

Member Function Documentation

environment_initialize()

static void stapl::runtime::mpi_communicator::environment_initialize ( option const &  opts )

static

Initializes the environment.

MPI_Init_thread() with the required thread support will be called if the MPI library has not been initialized yet (i.e MPI_Initialized() returns false).

Through the opts object the user can set STAPL_RUNTIME_MPI_RECV_MIN and STAPL_RUNTIME_MPI_RECV_MAX for the minimum and maximum number of pending MPI_Irecv() as well as STAPL_RUNTIME_MPI_SEND_MAX for the maximum number of MPI_Isend() before the communicator is considered overloaded.

Parameters

opts	option object passed from the user.

Warning

If the MPI library does not support the required thread support, then a failure will occur. Adjust your MPI library accordingly.

environment_finalize()

static void stapl::runtime::mpi_communicator::environment_finalize ( void  )

staticnoexcept

Finalizes the environment.

MPI_Finalize() will be called if the runtime was responsible for initializing the MPI library in the first place.

See also

mpi_communicator::initialize_environment()

initialize()

void stapl::runtime::mpi_communicator::initialize

(

option const &

opts

)

Initializes this mpi_communicator object.

This function can receive options through the opts object. The user can define the MPI commmunicator to use by setting it accordingly with the MPI_Comm tag in opts, as well a Cartesian topology through the tag MPI_Cart.

Parameters

opts	option object to initialize this mpi_communicator.

finalize()

void stapl::runtime::mpi_communicator::finalize

(

void

)

Finalizes this mpi_communicator object.

All pending messages will be canceled. An implicit barrier is part of the cleanup to ensure correctness.

start()

void stapl::runtime::mpi_communicator::start

(

void

)

Starts this mpi_communicator object.

New messages will be allocated to waiting for incoming communication. An implicit barrier is part of the setup to ensure that no process will start communication before other processes had the opportunity to finish their setup.

stop()

void stapl::runtime::mpi_communicator::stop

(

void

)

Stops this mpi_communicator object.

All pending messages will be canceled. An implicit barrier is part of the cleanup to ensure correctness.

set_default_message_size()

void stapl::runtime::mpi_communicator::set_default_message_size

(

const std::size_t

size

)

Sets the default communication message size.

Warning

This is a collective operation and is supposed to be called by one thread on each process only.

Parameters

size	Size of the message objects.

See also

message

post_receive_message()

void stapl::runtime::mpi_communicator::post_receive_message

(

message *

m

)

Posts an MPI_Irecv() with the given message.

Parameters

m	Message to post for reception.

create_receive_message()

void stapl::runtime::mpi_communicator::create_receive_message

(

const size_type

n = 1

)

Creates a number of MPI_Irecv(), waiting for messages to be received.

Parameters

n	Number of messages to pre-fire for receiving.

test_receive()

static std::pair<int, std::size_t> stapl::runtime::mpi_communicator::test_receive ( message &  m )

staticnoexcept

Tests m if it was received.

Returns

A std::pair with the sender process id and the size of the message if it was succesfully received, otherwise a std::pair of MPI_PROC_NULL and 0.

try_receive_long()

message* stapl::runtime::mpi_communicator::try_receive_long	(	int	source,
		const std::size_t	s
	)

Tries to receive a long message from process source of size s.

Returns

A pointer to the message if it was received, otherwise nullptr.

notify_sent_message() [1/2]

void stapl::runtime::mpi_communicator::notify_sent_message	(	int	dest,
		message &	m
	)

Notifies that m has been sent to dest.

If m was not successfully sent yet, it will be added to a queue to be checked later.

notify_sent_message() [2/2]

void stapl::runtime::mpi_communicator::notify_sent_message

(

message &

m

)

Notifies that m has been sent to multiple destinations.

If m was not successfully sent yet, it will be added to a queue to be checked later.

send_long_impl() [1/2]

void stapl::runtime::mpi_communicator::send_long_impl	(	const int	dest,
		message &	m
	)

Sends m, which is a long message, to dest.

This function sends the size of the m to the regular message channel and the actual message to the long message channel.

send_impl()

template<typename ForwardRange >

void stapl::runtime::mpi_communicator::send_impl	(	ForwardRange const &	r,
		message &	m,
		const bool	keep
	)

Sends m to processes in r.

Parameters

r	Processes to send m to.
m	Message to send.
keep	true if the current process should keep a copy of m.

send_long_impl() [2/2]

template<typename ForwardRange >

void stapl::runtime::mpi_communicator::send_long_impl	(	ForwardRange &&	r,
		message &	m,
		const bool	keep
	)

Sends m, which is a long message, to processes in r.

Parameters

r	Processes to send m to.
m	Message to send.
keep	true if the current process should keep a copy of m.

send() [1/2]

void stapl::runtime::mpi_communicator::send	(	const int	dest,
		message_ptr	p
	)

Sends the message to the given destination.

Parameters

dest	Destination of the message
p	Message to be sent.

send() [2/2]

template<typename ForwardRange >

void stapl::runtime::mpi_communicator::send	(	ForwardRange &&	r,
		message_ptr	p,
		const bool	keep
	)

Sends the message to multiple destinations.

Parameters

r	Range of destinations.
p	Message to be sent.
keep	true if the current process should keep a copy of m.

receive()

message_slist stapl::runtime::mpi_communicator::receive

(

const bool

wait

)

Receives all messages that can be received and puts them in the given list.

Tests the buffers initialized for reception, then removes, sorts and replaces the ones that have already completed. The call can be specified either blocking or non-blocking and only tests one more buffer than the number of received messages. It can receive more messages than the length of the receiving queue.

Parameters

wait	true if the call should be blocking, false if not.

Returns

The number of received messages.

---

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

• mpi_communicator.hpp