17.2.427. MPI_Win_allocate
MPI_Win_allocate — 一个单边MPI调用，用于分配内存并返回一个用于RMA操作的窗口对象。
17.2.427.1. 语法
17.2.427.1.1. C语法
#include <mpi.h>
int MPI_Win_allocate (MPI_Aint size, int disp_unit, MPI_Info info,
MPI_Comm comm, void *baseptr, MPI_Win *win)
17.2.427.1.2. Fortran语法
USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_WIN_ALLOCATE(SIZE, DISP_UNIT, INFO, COMM, BASEPTR, WIN, IERROR)
INTEGER(KIND=MPI_ADDRESS_KIND) SIZE, BASEPTR
INTEGER DISP_UNIT, INFO, COMM, WIN, IERROR
17.2.427.1.3. Fortran 2008 语法
USE mpi_f08
MPI_Win_allocate(size, disp_unit, info, comm, baseptr, win, ierror)
USE, INTRINSIC :: ISO_C_BINDING, ONLY : C_PTR
INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(IN) :: size
INTEGER, INTENT(IN) :: disp_unit
TYPE(MPI_Info), INTENT(IN) :: info
TYPE(MPI_Comm), INTENT(IN) :: comm
TYPE(C_PTR), INTENT(OUT) :: baseptr
TYPE(MPI_Win), INTENT(OUT) :: win
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
17.2.427.2. 输入参数
size: 窗口大小（以字节为单位，非负整数）。disp_unit: 位移量的本地单位大小，以字节为单位（正整数）。info: 信息参数（句柄）。comm: 通信器（句柄）。
17.2.427.3. 输出参数
baseptr: 窗口的初始地址。win: 调用返回的窗口对象（句柄）。ierror: 仅限Fortran：错误状态（整数）。
17.2.427.4. 描述
MPI_Win_allocate 是一个由 comm 组内所有进程共同执行的集体调用。在每个进程上，它会分配至少 size 字节的内存，返回指向该内存的指针，并返回一个窗口对象，该对象可被 comm 中的所有进程用于执行RMA操作。返回的内存由每个进程本地的 size 字节组成，起始地址为 baseptr，其与窗口的关联方式类似于用户在现有内存上调用 MPI_Win_create。参数 size 在每个进程上可以不同，且 size = 0 是有效的；然而，为了实现快速、全局对称的内存分配，库可能会分配并暴露更多内存。MPI-3.1 第8.2节中关于 MPI_Alloc_mem 和 MPI_Free_mem 的讨论及原理同样适用于 MPI_Win_allocate；特别是关于 baseptr 所用类型的解释，请参阅MPI-3.1第8.2节的原理说明。
位移单位参数用于简化RMA操作中的地址计算：在窗口创建时，RMA操作的目标位移参数会按目标进程指定的disp_unit因子进行缩放。
有关支持的信息键，请参阅MPI_Win_create。
17.2.427.5. 注意事项
disp_unit 的常见选择包括 1（不缩放）和（以 C 语法表示的）sizeof(type)，适用于由某种type类型元素数组组成的窗口。后一种选择允许在 RMA 调用中使用数组索引，并确保这些索引能正确转换为字节位移，即使在异构环境中也是如此。
调用 MPI_Win_free 将释放由 MPI_Win_allocate 分配的内存。因此手动释放 baseptr 是错误的。
17.2.427.6. C 语言注意事项
虽然baseptr是void *类型，但这是为了方便使用任何指针对象作为此参数。该参数实际上是void **类型。
17.2.427.7. 错误
几乎所有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-3.1标准中的错误处理部分。