17.2.290. MPI_Recv

MPI_Recv — 执行标准模式的阻塞接收操作。

17.2.290.1. 语法

17.2.290.1.1. C语法

#include <mpi.h>

int MPI_Recv(void *buf, int count, MPI_Datatype datatype,
     int source, int tag, MPI_Comm comm, MPI_Status *status)

17.2.290.1.2. Fortran语法

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_RECV(BUF, COUNT, DATATYPE, SOURCE, TAG, COMM, STATUS, IERROR)
     <type>  BUF(*)
     INTEGER COUNT, DATATYPE, SOURCE, TAG, COMM
     INTEGER STATUS(MPI_STATUS_SIZE), IERROR

17.2.290.1.3. Fortran 2008 语法

USE mpi_f08
MPI_Recv(buf, count, datatype, source, tag, comm, status, ierror)
     TYPE(*), DIMENSION(..) :: buf
     INTEGER, INTENT(IN) :: count, source, tag
     TYPE(MPI_Datatype), INTENT(IN) :: datatype
     TYPE(MPI_Comm), INTENT(IN) :: comm
     TYPE(MPI_Status) :: status
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

17.2.290.2. 输入参数

• count: 最大接收元素数量（整数）。

• datatype: 每个接收缓冲区条目的数据类型（句柄）。

• source: 源进程的排名（整数）。

• tag: 消息标签（整数）。

• comm: 通信器（句柄）。

17.2.290.3. 输出参数

• buf: 接收缓冲区的初始地址（可选）。

• status: 状态对象(status)。

• ierror: 仅限Fortran：错误状态（整数）。

17.2.290.4. 描述

这个基本的接收操作MPI_Recv是阻塞式的：只有在接收缓冲区包含新接收的消息后才会返回。接收操作可以在匹配的发送操作完成之前就完成（当然，它只能在匹配的发送操作开始后才能完成）。

此调用的阻塞语义在MPI标准的"通信模式"章节中有详细说明。

接收缓冲区包含由count值定义数量的连续元素。这组元素中的第一个元素位于address_buf地址处。每个元素的类型由datatype指定。

接收到的消息长度必须小于或等于接收缓冲区的长度。当发生溢出情况时，将返回MPI_ERR_TRUNCATE错误。

如果接收到的消息长度小于接收缓冲区的长度，则只有与（较短的）接收消息对应的位置会被修改。

17.2.290.5. 注意事项

count参数表示一条消息中可接收的datatype类型条目的最大数量。接收消息后，使用MPI_Get_count函数来确定该消息中的实际条目数量。

要接收长度未知的消息，请使用MPI_Probe函数。有关MPI_Probe和MPI_Cancel的更多信息，请参阅它们各自的手册页以及MPI标准中的"探测与取消"章节。

只有当消息的目标地址是接收进程，并且其来源(source)、标签(tag)和通信器(comm)值与接收操作指定的来源、标签和通信器值匹配时，该消息才能被接收操作接收。接收操作可以为来源和/或标签指定通配符值，表示接受任何来源和/或标签。来源的通配符值为 source = MPI_ANY_SOURCE。标签的通配符值为 tag = MPI_ANY_TAG。通信器没有通配符值。这些通配符的范围仅限于指定通信器组中的进程。

消息标签由接收操作的tag参数指定。

参数source（如果不同于MPI_ANY_SOURCE）需指定为与该通信器相关联的进程组内的一个秩（对于跨通信器而言则是远程进程组）。因此，source参数的有效值范围为{0,…,n-1}或{MPI_ANY_SOURCE}，其中n表示该组中的进程数量。

注意发送和接收操作之间的不对称性：接收操作可以接受来自任意发送方的消息；另一方面，发送操作必须指定唯一的接收方。这符合"推送"通信机制，其中数据传输由发送方实现（而不是"拉取"机制，其中数据传输由接收方实现）。

允许源地址与目标地址相同，即进程可以向自身发送消息。然而，不建议进程使用上述描述的阻塞式发送和接收操作向自身发送消息，因为这可能导致死锁。更多详情请参阅MPI标准中的"点对点通信语义"章节。

如果您的应用程序不需要检查status字段，可以通过使用预定义常量MPI_STATUS_IGNORE作为status参数的特殊值来节省资源。

17.2.290.6. 错误

几乎所有MPI例程都会返回一个错误值；C语言例程通过函数返回值返回，Fortran例程则通过最后一个参数返回。

在返回错误值之前，会调用与通信对象（如通信器、窗口、文件）关联的当前MPI错误处理程序。如果MPI调用未关联任何通信对象，则该调用被视为附加到MPI_COMM_SELF，并将调用关联的MPI错误处理程序。当MPI_COMM_SELF未初始化时（即在MPI_Init/MPI_Init_thread之前、MPI_Finalize之后，或仅使用会话模型时），错误会触发初始错误处理程序。初始错误处理程序可通过在使用世界模型时调用MPI_Comm_set_errhandler来修改MPI_COMM_SELF，或通过mpiexec的mpi_initial_errhandler命令行参数，或MPI_Comm_spawn/MPI_Comm_spawn_multiple的info键来设置。如果未设置其他适当的错误处理程序，则MPI I/O函数将调用MPI_ERRORS_RETURN错误处理程序，而其他所有MPI函数将调用MPI_ERRORS_ABORT错误处理程序。

Open MPI 包含三个可使用的预定义错误处理器：

• MPI_ERRORS_ARE_FATAL 导致程序中止所有连接的MPI进程。

• MPI_ERRORS_ABORT 一个可在通信器、窗口、文件或会话上调用的错误处理程序。当在通信器上调用时，其行为类似于在该通信器上调用MPI_Abort。如果在窗口或文件上调用，则行为类似于在包含对应窗口或文件中进程组的通信器上调用MPI_Abort。如果在会话上调用，则仅中止本地进程。

• MPI_ERRORS_RETURN 向应用程序返回一个错误代码。

MPI应用程序也可以通过调用以下方式实现自己的错误处理程序：

• MPI_Comm_create_errhandler 然后 MPI_Comm_set_errhandler

• MPI_File_create_errhandler 然后 MPI_File_set_errhandler

• MPI_Session_create_errhandler 然后 MPI_Session_set_errhandler 或在 MPI_Session_init

• MPI_Win_create_errhandler 然后 MPI_Win_set_errhandler

请注意，MPI不保证MPI程序在出现错误后能够继续运行。

查看MPI手册页获取完整的MPI错误代码列表。

有关更多信息，请参阅MPI-3.1标准中的错误处理部分。

请注意，根据MPI标准中"点对点通信"章节的"返回状态"部分，通过MPI_Recv接收消息时发生的MPI错误不会在返回的状态中设置status.MPI_ERROR字段。错误代码总是会传递给后端错误处理程序，如果后端错误处理程序返回该错误，则可能通过MPI_Recv的返回值传回给调用者。预定义的MPI错误处理程序MPI_ERRORS_RETURN就体现了这种行为。

另请参阅

• MPI_Irecv

• MPI_Probe