Point-to-point communication¶

All operations take the communicator last. Arguments with an obvious default can be left out in front of it: the tag (0 for sends, any tag for receives) and the source of a receive (any source). See Calling conventions.

Blocking operations return the buffers they were given: owned buffers (passed as rvalues) by value, borrowed buffers (lvalues) by reference. Non-blocking operations return an iresult that hands the buffers back on completion; see Results and non-blocking operations.

Sending¶

template<is_send_mode SendMode, send_buffer SBuf, rank Dest, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm> SBuf send(SendMode&&, SBuf &&sbuf, Dest dest, Tag tag, Comm const &comm)¶ (1)

template<is_send_mode SendMode, send_buffer SBuf, rank Dest, convertible_to_mpi_handle<MPI_Comm> Comm> SBuf send(SendMode &&mode, SBuf &&sbuf, Dest dest, Comm const &comm)¶ (2)

template<send_buffer SBuf, rank Dest, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm> SBuf send(SBuf &&sbuf, Dest dest, Tag tag, Comm const &comm)¶ (3)

template<send_buffer SBuf, rank Dest, convertible_to_mpi_handle<MPI_Comm> Comm> SBuf send(SBuf &&sbuf, Dest dest, Comm const &comm)¶ (4)

(1) Sends sbuf to dest with tag in the given send_mode (MPI_Send, MPI_Bsend, MPI_Ssend or MPI_Rsend).

(2) Sends sbuf to dest with DEFAULT_SEND_TAG in the given send_mode.

(3) Sends sbuf to dest with tag in standard mode (MPI_Send).

(4) Sends sbuf to dest with DEFAULT_SEND_TAG in standard mode (MPI_Send).

Returns:: The send buffer (owned if passed as rvalue, borrowed otherwise).

Defined in header <kamping/v2/p2p/send.hpp>

The send mode is selected with a tag as first argument, e.g. v2::send(v2::send_mode::sync, buf, dest, comm):

standard_t standard¶

Standard mode (MPI_Send).

Defined in header <kamping/v2/p2p/send_mode.hpp>

buffered_t buffered¶

Buffered mode (MPI_Bsend).

Defined in header <kamping/v2/p2p/send_mode.hpp>

sync_t sync¶

Synchronous mode (MPI_Ssend).

Defined in header <kamping/v2/p2p/send_mode.hpp>

ready_t ready¶

Ready mode (MPI_Rsend).

Defined in header <kamping/v2/p2p/send_mode.hpp>

int DEFAULT_SEND_TAG¶

The tag used by point-to-point operations that are called without an explicit tag.

Defined in header <kamping/v2/p2p/constants.hpp>

Receiving¶

