Point-to-Point communcation

KaMPIng's point-to-point communication wrappers. More...

Functions
template<typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::iprobe (Args... args) const
	Wrapper for MPI_Iprobe.
template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::irecv (Args... args) const
	Wrapper for MPI_Recv.
template<typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::isend (Args... args) const
	Wrapper for MPI_Isend.
template<typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::ibsend (Args... args) const
	Convenience wrapper for MPI_Ibsend. Calls kamping::Communicator::isend() with the appropriate send mode set.
template<typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::issend (Args... args) const
	Convenience wrapper for MPI_Issend. Calls kamping::Communicator::isend() with the appropriate send mode set.
template<typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::irsend (Args... args) const
	Convenience wrapper for MPI_Irsend. Calls kamping::Communicator::isend() with the appropriate send mode set.
template<typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::probe (Args... args) const
	Wrapper for MPI_Probe.
template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::recv (Args... args) const
	Wrapper for MPI_Recv.
template<typename recv_value_type_tparam , typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::recv_single (Args... args) const
	Convience wrapper for receiving single values via MPI_Recv.
template<typename... Args>
void	kamping::Communicator< DefaultContainerType, Plugins >::send (Args... args) const
	Wrapper for MPI_Send.
template<typename... Args>
void	kamping::Communicator< DefaultContainerType, Plugins >::bsend (Args... args) const
	Convenience wrapper for MPI_Bsend. Calls kamping::Communicator::send() with the appropriate send mode set.
template<typename... Args>
void	kamping::Communicator< DefaultContainerType, Plugins >::ssend (Args... args) const
	Convenience wrapper for MPI_Ssend. Calls kamping::Communicator::send() with the appropriate send mode set.
template<typename... Args>
void	kamping::Communicator< DefaultContainerType, Plugins >::rsend (Args... args) const
	Convenience wrapper for MPI_Rsend. Calls kamping::Communicator::send() with the appropriate send mode set.
template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::sendrecv (Args... args) const
	Wrapper for MPI_Sendrecv.
template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::try_recv (Args... args) const
	Receives a message if one is available.

Detailed Description

KaMPIng's point-to-point communication wrappers.

Function Documentation

iprobe()

template<template< typename... > typename DefaultContainerType, template< typename, template< typename... > typename > typename... Plugins>

template<typename... Args>

auto kamping::Communicator< DefaultContainerType, Plugins >::iprobe

(

Args...

args

)

const

Wrapper for MPI_Iprobe.

This wraps MPI_Iprobe. This operation checks if there is a message matching the (optionally) specified source and tag that can be received, and returns a bool indicating whether a message matched by default. If the user passes kamping::status_out(), returns a std::optional containing an kamping::MPIResult, which encapsulates a status object. If the probe does not match any message, returns std::nullopt.

The following parameters are optional:

• kamping::tag() probe for messages with this tag. Defaults to probing for an arbitrary tag, i.e. tag(tags::any).
• kamping::source() probe for messages sent from this source rank. Defaults to probing for an arbitrary source, i.e. source(rank::any).
• kamping::status() or kamping::status_out(). Returns info about the probed message by setting the appropriate fields in the status object passed by the user. If kamping::status_out() is passed, constructs a status object which may be retrieved by the user. The status can be ignored by passing kamping::status(kamping::ignore<>). This is the default.

Template Parameters

Args	Automatically deduced template parameters.

Parameters

args	All required and any number of the optional buffers described above.

irecv()

template<template< typename... > typename DefaultContainerType, template< typename, template< typename... > typename > typename... Plugins>

template<typename recv_value_type_tparam , typename... Args>

auto kamping::Communicator< DefaultContainerType, Plugins >::irecv

(

Args...

args

)

const

Wrapper for MPI_Recv.

This wraps MPI_Irecv. This operation performs a standard non-blocking receive. If the kamping::recv_counts() parameter is not specified, this first performs a (blocking) probe, followed by a (non-blocking) receive of the probed message with the probed message size. The call is associated with a kamping::Request (either allocated by KaMPIng or provided by the user). Before accessing the result the user has to complete the request.

