AP_recv

Receive a message

Synopsis

#include "autopack.h"

int AP_recv(int sender, int tag, int flags,
            void **ret_msg, int *ret_size, int *ret_sender, int *ret_tag)

SUBROUTINE AP_RECV(sender, tag, flags, ret_msg, ret_size, ret_sender, ret_tag, return_value)
INTEGER sender, tag, flags, ret_msg, ret_size, ret_sender, ret_tag, return_value
INCLUDE 'autopack.fh'

Parameters

sender
specifies rank of the message source (may be MPI_ANY_SOURCE)
tag
specifies tag of the message (may be MPI_ANY_TAG)
flags
flags to specify options (see below)

ret_msg
the received message (or in Fortran, a descriptor)
ret_size
size of the received message
ret_sender
sender of the received message
ret_tag
tag of the received message

Return Value

Returns nonzero if a message has been successfully received, otherwise returns 0. If a message has been received, the arguments ret_msg, ret_size, ret_sender, and ret_tag pass back information about the message.

In the Fortran binding, it is not possible to return a pointer to the message in ret_msg. Instead, a descriptor is returned that may be passed to AP_COPY_FREE() to retrieve the message.

Description

Receive a message with given sender and tag (MPI_ANY_SOURCE and MPI_ANY_TAG may be used). If such a message is available, returns nonzero and sets *ret_msg, *ret_size, *ret_sender, and *ret_tag. If no message matching the criteria is found, returns zero.

Any of ret_size, ret_sender, and ret_tag may be passed NULL if the caller is not interested in the return information.

After the caller has processed the information in ret_msg, the function AP_free() must be called to free the buffer space. Failure to do this will result in a memory leak.

Flags may be a bitwise OR of the following (in Fortran, use addition):

AP_NOFLAGS
Default

AP_BLOCKING

Block until a matching message is received (by default, do not block). Will always return 1 unless AP_DROPOUT is specified.

AP_DROPOUT

Used in conjunction with AP_BLOCKING. If some change in status occurs (e.g. an asynchronous reduction message is received) before a message is available, then unblock and return 0.

AP_FIFO

When searching for messages, only look at first incoming message from each source. Default action is to search all incoming messages from a source (then continuing to the next source if MPI_ANY_SOURCE was specified).

If there are deferred sends, the library will try to process them before each attempt to receive a new message from MPI. This is the case whether the call to AP_recv() is blocking or non-blocking,

Efficiency notes

The library will be most efficient when messages are received in the same order they arrive. If all the messages have the same tag, this is not a concern. However, if the incoming messages have a variety of tags, MPI_ANY_TAG will always match the first one and is the most efficient. If a particular tag is specified, use AP_FIFO if the circumstances permit.

The library will be more efficient when a particular source is specified rather than MPI_ANY_SOURCE. If MPI_ANY_SOURCE is specified, sources will be checked in round-robin fashion starting with the rank from which the last message was received. The search is depth-first (although AP_FIFO may truncate the search).