17.2.302. MPI_Request_free

MPI_Request_free — 释放通信请求对象。

17.2.302.1. 语法

17.2.302.1.1. C语法

#include <mpi.h>

int MPI_Request_free(MPI_Request *request)

17.2.302.1.2. Fortran 语法

USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_REQUEST_FREE(REQUEST, IERROR)
     INTEGER REQUEST, IERROR

17.2.302.1.3. Fortran 2008 语法

USE mpi_f08
MPI_Request_free(request, ierror)
     TYPE(MPI_Request), INTENT(INOUT) :: request
     INTEGER, OPTIONAL, INTENT(OUT) :: ierror

17.2.302.2. 输入/输出参数

  • request: 通信请求（句柄）。

17.2.302.3. 描述

此操作允许在不等待关联通信完成的情况下释放请求对象。

MPI_Request_free 将请求对象标记为待释放状态，并将请求设置为MPI_REQUEST_NULL。任何与该请求关联的正在进行中的通信将被允许完成。该请求只会在完成后才会被释放。

17.2.302.4. 注意事项

当通过调用MPI_Request_free释放请求后，就无法再通过MPI_Wait或MPI_Test调用来检查相关通信是否成功完成。此外，如果通信过程中后续发生错误，错误代码将无法返回给用户——此类错误必须被视为致命错误。

这就引出了一个问题：在使用MPI_Request_free时，如何知道操作何时完成？根据程序逻辑，可能存在其他方式让程序知道某些操作已完成，这使得MPI_Request_free的使用具有实际意义。例如，当程序逻辑表明接收方已发送对发送消息的回复时，可以释放活动发送请求——回复的到达告知发送方发送已完成，发送缓冲区可以重新使用。而活动接收请求永远不应被释放，因为接收方将无法验证接收是否已完成以及接收缓冲区是否可以重新使用。

示例：

CALL MPI_COMM_RANK(MPI_COMM_WORLD, rank)
IF(rank == 0) THEN
    DO i=1, n
      CALL MPI_ISEND(outval, 1, MPI_REAL, 1, 0, req, ierr)
      CALL MPI_REQUEST_FREE(req, ierr)
      CALL MPI_IRECV(inval, 1, MPI_REAL, 1, 0, req, ierr)
      CALL MPI_WAIT(req, status, ierr)
    END DO
ELSE IF (rank == 1) THEN
    CALL MPI_IRECV(inval, 1, MPI_REAL, 0, 0, req, ierr)
    CALL MPI_WAIT(req, status)
    DO I=1, n-1
       CALL MPI_ISEND(outval, 1, MPI_REAL, 0, 0, req, ierr)
       CALL MPI_REQUEST_FREE(req, ierr)
       CALL MPI_IRECV(inval, 1, MPI_REAL, 0, 0, req, ierr)
       CALL MPI_WAIT(req, status, ierr)
    END DO
    CALL MPI_ISEND(outval, 1, MPI_REAL, 0, 0, req, ierr)
    CALL MPI_WAIT(req, status)
END IF

此例程通常用于释放通过MPI_Recv_init或MPI_Send_init等创建的持久请求。不过，它也可用于释放由MPI_Irecv或MPI_Isend等创建的请求；在这种情况下，用户无法对该请求使用测试/等待例程。

允许释放一个活跃的请求。然而，一旦释放后，您不能在等待或测试例程（例如MPI_Wait）中使用该请求。

17.2.302.5. 错误

几乎所有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不保证MPI程序在出现错误后能够继续运行。

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

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

另请参阅