The following parameters are optional:

• kamping::recv_buf() the buffer to receive the message into. If no kamping::recv_buf() is provided, the value_type of the recv buffer has to be passed as a template parameter to recv().
• kamping::tag() recv message with this tag. Defaults to receiving for an arbitrary tag, i.e. tag(tags::any).
• kamping::source() receive a message sent from this source rank. Defaults to probing for an arbitrary source, i.e. source(rank::any).
  • kamping::recv_type() specifying the MPI datatype to use as recv type. If omitted, the MPI datatype is derived automatically based on recv_buf's underlying value_type.
• kamping::request() The request object to associate this operation with. Defaults to a library allocated request object, which can be access via the returned result.

The following parameter is optional, but leads to an additional call to MPI_Probe if not present:

• kamping::recv_count() the number of elements to receive. Will be probed before receiving if not given. Keep in mind that this introduces an additional blocking operation call.

Template Parameters

Args	Automatically deduced template parameters.

Parameters

args	All required and any number of the optional parameters described above.

Returns

Result object wrapping the output parameters to be returned by value.

See also

docs/parameter_handling.md for general information about parameter handling in KaMPIng.

---

Note on Resize Policy

The underlying container/storage of an out parameter encapsulating a data buffer (e.g. recv_buf/recv_counts, etc.) will be resized according to the parameter's resize policy:

• kamping::BufferResizePolicy::no_resize: no resizing will occur and the underlying storage must be large enough to hold all elements (default).
• kamping::BufferResizePolicy::grow_only: resizing will only occur if the underlying storage is not large enough to hold all elements.
• kamping::BufferResizePolicy::resize_to_fit: the underlying storage will be resized to exactly the number of elements (e.g. number of received elements for the recv_buf, etc.)

If a send_/recv_/send_recv_type parameter is provided, kamping::BufferResizePolicy::no_resize for receive buffers is required, as KaMPIng can no longer ensure a 1:1 mapping between MPI_Datatype and the underlying storage's C++ type.

isend()

template<template< typename... > typename DefaultContainerType, template< typename, template< typename... > typename > typename... Plugins>

template<typename... Args>

auto kamping::Communicator< DefaultContainerType, Plugins >::isend

(

Args...

args

)

const

Wrapper for MPI_Isend.

This wraps MPI_Isend. This operation sends the elements in the input buffer provided via kamping::send_buf() to the specified receiver rank using standard send mode without blocking. The call is associated with a kamping::Request (either allocated by KaMPIng or provided by the user). Before accessing the result the user has to complete the request.

The following parameters are required:

• kamping::send_buf() containing the data that is sent.
• kamping::destination() the receiving rank.

The following parameters are optional:

• kamping::send_count() specifying how many elements of the buffer are sent. If omitted, the size of the send buffer is used as a default. This parameter is mandatory if kamping::send_type() is given.
  • kamping::send_type() specifying the MPI datatype to use as send type. If omitted, the MPI datatype is derived automatically based on send_buf's underlying value_type.
• kamping::tag() the tag added to the message. Defaults to the communicator's default tag (Communicator::default_tag()) if not present.
• kamping::request() The request object to associate this operation with. Defaults to a library allocated request object, which can be access via the returned result.
• kamping::send_mode() the send mode to use. Defaults to standard MPI_Send.

Template Parameters

Args	Automatically deduced template parameters.

Parameters

args	All required and any number of the optional parameters described above.

Returns

Result object wrapping the output parameters to be returned by value.

See also

docs/parameter_handling.md for general information about parameter handling in KaMPIng.

---

Note on Resize Policy

The underlying container/storage of an out parameter encapsulating a data buffer (e.g. recv_buf/recv_counts, etc.) will be resized according to the parameter's resize policy:

• kamping::BufferResizePolicy::no_resize: no resizing will occur and the underlying storage must be large enough to hold all elements (default).
• kamping::BufferResizePolicy::grow_only: resizing will only occur if the underlying storage is not large enough to hold all elements.
• kamping::BufferResizePolicy::resize_to_fit: the underlying storage will be resized to exactly the number of elements (e.g. number of received elements for the recv_buf, etc.)

