17.2.182. MPI_Grequest_start

MPI_Grequest_start — 启动一个广义请求并在request中返回其句柄。

17.2.182.1. 语法

17.2.182.1.1. C语法

#include <mpi.h>

int MPI_Grequest_start(MPI_Grequest_query_function *query_fn,
    MPI_Grequest_free_function *free_fn,
    MPI_Grequest_cancel_function *cancel_fn, void *extra_state,
    MPI_Request *request)

17.2.182.1.2. Fortran 语法

USE MPI
! or the older form: INCLUDE 'mpif.h'

MPI_GREQUEST_START(QUERY_FN, FREE_FN, CANCEL_FN, EXTRA_STATE,
    REQUEST, IERROR)
    INTEGER REQUEST, IERROR
    EXTERNAL QUERY_FN, FREE_FN, CANCEL_FN
      INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE

17.2.182.1.3. Fortran 2008 语法

USE mpi_f08

MPI_Grequest_start(query_fn, free_fn, cancel_fn, extra_state, request,
        ierror)
    PROCEDURE(MPI_Grequest_query_function) :: query_fn
    PROCEDURE(MPI_Grequest_free_function) :: free_fn
    PROCEDURE(MPI_Grequest_cancel_function) :: cancel_fn
    INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(IN) :: extra_state
    TYPE(MPI_Request), INTENT(OUT) :: request
    INTEGER, OPTIONAL, INTENT(OUT) :: ierror

17.2.182.2. 输入参数

  • query_fn当请求状态被查询时调用的回调函数

    （函数）。

  • free_fn请求释放时调用的回调函数

    (函数).

  • cancel_fn请求被取消时调用的回调函数

    (函数)。

  • extra_state : 额外状态。

17.2.182.3. 输出参数

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

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

17.2.182.4. 描述

MPI_Grequest_start 启动一个广义request并在request中返回其句柄。

回调函数的语法和含义如下所列。所有回调函数都会接收由起始调用MPI_Grequest_start关联到request的extra_state参数。这可用于维护用户为request定义的状态。在C语言中，查询函数为

typedef int MPI_Grequest_query_function(void *extra_state,
    MPI_Status *status);

在Fortran中，它是

SUBROUTINE GREQUEST_QUERY_FUNCTION(EXTRA_STATE, STATUS, IERROR)
    INTEGER STATUS(MPI_STATUS_SIZE), IERROR
    INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE

query_fn 函数计算应返回的广义请求状态。该状态还包含请求取消成功/失败的信息（结果将由 MPI_Test_cancelled 返回）。

当MPI_{Wait|Test}{any|some|all}调用完成与此回调关联的广义请求时，会触发query_fn函数。若请求在调用时已完成，则MPI_Request_get_status调用也会触发此回调函数。在这两种情况下，回调都会接收到用户传递给MPI调用的对应状态变量的引用。如果用户向触发query_fn的MPI函数提供了MPI_STATUS_IGNORE或MPI_STATUSES_IGNORE，MPI仍会向query_fn传递有效的状态对象，但该状态将在回调函数返回时被忽略。请注意，query_fn仅在请求上调用MPI_Grequest_complete后才会被触发；对于同一个广义请求可能会被多次触发。还需注意，MPI_{Wait|Test}{some|all}调用可能导致query_fn回调函数的多次触发，每次对应一个由MPI调用完成的广义请求。这些触发的顺序不由MPI规范定义。

在C语言中，free函数的作用是

typedef int MPI_Grequest_free_function(void *extra_state);

而在Fortran中，它是

SUBROUTINE GREQUEST_FREE_FUNCTION(EXTRA_STATE, IERROR)
    INTEGER IERROR
    INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE

当通用请求被释放时，会调用free_fn回调函数来清理用户分配的资源。

free_fn函数由完成与此回调关联的通用请求的MPI_{Wait|Test}{any|some|all}调用触发。free_fn会在对同一请求调用query_fn之后执行。不过，如果MPI调用完成了多个通用请求，MPI并未规定free_fn回调函数的执行顺序。

对于通过调用MPI_Request_free释放的广义请求（此类请求不会调用MPI_{Wait|Test}{any|some|all}），也会触发free_fn回调函数。在这种情况下，回调函数将在MPI调用MPI_Request_free(request)或MPI调用MPI_Grequest_complete(request)中较晚发生的那个调用中被执行。换句话说，在这种情况下，实际的释放代码会在两个调用（MPI_Request_free和MPI_Grequest_complete）都完成后立即执行。request在free_fn完成之前不会被释放。请注意，正确的程序对每个请求只会调用一次free_fn。

在C语言中，取消函数是

typedef int MPI_Grequest_cancel_function(void *extra_state, int complete);

在Fortran中，取消函数是

SUBROUTINE GREQUEST_CANCEL_FUNCTION(EXTRA_STATE, COMPLETE, IERROR)
     INTEGER IERROR
     INTEGER(KIND=MPI_ADDRESS_KIND) EXTRA_STATE
     LOGICAL COMPLETE

cancel_fn 函数用于启动广义请求的取消操作。它由 MPI_Request_cancel(request) 调用。如果已经对该请求调用了 MPI_Grequest_complete，MPI 会向回调函数传递 complete=true 参数，否则传递 complete=false。

17.2.182.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标准中的错误处理部分。

所有回调函数都会返回一个错误代码。该代码会被传递回并由调用回调函数的MPI函数根据错误代码进行相应处理。例如，如果返回错误代码，那么调用回调函数的MPI函数将返回回调函数返回的错误代码。在调用query_fn和free_fn的MPI_{Wait|Test}any调用中，MPI调用将返回最后一个回调函数（即free_fn）返回的错误代码。如果在调用``MPI_{Wait|Test}{some|all}时一个或多个request失败，则MPI调用将返回MPI_ERR_IN_STATUS。在这种情况下，如果MPI调用传递了一个状态数组，那么MPI将在每个对应于已完成广义request的状态中返回其free_fn回调函数相应调用返回的错误代码。然而，如果MPI函数传递了MPI_STATUSES_IGNORE，则每个回调函数返回的单独错误代码将丢失。