template<recv_buffer RBuf, rank Source, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> RBuf recv(RBuf &&rbuf, Source source, Tag tag, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (1)

template<recv_buffer RBuf, rank Source, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> RBuf recv(RBuf &&rbuf, Source source, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (2)

template<recv_buffer RBuf, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> RBuf recv(RBuf &&rbuf, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (3)

(1) Receives a message from source with tag into rbuf (MPI_Recv).

If rbuf is a deferred receive buffer (e.g. views::resize or auto_recv<T>()), the message is matched with MPI_Mprobe first and rbuf is resized to fit, then received with MPI_Mrecv.

(2) Receives a message from source with any tag into rbuf; see the overload above.

(3) Receives a message from any source with any tag into rbuf; see the overload above.

Parameters:

status – Optional: filled with the status of the received message. Defaults to MPI_STATUS_IGNORE.

Returns:: The receive buffer (owned if passed as rvalue, borrowed otherwise).

Defined in header <kamping/v2/p2p/recv.hpp>

Sending and receiving at once¶

template<send_buffer SBuf, recv_buffer RBuf, rank Dest, rank Source, tag SendTag, tag RecvTag, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> result<SBuf, RBuf> sendrecv(SBuf &&sbuf, Dest dest, SendTag send_tag, RBuf &&rbuf, Source source, RecvTag recv_tag, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (1)

template<send_buffer SBuf, recv_buffer RBuf, rank Dest, rank Source, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> result<SBuf, RBuf> sendrecv(SBuf &&sbuf, Dest dest, RBuf &&rbuf, Source source, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (2)

template<send_buffer SBuf, recv_buffer RBuf, rank Dest, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> result<SBuf, RBuf> sendrecv(SBuf &&sbuf, Dest dest, RBuf &&rbuf, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (3)

(1) Sends sbuf to dest with send_tag and receives into rbuf from source with recv_tag in one call (MPI_Sendrecv).

If rbuf is a deferred receive buffer (e.g. views::resize), the counts are exchanged first and rbuf is resized.

(2) Like the overload above, sending with DEFAULT_SEND_TAG and receiving with any tag.

(3) Like the overload above, receiving from any source.

Parameters:

status – Optional: filled with the status of the received message. Defaults to MPI_STATUS_IGNORE.

Returns:: The send and receive buffer (owned if passed as rvalue, borrowed otherwise).

Defined in header <kamping/v2/p2p/sendrecv.hpp>

With one buffer for both directions:

template<send_recv_buffer SRBuf, rank Dest, rank Source, tag SendTag, tag RecvTag, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> SRBuf sendrecv_replace(SRBuf &&send_recv_buf, Dest dest, SendTag send_tag, Source source, RecvTag recv_tag, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (1)

template<send_recv_buffer SRBuf, rank Dest, rank Source, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> SRBuf sendrecv_replace(SRBuf &&send_recv_buf, Dest dest, Source source, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (2)

template<send_recv_buffer SRBuf, rank Dest, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> SRBuf sendrecv_replace(SRBuf &&send_recv_buf, Dest dest, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (3)

(1) Sends the contents of send_recv_buf to dest with send_tag and replaces them with a message received from source with recv_tag, in one call (MPI_Sendrecv_replace).

The same buffer, count and datatype are used for both directions: count(send_recv_buf) elements are sent, and the received message must not be longer. The default infer() therefore rejects deferred receive buffers such as views::resize; use sendrecv with a separate receive buffer for messages of unknown size.

(2) Like the overload above, sending with DEFAULT_SEND_TAG and receiving with any tag.

(3) Like the overload above, receiving from any source.

Parameters:

status – Optional: filled with the status of the received message. Defaults to MPI_STATUS_IGNORE.

Returns:: The buffer (owned if passed as rvalue, borrowed otherwise).

Defined in header <kamping/v2/p2p/sendrecv_replace.hpp>

Probing¶

template<rank Source, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> void probe(Source source, Tag tag, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (1)

template<rank Source, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> void probe(Source source, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (2)

template<convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> void probe(Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (3)

(1) Blocks until a message matching source and tag is available, without receiving it (MPI_Probe).

(2) Like the overload above, probing for any tag.

(3) Like the overload above, probing for any source and any tag.

Parameters:

status – Optional: filled with the status of the message. Defaults to MPI_STATUS_IGNORE.

Defined in header <kamping/v2/p2p/probe.hpp>

template<rank Source, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> bool iprobe(Source source, Tag tag, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (1)

template<rank Source, convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> bool iprobe(Source source, Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (2)

template<convertible_to_mpi_handle<MPI_Comm> Comm, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> bool iprobe(Comm const &comm, Status &&status = MPI_STATUS_IGNORE)¶ (3)

(1) Checks whether a message matching source and tag is available, without blocking or receiving it (MPI_Iprobe).

(2) Like the overload above, probing for any tag.

(3) Like the overload above, probing for any source and any tag.

Parameters:

status – Optional: filled with the status of the message if one is available. Defaults to MPI_STATUS_IGNORE.

Returns:: true if a matching message is available.

Defined in header <kamping/v2/p2p/probe.hpp>

class probe_result¶

Result of a matched probe: the matched message together with its status.

Provides the status accessors (source(), tag(), count()) directly and satisfies convertible_to_mpi_handle_ptr<MPI_Message>, so it can be passed to mrecv() / imrecv() to receive the message. Move-only: it terminates the program if destroyed while the matched message has not been received or released.

Defined in header <kamping/v2/p2p/probe.hpp>

const_status_view status() const¶ (1)

status_view status()¶ (2)

Returns:

(1) A read-only view of the status of the matched message.
(2) A view of the status of the matched message.

MPI_Message release() noexcept¶: Gives up responsibility for the matched message and returns it; the caller must then receive it.

int source() const¶

Returns:: The source rank.

int tag() const¶

Returns:: The tag.

std::optional<int> count(MPI_Datatype datatype) const¶ (1)

template<typename T> requires kamping::types::is_builtin_type_v<T> std::optional<int> count() const¶ (2)

Template parameters:

T – A builtin MPI-mappable type.

Parameters:

datatype – The MPI datatype.

Returns:

(1) The number of top-level elements of the given datatype in the message. In cases where MPI_Get_count would return MPI_UNDEFINED, std::nullopt is returned.
(2) The number of top-level elements of type T in the message. In cases where MPI_Get_count would return MPI_UNDEFINED, std::nullopt is returned.

Matched probe and receive¶

template<rank Source, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm> probe_result mprobe(Source source, Tag tag, Comm const &comm)¶ (1)

template<rank Source, convertible_to_mpi_handle<MPI_Comm> Comm> probe_result mprobe(Source source, Comm const &comm)¶ (2)

template<convertible_to_mpi_handle<MPI_Comm> Comm> probe_result mprobe(Comm const &comm)¶ (3)

(1) Blocks until a message matching source and tag arrives and matches it (MPI_Mprobe).

The message is removed from the matching queue and must be received through the returned probe_result.

(2) Like the overload above, matching a message with any tag.

(3) Like the overload above, matching a message from any source with any tag.

Returns:: The matched message and its status.

Defined in header <kamping/v2/p2p/probe.hpp>

template<rank Source, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm> std::optional<probe_result> improbe(Source source, Tag tag, Comm const &comm)¶ (1)

template<rank Source, convertible_to_mpi_handle<MPI_Comm> Comm> std::optional<probe_result> improbe(Source source, Comm const &comm)¶ (2)

template<convertible_to_mpi_handle<MPI_Comm> Comm> std::optional<probe_result> improbe(Comm const &comm)¶ (3)

(1) Matches a message matching source and tag if one is available, without blocking (MPI_Improbe).

A matched message is removed from the matching queue and must be received through the returned probe_result.

(2) Like the overload above, matching a message with any tag.

(3) Like the overload above, matching a message from any source with any tag.

Returns:: The matched message and its status, or std::nullopt if no matching message is available.

Defined in header <kamping/v2/p2p/probe.hpp>

template<recv_buffer RBuf, convertible_to_mpi_handle_ptr<MPI_Status> Status = MPI_Status*> RBuf mrecv(RBuf &&rbuf, probe_result probe, Status &&status = MPI_STATUS_IGNORE)¶

Receives the message matched by probe into rbuf (MPI_Mrecv).

Calls the infer(comm_op::mrecv, ...) customization point first; the default overload sizes a deferred recv buffer (e.g. views::resize) from the probed count, so no further probing is needed. Takes probe by value, so the caller must hand it over with std::move — the message can be received only once.

Parameters:

status – Optional: filled with the status of the receive. Defaults to MPI_STATUS_IGNORE.

Returns:: The buffer (ownership semantics match blocking recv).

Defined in header <kamping/v2/p2p/mrecv.hpp>

template<recv_buffer RBuf, convertible_to_mpi_handle_ptr<MPI_Request> Request> RBuf imrecv(Request &&request, RBuf &&rbuf, probe_result probe)¶ (1)

template<recv_buffer RBuf> iresult<RBuf> imrecv(RBuf &&rbuf, probe_result probe)¶ (2)

(1) Starts a non-blocking receive of the message matched by probe into rbuf, using a caller-supplied request (MPI_Imrecv).

Like mrecv, sizes a deferred recv buffer from the probed count before the receive is started. The message is consumed immediately, so probe need not outlive the request; the caller must keep rbuf alive and complete request.

(2) Starts a non-blocking receive of the message matched by probe into rbuf (MPI_Imrecv).

Like mrecv, sizes a deferred recv buffer from the probed count before the receive is started. The message is consumed immediately, so probe need not outlive the returned iresult, which owns the request and keeps the buffer alive until completion.

Returns:

(1) The buffer (ownership semantics match blocking recv).
(2) An iresult to wait on or test for the received buffer.

Defined in header <kamping/v2/p2p/mrecv.hpp>

Non-blocking operations¶

template<is_send_mode SendMode, convertible_to_mpi_handle_ptr<MPI_Request> Request, send_buffer SBuf, rank Dest, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm> SBuf isend(SendMode&&, Request &&request, SBuf &&sbuf, Dest dest, Tag tag, Comm const &comm)¶ (1)

template<is_send_mode SendMode, convertible_to_mpi_handle_ptr<MPI_Request> Request, send_buffer SBuf, rank Dest, convertible_to_mpi_handle<MPI_Comm> Comm> SBuf isend(SendMode &&mode, Request &&request, SBuf &&sbuf, Dest dest, Comm const &comm)¶ (2)

template<is_send_mode SendMode, send_buffer SBuf, rank Dest, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm> iresult<SBuf> isend(SendMode &&mode, SBuf &&sbuf, Dest dest, Tag tag, Comm const &comm)¶ (3)

template<is_send_mode SendMode, send_buffer SBuf, rank Dest, convertible_to_mpi_handle<MPI_Comm> Comm> iresult<SBuf> isend(SendMode &&mode, SBuf &&sbuf, Dest dest, Comm const &comm)¶ (4)

template<convertible_to_mpi_handle_ptr<MPI_Request> Request, send_buffer SBuf, rank Dest, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm> SBuf isend(Request &&request, SBuf &&sbuf, Dest dest, Tag tag, Comm const &comm)¶ (5)

template<convertible_to_mpi_handle_ptr<MPI_Request> Request, send_buffer SBuf, rank Dest, convertible_to_mpi_handle<MPI_Comm> Comm> SBuf isend(Request &&request, SBuf &&sbuf, Dest dest, Comm const &comm)¶ (6)

template<send_buffer SBuf, rank Dest, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm> iresult<SBuf> isend(SBuf &&sbuf, Dest dest, Tag tag, Comm const &comm)¶ (7)

template<send_buffer SBuf, rank Dest, convertible_to_mpi_handle<MPI_Comm> Comm> iresult<SBuf> isend(SBuf &&sbuf, Dest dest, Comm const &comm)¶ (8)

(1) Starts sending sbuf to dest with tag in the given send_mode, using the caller-supplied request (MPI_Isend, MPI_Ibsend, MPI_Issend or MPI_Irsend). The caller must keep sbuf alive and complete request.

(2) Like the overload above, with DEFAULT_SEND_TAG.

(3) Starts sending sbuf to dest with tag in the given send_mode.

(4) Like the overload above, with DEFAULT_SEND_TAG.

(5) Starts sending sbuf to dest with tag in standard mode, using the caller-supplied request (MPI_Isend).

(6) Like the overload above, with DEFAULT_SEND_TAG.

(7) Starts sending sbuf to dest with tag in standard mode (MPI_Isend).

(8) Like the overload above, with DEFAULT_SEND_TAG.

Returns:

(1, 5) The send buffer (owned if passed as rvalue, borrowed otherwise).
(3, 7) An iresult owning the request (and the buffer, if passed as rvalue); complete it with wait() or test().

Defined in header <kamping/v2/p2p/isend.hpp>

template<convertible_to_mpi_handle_ptr<MPI_Request> Request, recv_buffer RBuf, rank Source, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm> RBuf irecv(Request &&request, RBuf &&rbuf, Source source, Tag tag, Comm const &comm)¶ (1)

template<convertible_to_mpi_handle_ptr<MPI_Request> Request, recv_buffer RBuf, rank Source, convertible_to_mpi_handle<MPI_Comm> Comm> RBuf irecv(Request &&request, RBuf &&rbuf, Source source, Comm const &comm)¶ (2)

template<convertible_to_mpi_handle_ptr<MPI_Request> Request, recv_buffer RBuf, convertible_to_mpi_handle<MPI_Comm> Comm> RBuf irecv(Request &&request, RBuf &&rbuf, Comm const &comm)¶ (3)

template<recv_buffer RBuf, rank Source, tag Tag, convertible_to_mpi_handle<MPI_Comm> Comm> iresult<RBuf> irecv(RBuf &&rbuf, Source source, Tag tag, Comm const &comm)¶ (4)

template<recv_buffer RBuf, rank Source, convertible_to_mpi_handle<MPI_Comm> Comm> iresult<RBuf> irecv(RBuf &&rbuf, Source source, Comm const &comm)¶ (5)

template<recv_buffer RBuf, convertible_to_mpi_handle<MPI_Comm> Comm> iresult<RBuf> irecv(RBuf &&rbuf, Comm const &comm)¶ (6)

(1) Starts receiving a message from source with tag into rbuf, using the caller-supplied request (MPI_Irecv, or MPI_Imrecv for a deferred buffer). The caller must keep rbuf alive and complete request.

(2) Like the overload above, receiving with any tag.

(3) Like the overload above, receiving from any source with any tag.

(4) Starts receiving a message from source with tag into rbuf (MPI_Irecv, or MPI_Imrecv for a deferred buffer).

(5) Like the overload above, receiving with any tag.

(6) Like the overload above, receiving from any source with any tag.

Returns:

(1) The receive buffer (owned if passed as rvalue, borrowed otherwise).
(4) An iresult owning the request (and the buffer, if passed as rvalue); complete it with wait() or test().

Defined in header <kamping/v2/p2p/irecv.hpp>

template<convertible_to_mpi_handle_ptr<MPI_Request> Request, send_buffer SBuf, recv_buffer RBuf, rank Dest, rank Source, tag SendTag, tag RecvTag, convertible_to_mpi_handle<MPI_Comm> Comm> result<SBuf, RBuf> isendrecv(Request &&request, SBuf &&sbuf, Dest dest, SendTag send_tag, RBuf &&rbuf, Source source, RecvTag recv_tag, Comm const &comm)¶ (1)

template<convertible_to_mpi_handle_ptr<MPI_Request> Request, send_buffer SBuf, recv_buffer RBuf, rank Dest, rank Source, convertible_to_mpi_handle<MPI_Comm> Comm> result<SBuf, RBuf> isendrecv(Request &&request, SBuf &&sbuf, Dest dest, RBuf &&rbuf, Source source, Comm const &comm)¶ (2)

template<convertible_to_mpi_handle_ptr<MPI_Request> Request, send_buffer SBuf, recv_buffer RBuf, rank Dest, convertible_to_mpi_handle<MPI_Comm> Comm> result<SBuf, RBuf> isendrecv(Request &&request, SBuf &&sbuf, Dest dest, RBuf &&rbuf, Comm const &comm)¶ (3)

template<send_buffer SBuf, recv_buffer RBuf, rank Dest, rank Source, tag SendTag, tag RecvTag, convertible_to_mpi_handle<MPI_Comm> Comm> iresult<SBuf, RBuf> isendrecv(SBuf &&sbuf, Dest dest, SendTag send_tag, RBuf &&rbuf, Source source, RecvTag recv_tag, Comm const &comm)¶ (4)

template<send_buffer SBuf, recv_buffer RBuf, rank Dest, rank Source, convertible_to_mpi_handle<MPI_Comm> Comm> iresult<SBuf, RBuf> isendrecv(SBuf &&sbuf, Dest dest, RBuf &&rbuf, Source source, Comm const &comm)¶ (5)

template<send_buffer SBuf, recv_buffer RBuf, rank Dest, convertible_to_mpi_handle<MPI_Comm> Comm> iresult<SBuf, RBuf> isendrecv(SBuf &&sbuf, Dest dest, RBuf &&rbuf, Comm const &comm)¶ (6)

(1) Starts sending sbuf to dest with send_tag and receiving into rbuf from source with recv_tag, using the caller-supplied request (MPI_Isendrecv). The caller must keep both buffers alive and complete request.

(2) Like the overload above, sending with DEFAULT_SEND_TAG and receiving with any tag.

(3) Like the overload above, receiving from any source.

(4) Starts sending sbuf to dest with send_tag and receiving into rbuf from source with recv_tag (MPI_Isendrecv).

(5) Like the overload above, sending with DEFAULT_SEND_TAG and receiving with any tag.

(6) Like the overload above, receiving from any source.

Returns:

(1) The send and receive buffer (owned if passed as rvalue, borrowed otherwise).
(4) An iresult owning the request (and the buffers passed as rvalue); complete it with wait() or test().

Defined in header <kamping/v2/p2p/isendrecv.hpp>