If a send_/recv_/send_recv_type parameter is provided, kamping::BufferResizePolicy::no_resize for receive buffers is required, as KaMPIng can no longer ensure a 1:1 mapping between MPI_Datatype and the underlying storage's C++ type.

probe()

template<template< typename... > typename DefaultContainerType, template< typename, template< typename... > typename > typename... Plugins>

template<typename... Args>

auto kamping::Communicator< DefaultContainerType, Plugins >::probe

(

Args...

args

)

const

Wrapper for MPI_Probe.

This wraps MPI_Probe. This operation probes for a message and returns a status object with info about the probe message. The following parameters are optional:

• kamping::source() probe for messages sent from this source rank. Defaults to probing for an arbitrary source, i.e. source(rank::any).
• kamping::tag() probe for messages with this tag. Defaults to probing for an arbitrary tag, i.e. tag(tags::any).
• kamping::status(ignore<>) or kamping::status_out(). Returns info about the probed message by setting the appropriate fields in the status object passed by the user. If kamping::status_out() is passed, constructs a status object which may be retrieved by the user. The status can be ignored by passing kamping::status(kamping::ignore<>). This is the default.

Template Parameters

Args	Automatically deduced template parameters.

Parameters

args	All required and any number of the optional buffers described above.

recv()

template<template< typename... > typename DefaultContainerType, template< typename, template< typename... > typename > typename... Plugins>

template<typename recv_value_type_tparam , typename... Args>

auto kamping::Communicator< DefaultContainerType, Plugins >::recv

(

Args...

args

)

const

Wrapper for MPI_Recv.

This wraps MPI_Recv. This operation performs a standard blocking receive. If the kamping::recv_counts() parameter is not specified, this first performs a probe, followed by a receive of the probed message with the probed message size.

The following parameter is optional, but leads to an additional call to MPI_Probe if not present:

• kamping::recv_count() the number of elements to receive. Will be probed before receiving if not given.

The following parameters are optional:

• kamping::recv_buf() the buffer to receive the message into. The buffer's underlying storage must be large enough to hold all received elements. If no kamping::recv_buf() is provided, the value_type of the recv buffer has to be passed as a template parameter to recv().
  • kamping::recv_type() specifying the MPI datatype to use as recv type. If omitted, the MPI datatype is derived automatically based on recv_buf's underlying value_type.
• kamping::source() receive a message sent from this source rank. Defaults to probing for an arbitrary source, i.e. source(rank::any).
• kamping::tag() recv message with this tag. Defaults to receiving for an arbitrary tag, i.e. tag(tags::any).
• kamping::status(ignore<>) or kamping::status_out(). Returns info about the received message by setting the appropriate fields in the status object passed by the user. If kamping::status_out() is passed, constructs a status object which may be retrieved by the user. The status can be ignored by passing kamping::status(kamping::ignore<>). This is the default.

Template Parameters

Args	Automatically deduced template parameters.

Parameters

args	All required and any number of the optional parameters described above.

Returns

Result object wrapping the output parameters to be returned by value.

See also

docs/parameter_handling.md for general information about parameter handling in KaMPIng.

---

Note on Resize Policy

The underlying container/storage of an out parameter encapsulating a data buffer (e.g. recv_buf/recv_counts, etc.) will be resized according to the parameter's resize policy:

• kamping::BufferResizePolicy::no_resize: no resizing will occur and the underlying storage must be large enough to hold all elements (default).
• kamping::BufferResizePolicy::grow_only: resizing will only occur if the underlying storage is not large enough to hold all elements.
• kamping::BufferResizePolicy::resize_to_fit: the underlying storage will be resized to exactly the number of elements (e.g. number of received elements for the recv_buf, etc.)

If a send_/recv_/send_recv_type parameter is provided, kamping::BufferResizePolicy::no_resize for receive buffers is required, as KaMPIng can no longer ensure a 1:1 mapping between MPI_Datatype and the underlying storage's C++ type.

recv_single()

