17.2.392. MPI_Type_create_struct
MPI_Type_create_struct — 创建一个结构化数据类型。
17.2.392.1. 语法
17.2.392.1.1. C语法
#include <mpi.h>
int MPI_Type_create_struct(int count, int array_of_blocklengths[],
const MPI_Aint array_of_displacements[], const MPI_Datatype array_of_types[],
MPI_Datatype *newtype)
17.2.392.1.2. Fortran语法
USE MPI
! or the older form: INCLUDE 'mpif.h'
MPI_TYPE_CREATE_STRUCT(COUNT, ARRAY_OF_BLOCKLENGTHS,
ARRAY_OF_DISPLACEMENTS, ARRAY_OF_TYPES, NEWTYPE, IERROR)
INTEGER COUNT, ARRAY_OF_BLOCKLENGTHS(*), ARRAY_OF_TYPES(*),
INTEGER NEWTYPE, IERROR
INTEGER(KIND=MPI_ADDRESS_KIND) ARRAY_OF_DISPLACEMENTS(*)
17.2.392.1.3. Fortran 2008 语法
USE mpi_f08
MPI_Type_create_struct(count, array_of_blocklengths,
array_of_displacements, array_of_types, newtype, ierror)
INTEGER, INTENT(IN) :: count, array_of_blocklengths(count)
INTEGER(KIND=MPI_ADDRESS_KIND), INTENT(IN) ::
array_of_displacements(count)
TYPE(MPI_Datatype), INTENT(IN) :: array_of_types(count)
TYPE(MPI_Datatype), INTENT(OUT) :: newtype
INTEGER, OPTIONAL, INTENT(OUT) :: ierror
17.2.392.2. 输入参数
count: 块数量（整数）——同时也是数组array_of_types、array_of_displacements和array_of_blocklengths中的条目数。array_of_blocklengths: 每个块中的元素数量（整数数组）。array_of_displacements: 每个块的字节位移（整数数组）。array_of_types: 每个块中元素的类型（数据类型对象句柄的数组）。
17.2.392.3. 输出参数
newtype: 新数据类型（句柄）。ierror: 仅限Fortran：错误状态（整数）。
17.2.392.4. 描述
MPI_Type_create_struct 创建一个结构化数据类型。该例程取代了现已弃用的 MPI_Type_struct。
MPI_Type_create_struct 是最通用的类型构造函数。它在MPI_Type_create_hindexed的基础上进一步扩展，允许每个数据块由不同数据类型的重复元素组成。
示例1:
设type1具有类型映射
{(double, 0), (char, 8)}
扩展范围为16。设B = (2, 1, 3)，D = (0, 16, 26)，以及T = (MPI_FLOAT, type1, MPI_CHAR)。
然后调用MPI_Type_create_struct(3, B, D, T, newtype)
将返回一个具有以下类型映射的数据类型
{
(float, 0), (float,4), // 2 float
(double, 16), (char, 24), // 1 type1
(char, 26), (char, 27), (char, 28) // 3 char
}
也就是说，从0开始的两个MPI_FLOAT副本，接着是从16开始的一个type1副本，然后是从26开始的三个MPI_CHAR副本。
示例2：
一个结构体示例，其中仅部分组件属于该类型
struct MyStruct {
double x[2], y;
char a;
int n;
};
// create a new type where we only send x, y and n
int B[] = {
2, // 2 double's
1, // 1 double
1, // 1 int
1 // alignment padding
};
MPI_Aint D[] = {
offsetof(struct MyStruct, x),
offsetof(struct MyStruct, y),
offsetof(struct MyStruct, n),
sizeof(struct MyStruct)
};
MPI_Datatype T[] = {
MPI_DOUBLE,
MPI_DOUBLE,
MPI_INT,
MPI_UB
};
MPI_Datatype mpi_dt_mystruct;
MPI_Type_create_struct(4, B, D, T, &mpi_dt_mystruct);
MPI_Type_commit(&mpi_dt_mystruct);
// We can now send a struct (omitting a)
struct MyStruct values[3];
if ( rank == 0 ) {
// ... initialize values
MPI_Send(values, 3, mpi_dt_mystruct, 1, 0, MPI_COMM_WORLD);
} else if ( rank == 1 ) {
MPI_Recv(values, 3, mpi_dt_mystruct, 0, 0, MPI_COMM_WORLD, MPI_STATUS_IGNORE);
}
更多信息，请参阅MPI-4.0标准第5.1.2节。
17.2.392.5. 备注
如果通过使用MPI数据类型MPI_UB显式设置了上限，则对应的索引必须为正数。
MPI-1标准最初对填充和对齐做出了模糊的说明；这是为了允许简单定义可以通过计数大于一发送的结构。例如，
struct {int a; char b;} foo;
可能有
sizeof(foo) = sizeof(int) + sizeof(char);
将数据类型的范围定义为包含一个epsilon值，这将允许实现使该结构的MPI数据类型范围等于2*sizeof(int)。然而，由于不同系统可能定义不同的填充方式，标准的一个澄清将epsilon设为零。因此，如果您定义了一个结构体数据类型并希望发送或接收多个项目，您应该明确地在结构体的最后一个成员中包含一个MPI_UB条目。请参阅上面的示例。
17.2.392.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不保证MPI程序在出现错误后能够继续运行。
有关更多信息，请参阅MPI-3.1标准中的错误处理部分。