17.2.428. MPI_Win_allocate_shared
MPI_Win_allocate_shared — 一种单边MPI调用，用于分配共享内存并返回一个用于RMA操作的窗口对象。
17.2.428.1. 语法
17.2.428.1.1. C语法
#include <mpi.h>
int MPI_Win_allocate_shared (MPI_Aint size, int disp_unit, MPI_Info info,
MPI_Comm comm, void *baseptr, MPI_Win *win)
17.2.428.1.2. Fortran 语法
USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_WIN_ALLOCATE_SHARED(SIZE, DISP_UNIT, INFO, COMM, BASEPTR, WIN, IERROR)
INTEGER(KIND=MPI_ADDRESS_KIND) SIZE, BASEPTR
INTEGER DISP_UNIT, INFO, COMM, WIN, IERROR
17.2.428.1.3. Fortran 2008 语法
USE mpi_f08
MPI_Win_allocate_shared(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.428.2. 输入参数
size: 窗口大小（以字节为单位，非负整数）。disp_unit: 位移量的本地单位大小，以字节为单位（正整数）。info: 信息参数（句柄）。comm: 通信器（句柄）。
17.2.428.3. 输出参数
baseptr: 窗口的初始地址。win: 调用返回的窗口对象（句柄）。ierror: 仅限Fortran：错误状态（整数）。
17.2.428.4. 描述
MPI_Win_allocate_shared 是一个由comm通信组中所有进程共同执行的集体调用。在每个进程上，它会分配至少size字节的内存空间，这些内存由comm中的所有进程共享，并通过baseptr返回指向本地分配内存段的指针，该指针可用于调用进程的加载/存储访问。本地分配的内存可以成为远程进程进行加载/存储访问的目标；其他进程的基指针可通过函数MPI_Win_shared_query查询。该调用还会返回一个窗口对象，comm中的所有进程都可以使用该对象执行RMA操作。size参数在每个进程中可以不同，且允许size = 0。用户需要确保通信器comm所代表的进程组能够创建可被组内所有进程访问的共享内存段。MPI-3.1标准第8.2节中关于MPI_Alloc_mem和MPI_Free_mem的设计原理同样适用于MPI_Win_allocate_shared；特别是关于baseptr所用类型的解释，可参考MPI-3.1第8.2节的原理说明。除非指定了info键alloc_shared_noncontig，否则分配的内存将在进程秩上连续分布。进程秩连续意味着进程i的内存段首地址与进程i-1的内存段末地址相邻接。这一特性可能使用户仅凭本地信息就能计算远程地址偏移量。
支持以下信息键：
- alloc_shared_noncontig
如果未设置为true，分配策略将按进程等级分配连续内存。在某些架构上这可能会限制性能，因为该策略不允许实现修改数据布局（例如通过填充来减少访问延迟）。
- blocking_fence
如果设置为true，osc/sm组件将使用MPI_Barrier来实现 MPI_Win_fence。如果设置为false，则会改用条件变量和计数器。 默认值为false。此信息键是Open MPI特有的。
如需了解更多支持的信息键，请参阅MPI_Win_create。
17.2.428.5. 注意事项
disp_unit的常见选择是1（无缩放），以及（用C语法表示的）sizeof(type)，适用于由type类型元素数组组成的窗口。后一种选择允许在RMA调用中使用数组索引，并确保这些索引能正确转换为字节位移，即使在异构环境中也是如此。
调用MPI_Win_free将释放由MPI_Win_allocate_shared分配的内存。因此手动释放baseptr是错误的。
17.2.428.6. C语言注意事项
虽然baseptr是void *类型，但这是为了方便使用任何指针对象作为此参数。该参数实际上是void **类型。
17.2.428.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标准中的错误处理部分。