template<template< typename... > typename DefaultContainerType, template< typename, template< typename... > typename > typename... Plugins>

template<typename recv_value_type_tparam , typename... Args>

auto kamping::Communicator< DefaultContainerType, Plugins >::recv_single

(

Args...

args

)

const

Convience wrapper for receiving single values via MPI_Recv.

This wraps MPI_Recv. This operation performs a standard blocking receive with a receive count of 1 and returns the received value.

The following parameters are optional:

• kamping::source() receive a message sent from this source rank. Defaults to kamping::source(kamping::rank::any).
• kamping::tag() recv message with this tag. Defaults to receiving for an arbitrary tag, i.e. tag(tags::any).
• kamping::status() Returns info about the received message by setting the appropriate fields in the status object passed by the user. The status can be ignored by passing kamping::status(kamping::ignore<>). This is the default.

Template Parameters

recv_value_type_tparam	The type of the message to be received.
Args	Automatically deduced template parameters.

Parameters

args	All required and any number of the optional buffers described above.

Returns

The received value of type recv_value_type_tparam.

send()

template<template< typename... > typename DefaultContainerType, template< typename, template< typename... > typename > typename... Plugins>

template<typename... Args>

void kamping::Communicator< DefaultContainerType, Plugins >::send

(

Args...

args

)

const

Wrapper for MPI_Send.

This wraps MPI_Send. This operation sends the elements in the input buffer provided via kamping::send_buf() to the specified receiver rank using standard send mode. The following parameters are required:

• kamping::send_buf() containing the data that is sent.
• kamping::send_count() specifying how many elements of the buffer are sent. If omitted, the size of the send buffer is used as a default. This parameter is mandatory if kamping::send_type() is given.
  • kamping::send_type() specifying the MPI datatype to use as send type. If omitted, the MPI datatype is derived automatically based on send_buf's underlying value_type.
• kamping::destination() the receiving rank.

The following parameters are optional:

• kamping::tag() the tag added to the message. Defaults to the communicator's default tag (Communicator::default_tag()) if not present.

Template Parameters

Args	Automatically deduced template parameters.

Parameters

args	All required and any number of the optional parameters described above.

See also

docs/parameter_handling.md for general information about parameter handling in KaMPIng.

---

Note on Resize Policy

The underlying container/storage of an out parameter encapsulating a data buffer (e.g. recv_buf/recv_counts, etc.) will be resized according to the parameter's resize policy:

• kamping::BufferResizePolicy::no_resize: no resizing will occur and the underlying storage must be large enough to hold all elements (default).
• kamping::BufferResizePolicy::grow_only: resizing will only occur if the underlying storage is not large enough to hold all elements.
• kamping::BufferResizePolicy::resize_to_fit: the underlying storage will be resized to exactly the number of elements (e.g. number of received elements for the recv_buf, etc.)

If a send_/recv_/send_recv_type parameter is provided, kamping::BufferResizePolicy::no_resize for receive buffers is required, as KaMPIng can no longer ensure a 1:1 mapping between MPI_Datatype and the underlying storage's C++ type.

sendrecv()

template<template< typename... > typename DefaultContainerType, template< typename, template< typename... > typename > typename... Plugins>

template<typename recv_value_type_tparam , typename... Args>

auto kamping::Communicator< DefaultContainerType, Plugins >::sendrecv

(

Args...

args

)

const

Wrapper for MPI_Sendrecv.

This wraps MPI_Sendrecv. This operation performs a blocking send and receive operation. If the kamping::recv_counts() parameter is not specified, this first performs a sendrecv, sending and receiving the recv count.

The following parameters are required:

• kamping::send_buf() containing the data that is sent.
• kamping::destination() the receiving rank.

The following parameter is optional, but leads to an additional call to MPI_Sendrecv if not present:

• kamping::recv_count() the number of elements to receive. Will be calculated using an additional sendrecv if not given. Note that this additional sendrecv can be received by send(). This will lead to unintended behavior, if sendrecv() is used in combination with send() or recv() while omitting the kamping::recv_counts() parameter.

The following parameters are optional:

