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
template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::irecv (Args... args) const
template<typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::isend (Args... args) const
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
template<typename recv_value_type_tparam = kamping::internal::unused_tparam, typename... Args>
auto	kamping::Communicator< DefaultContainerType, Plugins >::recv (Args... args) const
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
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 >::try_recv (Args... args) const

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

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

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). 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

This wraps \c MPI_Isend. This operation sends the elements in the input buffer provided via \c
kamping::send_buf() to the specified receiver rank using standard send mode without blocking. The call is associated
with a \ref 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:
- \ref kamping::send_buf() containing the data that is sent.

- \ref kamping::destination() the receiving rank.

The following parameters are optional:
- \ref 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 \ref
kamping::send_type() is given.

 - \ref kamping::send_type() specifying the \c MPI datatype to use as send type. If omitted, the \c MPI datatype is
derived automatically based on send_buf's underlying \c value_type.

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

- \ref 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.

- \ref kamping::send_mode() the send mode to use. Defaults to standard MPI_Send.

@tparam Args Automatically deduced template parameters.
@param args All required and any number of the optional parameters described above.
@return Result object wrapping the output parameters to be returned by value.

@see \ref docs/parameter_handling.md for general information about parameter handling in KaMPIng.
<hr>
 
\ifile "/github/workspace/docs/resize_policy.dox" \iline 1 
 #### 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

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

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(). 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

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

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

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

The following parameters are optional:
- \ref 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 \ref kamping::recv_buf() is provided, the \c value_type of the recv
buffer has to be passed as a template parameter to \c recv().

- \ref kamping::tag() receive message with the given tag. Defaults to receiving for an arbitrary tag, i.e. \c
tag(tags::any).

- \ref kamping::source() receive a message sent from the given source rank. Defaults to probing for an arbitrary
source, i.e. \c source(rank::any).

- \ref kamping::status(). Returns info about the received message by setting the
appropriate fields in the status object. The status can be obtained by using \c kamping::status_out and ignored by
passing \c kamping::ignore<>. This is the default.

- \ref kamping::recv_type() specifying the \c MPI datatype to use as the recv type. If omitted, the \c MPI datatype
is derived automatically based on `recv_buf`'s underlying \c value_type.

@tparam recv_value_type_tparam The type that is received. Only required when no \ref kamping::recv_buf() is given.
@tparam Args Automatically deduced template parameters.
@param args All required and any number of the optional buffers described above.
@return If no message is available return \c std::nullopt, else return a \c std::optional wrapping an \ref
kamping::MPIResult. If the result object is empty, i.e. there are no owning out parameters passed to `try_recv` (see
\ref docs/parameter_handling.md), returns a \c bool indicating success instead of an \c std::optional.

@see \ref docs/parameter_handling.md for general information about parameter handling in KaMPIng.
<hr>
 
\ifile "/github/workspace/docs/resize_policy.dox" \iline 1 
 #### 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.