17.2.361. MPI_T_pvar_get_info

MPI_T_pvar_get_info — 从性能变量查询信息

17.2.361.1. 语法

17.2.361.1.1. C语法

#include <mpi.h>

int MPI_T_pvar_get_info(int pvar_index, char *name, int *name_len,
                        int *verbosity, int *var_class, MPI_Datatype *datatype, MPI_T_enum *enumtype,
                        char *desc, int *desc_len, int *bind, int *readonly, int *continuous,
                        int *atomic)

17.2.361.2. 输入参数

pvar_index: 要查询的性能变量索引。

17.2.361.3. 输入/输出参数

name_len: 名称字符串和/或缓冲区的长度。
desc_len: 描述字符串和/或缓冲区的长度。

17.2.361.4. 输出参数

name: 用于返回包含性能变量名称的字符串的缓冲区。
verbosity: 该变量的详细级别。
var_class: 性能变量的类别。
datatype: 性能变量中存储信息的MPI数据类型。
enumtype: 枚举信息的可选描述符。
desc: 用于返回包含性能变量描述的字符串缓冲区。
bind: 该变量必须绑定的MPI对象类型。
readonly: 标志变量是否可被写入/重置。
continuous: 标志位，表示该变量可以被启动和停止，还是持续处于活动状态。
atomic: 标志位，表示该变量是否支持原子读取和重置操作。

17.2.361.5. 描述

MPI_T_pvar_get_info 可用于从性能变量中查询信息。该函数分别在参数 verbosity、var_class、datatype、enumtype 和 bind 中返回查询控制变量的详细级别、类别、数据类型、枚举类型和绑定关系。标志位 readonly、continuous 和 atomic 分别表示该变量是否为只读、连续或原子操作。更多信息请参阅MPI-3标准第14.3.7节。关于变量详细级别的说明，请参见MPI_T_cvar_get_info的手册页。

17.2.361.6. 变量类

性能变量被分类为不同的类别，这些类别描述了它们的初始值、有效类型和行为。在var_class参数中返回的类别可能是以下之一：

MPI_T_PVAR_CLASS_STATE: 该变量表示一组可由枚举器描述的离散状态。此类的变量必须用MPI_INT表示。起始值为该变量的当前状态。
MPI_T_PVAR_CLASS_LEVEL: 该变量表示资源的当前利用率水平。此类的变量必须由MPI_UNSIGNED、MPI_UNSIGNED_LONG、MPI_UNSIGNED_LONG_LONG或MPI_DOUBLE类型表示。起始值为该资源的当前利用率水平。
MPI_T_PVAR_CLASS_SIZE: 该变量表示资源的固定大小。此类的变量由MPI_UNSIGNED、MPI_UNSIGNED_LONG、MPI_UNSIGNED_LONG_LONG或MPI_DOUBLE表示。起始值为资源的当前大小。
MPI_T_PVAR_CLASS_PERCENTAGE: 该变量表示资源的当前利用率百分比。此类别变量由MPI_DOUBLE类型表示。初始值为资源的当前利用率百分比。
MPI_T_PVAR_CLASS_HIGHWATERMARK: 该变量表示资源使用的高水位标记。此类的变量由MPI_UNSIGNED、MPI_UNSIGNED_LONG、MPI_UNSIGNED_LONG_LONG或MPI_DOUBLE类型表示。初始值为资源的当前使用量。
MPI_T_PVAR_CLASS_HIGHWATERMARK: 该变量表示资源利用率的低水位标记。此类的变量由MPI_UNSIGNED、MPI_UNSIGNED_LONG、MPI_UNSIGNED_LONG_LONG或MPI_DOUBLE表示。起始值为该资源的当前利用率。
MPI_T_PVAR_CLASS_COUNTER: 该变量表示特定事件发生次数的计数。此类的变量由MPI_UNSIGNED、MPI_UNSIGNED_LONG或MPI_UNSIGNED_LONG_LONG表示。起始值为0。
MPI_T_PVAR_CLASS_COUNTER: 该变量表示一个聚合值，用于统计特定事件处理过程中的参数总和。此类变量使用MPI_UNSIGNED、MPI_UNSIGNED_LONG、MPI_UNSIGNED_LONG_LONG或MPI_DOUBLE类型表示，初始值为0。
MPI_T_PVAR_CLASS_TIMER: 该变量表示MPI实现在处理事件、事件类型或代码段时所花费的累计时间。此类的变量由MPI_UNSIGNED、MPI_UNSIGNED_LONG、MPI_UNSIGNED_LONG_LONG或MPI_DOUBLE表示。如果变量由MPI_DOUBLE表示，单位将与MPI_Wtime()使用的单位相同。起始值为0。
MPI_T_PVAR_CLASS_GENERIC: 该变量不属于任何其他类别。可以通过MPI工具信息接口支持的类型来表示（参见DATATYPE）。初始值因变量而异。

更多信息请参阅MPI-3第14.3.7节。

17.2.361.7. 数据类型

由MPI_T_pvar_get_info返回的数据类型仅限于以下类型之一：MPI_INT、MPI_UNSIGNED、MPI_UNSIGNED_LONG、MPI_UNSIGNED_LONG_LONG、MPI_COUNT、MPI_CHAR和MPI_DOUBLE。有关MPI工具信息接口中数据类型的更多信息，请参阅MPI-3第14.3.5节。

17.2.361.8. 绑定

性能变量可以绑定到MPI对象。在bind参数中返回的绑定可能是以下之一：

MPI_T_BIND_NO_OBJECT: 无对象
MPI_T_BIND_MPI_COMM: MPI通信器
MPI_T_BIND_MPI_DATATYPE: MPI数据类型
MPI_T_BIND_MPI_ERRHANDLER: MPI错误处理器
MPI_T_BIND_MPI_FILE: MPI文件句柄
MPI_T_BIND_MPI_GROUP: MPI组
MPI_T_BIND_MPI_OP: MPI归约操作符
MPI_T_BIND_MPI_REQUEST: MPI请求
MPI_T_BIND_MPI_WIN: 用于单边通信的MPI窗口
MPI_T_BIND_MPI_MESSAGE: MPI消息对象
MPI_T_BIND_MPI_INFO: MPI信息对象

更多信息请参阅MPI-3第14.3.2节。

17.2.361.9. 备注

该MPI工具接口函数返回两个字符串。此函数为每个字符串接收两个参数：一个用于存储字符串的缓冲区，以及一个初始必须指定缓冲区大小的长度值。如果传入的长度为n，则该函数最多将字符串的n-1个字符复制到相应缓冲区中，并将长度设置为实际复制的字符数减1。若长度参数为NULL或指定的长度值为0，则忽略对应的字符串缓冲区且不返回该字符串。更多信息请参阅MPI-3标准第14.3.3节。

17.2.361.10. 错误

MPI_T_pvar_get_info 在以下情况下会失败：

MPI_T_ERR_NOT_INITIALIZED: MPI工具接口未初始化
MPI_T_ERR_INVALID_INDEX: 性能变量索引无效

另请参阅

MPI_T_cvar_get_info