• kamping::recv_buf() the buffer to receive the message into. The buffer's underlying storage must be large enough to hold all received elements. If no kamping::recv_buf() is provided, the value_type of the recv buffer has to be passed as a template parameter to sendrecv().
• kamping::send_count() specifying how many elements of the buffer are sent. If omitted, the size of the send buffer is used as a default.
• kamping::source() receive a message sent from this source rank. Defaults to probing for an arbitrary source, i.e. source(rank::any).
• kamping::send_tag() send message with this tag. Defaults to the communicator's default tag (Communicator::default_tag()) if not present.
• kamping::recv_tag() receive message with this tag. Defaults to receiving for an arbitrary tag, i.e. tag(tags::any).
• kamping::status(ignore<>) or kamping::status_out(). Returns info about the received message by setting the appropriate fields in the status object passed by the user. If kamping::status_out() is passed, constructs a status object which may be retrieved by the user. The status can be ignored by passing kamping::status(kamping::ignore<>). This is the default.

Template Parameters

Args	Automatically deduced template parameters.
recv_value_type_tparam	The type of the message to be received.

Parameters

args	All required and any number of the optional parameters described above.

Returns

Result object wrapping the output parameters to be returned by value.

See also

docs/parameter_handling.md for general information about parameter handling in KaMPIng.

---

try_recv()

template<template< typename... > typename DefaultContainerType, template< typename, template< typename... > typename > typename... Plugins>

template<typename recv_value_type_tparam , typename... Args>

auto kamping::Communicator< DefaultContainerType, Plugins >::try_recv

(

Args...

args

)

const

Receives a message if one is available.

In contrast to kamping::Communicator::recv(), this method does not block if no message is available. Instead, it will return a empty std::optional. Internally, this first does a matched probe (MPI_Improbe) to check if a message is available. If a message is available, it will be received using a matched receive (MPI_Mrecv).

The following parameters are optional:

• kamping::recv_buf() the buffer to receive the message into. The buffer's underlying storage must be large enough to hold all received elements. If no kamping::recv_buf() is provided, the value_type of the recv buffer has to be passed as a template parameter to recv().
• kamping::tag() receive message with the given tag. Defaults to receiving for an arbitrary tag, i.e. tag(tags::any).
• kamping::source() receive a message sent from the given source rank. Defaults to probing for an arbitrary source, i.e. source(rank::any).
• kamping::status(). Returns info about the received message by setting the appropriate fields in the status object. The status can be obtained by using kamping::status_out and ignored by passing kamping::ignore<>. This is the default.
• kamping::recv_type() specifying the MPI datatype to use as the recv type. If omitted, the MPI datatype is derived automatically based on recv_buf's underlying value_type.

Template Parameters

recv_value_type_tparam	The type that is received. Only required when no kamping::recv_buf() is given.
Args	Automatically deduced template parameters.

Parameters

args	All required and any number of the optional buffers described above.

Returns

If no message is available return std::nullopt, else return a std::optional wrapping an kamping::MPIResult. If the result object is empty, i.e. there are no owning out parameters passed to try_recv (see docs/parameter_handling.md), returns a bool indicating success instead of an std::optional.

See also

docs/parameter_handling.md for general information about parameter handling in KaMPIng.

---

Note on Resize Policy

The underlying container/storage of an out parameter encapsulating a data buffer (e.g. recv_buf/recv_counts, etc.) will be resized according to the parameter's resize policy:

• kamping::BufferResizePolicy::no_resize: no resizing will occur and the underlying storage must be large enough to hold all elements (default).
• kamping::BufferResizePolicy::grow_only: resizing will only occur if the underlying storage is not large enough to hold all elements.
• kamping::BufferResizePolicy::resize_to_fit: the underlying storage will be resized to exactly the number of elements (e.g. number of received elements for the recv_buf, etc.)

If a send_/recv_/send_recv_type parameter is provided, kamping::BufferResizePolicy::no_resize for receive buffers is required, as KaMPIng can no longer ensure a 1:1 mapping between MPI_Datatype and the underlying storage's C++ type.