LAPI_Init 子例程

用途

初始化 LAPI 上下文。

库

可用性库 (liblapi_r.a)

C 语法

#include <lapi.h>
 
int LAPI_Init(hndl,lapi_info)
lapi_handle_t *hndl;
lapi_info_t *lapi_info;

FORTRAN 语法

include 'lapif.h'
 
LAPI_INIT(hndl,lapi_info,ierror)
INTEGER hndl
TYPE (LAPI_INFO_T) :: lapi_info
INTEGER ierror

描述

Type of call: 本地初始化

使用此子例程来实例化和初始化新的 LAPI 上下文。新创建的 LAPI 上下文的句柄在 hndl中返回。所有后续 LAPI 调用都可以使用 hndl 来指定 LAPI 操作的上下文。除了 LAPI_Address() 和 LAPI_Msg_string()之外，用户在调用 LAPI_Init()之前无法进行任何 LAPI 调用。

在填写任何字段之前，必须将 lapi_info 结构 (lapi_info_t) "清零"。要在 C 中执行此操作，请使用以下语句: bzero (lapi_info, size of (lapi_info_t))。在 FORTRAN 中，您需要在 LAPI_INFO_T 类型中手动将每个字段 "置零"。不应使用描述为 Future support 的字段，因为这些字段的名称可能会更改。

lapi_info_t 结构定义如下:

typedef struct {                     
    lapi_dev_t     protocol;      /* Protocol device returned                    */
    lapi_lib_t     lib_vers;      /* LAPI library version -- user-supplied       */
    uint           epoch_num;     /* No longer used                              */
    int            num_compl_hndlr_thr; /* Number of completion handler threads  */
    uint           instance_no;   /* Instance of LAPI to initialize [1-16]       */ 
    int            info6;         /* Future support                              */
    LAPI_err_hndlr *err_hndlr;    /* User-registered error handler               */
    com_thread_info_t *lapi_thread_attr; /* Support thread att and init function */
    void           *adapter_name; /* What adapter to initialize, i.e. css0, ml0  */
    lapi_extend_t  *add_info;     /* Additional structure extension              */
} lapi_info_t;

这些字段使用如下：

协议

LAPI 将此字段设置为已初始化的协议。

lib_vers

用于指示 LAPI 的库版本以实现兼容性。此字段的有效值是：

L1_LIB: 提供基本功能 (这是缺省值)。
L2_LIB: 提供将计数器用作结构的能力。
LAST_LIB: 提供最新级别的功能。对于 LAPI 的新用户， lib_vers 应设置为 LAST_LIB。

此字段必须设置为 L2_LIB 或 LAST_LIB 才能使用 LAPI_Nopoll_wait 和 LAPI_Setcntr_wstatus。

戳记号

不再使用此字段。

num_compl_hndlr_thr

向 LAPI 指示要初始化的完成处理程序线程数。

实例 (否)

指定要初始化的 LAPI 实例 (1 到 16)。

info6

此字段供将来使用。

err_hndlr

使用此字段可选择将回调指针传递到错误处理程序例程。

lapi_thread_attr

支持线程属性和初始化函数。

适配器名称

在持久子系统 (PSS) 方式下用于传递适配器名称。

添加信息

用于独立 UDP 方式下的其他信息。

参数

输入/输出
lapi_info: 指定用于提供与此 LAPI 上下文关联的并行作业信息的结构。此参数的值不能为 NULL (在 C 中) 或 LAPI_ADDR_NULL (在 FORTRAN 中)。
输出
hndl: 指定指向要初始化的 LAPI 句柄的指针。
ierror: 指定 FORTRAN 返回码。这始终是最后一个参数。

返回值

成功 (LAPI_SUCCESS): 指示函数调用已成功完成。
LAPI_ERR_ALL_HNDL_IN_USE: 所有可用的 LAPI 实例都在使用中。
LAPI_ERR_BOTH_NETSTR_SET: 同时设置了 MP_LAPI_NETWORK 和 MP_LAPI_INET 语句 (仅应设置一个语句)。
LAPI_ERR_CSS_LOAD_FAILED: LAPI 无法装入通信实用程序库。
LAPI_ERR_HNDL_INVALID: 传递到 LAPI 以进行初始化的 lapi_handle_t * 为 NULL (在 C 中) 或 LAPI_ADDR_NULL (在 FORTRAN 中)。
LAPI_ERR_INFO_NONZERO_INFO: 传递到 LAPI 的 lapi_info_t 结构中的未来支持字段未设置为零 (并且应该设置为零)。
LAPI_ERR_INFO_NULL: 传递到 LAPI 的 lapi_info_t 指针为 NULL (在 C 中) 或 LAPI_ADDR_NULL (在 FORTRAN 中)。
已耗尽LAPI_ERR_MEMORY_死: LAPI 无法从系统获取内存。
LAPI_ERR_MSG_API: 指示未正确设置 MP_MSG_API 环境变量。
LAPI_ERR_NO_NETSTR_SET: 未设置网络语句。请注意，如果与 POE 一起运行，那么如果未正确设置 MP_MSG_API ，那么将返回此值。
LAPI_ERR_NO_UDP_HNDLR: 您为 UDP 处理程序和 UDP 列表传递了值 NULL (以 C 为) 或 LAPI_ADDR_NULL (以 FORTRAN 为)。其中一个 (UDP 处理程序或 UDP 列表) 必须针对独立 UDP 初始化进行初始化。此错误仅以独立 UDP 方式返回。
LAPI_ERR_PSS_NON_ROOT: 您尝试以非 root 用户身份初始化持久子系统 (PSS) 协议。
LAPI_ERR_SHM_KE_NOT_LOADED: 未装入 LAPI 的共享内存内核扩展。
LAPI_ERR_SHM_SETUP: LAPI 无法设置共享内存。如果将 LAPI_USE_SHM=only 和任务分配给多个节点，那么将返回此错误。
LAPI_ERR_UDP_PKT_SZ: 您指示的 UDP 包大小无效。
LAPI_ERR_UNKNOWN: 发生了内部错误。
LAPI_ERR_USER_UDP_HNDLR_FAIL: 您传递的 UDP 处理程序返回了非零错误代码。此错误仅以独立 UDP 方式返回。

C 示例

在初始化 LAPI 之前，必须设置以下环境变量:


MP_MSG_API=[ lapi | [ lapi,mpi | mpi,lapi ] | mpi_lapi ]

还常用以下环境变量:


MP_EUILIB=[ ip | us ] (ip is the default)

MP_PROCS=number_of_tasks_in_job

LAPI_USE_SHM=[ yes | no | only ] (no is the default)

要初始化 LAPI ，请执行以下步骤:

在调用用户应用程序之前设置环境变量 (如 RSCT for AIX 5L: LAPI Programming Guide中所述)。其余步骤在用户应用程序中完成。
清除 lapi_info_t，然后设置任何字段。
调用 LAPI_Init。

对于运行 PE 的系统

共享句柄支持 US 和 UDP/IP ，只要这两个句柄相同。不支持混合传输协议，例如 LAPI IP 和共享用户空间 (US)。

要初始化 LAPI 句柄:


{
    lapi_handle_t hndl;
    lapi_info_t info;
 
    bzero(&info, sizeof(lapi_info_t));  /* clear lapi_info */
 
    LAPI_Init(&hndl, &info);
}

要初始化 LAPI 句柄并注册错误处理程序:


void my_err_hndlr(lapi_handle_t *hndl, int *error_code, lapi_err_t *err_type,
                  int *task_id, int *src )
{
   /* examine passed parameters and delete desired information */
   
   if ( user wants to terminate ) {
       LAPI_Term(*hndl);                /* will terminate LAPI */
       exit(some_return_code);  
   }
 
   /* any additional processing */
   
   return; /* signals to LAPI that error is non-fatal; execution should continue */
}
 
{
    lapi_handle_t hndl;
    lapi_info_t info;
 
 
    bzero(&info, sizeof(lapi_info_t));  /* clear lapi_info */
 
    /* set error handler pointer */
    info.err_hndlr = (LAPI_err_hndlr) my_err_hndlr;
 
    LAPI_Init(&hndl, &info);
}

对于独立系统 (未运行 PE)

要使用用户处理程序初始化用于 UDP/IP 通信的 LAPI 句柄:


int my_udp_hndlr(lapi_handle_t *hndl, lapi_udp_t *local_addr, lapi_udp_t *addr_list, 
                 lapi_udpinfo_t *info)

{
    /* LAPI will allocate and free addr_list pointer when using */
    /* a user handler                                           */

    /* use the AIX(r) inet_addr call to convert an IP address      */
    /* from a dotted quad to a long                             */
    task_0_ip_as_long = inet_addr(task_0_ip_as_string);
    addr_list[0].ip_addr = task_0_ip_as_long;
    addr_list[0].port_no = task_0_port_as_unsigned;

    task_1_ip_as_long = inet_addr(task_1_ip_as_string);
    addr_list[1].ip_addr = task_1_ip_as_long;
    addr_list[1].port_no = task_1_port_as_unsigned;
    .	
    .
    .
    task_num_tasks-1_ip_as_long = inet_addr(task_num_tasks-1_ip_as_string);
    addr_list[num_tasks-1].ip_addr = task_num_tasks-1_ip_as_long;
    addr_list[num_tasks-1].port_no = task_num_tasks-1_port_as_unsigned;

}


{
    lapi_handle_t hndl;
    lapi_info_t info;
    lapi_extend_t extend_info;

    bzero(&info, sizeof(lapi_info_t));           /* clear lapi_info        */
    bzero(&extend_info, sizeof(lapi_extend_t));  /* clear lapi_extend_info */

    extend_info.udp_hndlr = (udp_init_hndlr *) my_udp_hndlr;
    info.add_info = &extend_info;
    
 
    LAPI_Init(&hndl, &info);
}

要使用用户列表初始化用于 UDP/IP 通信的 LAPI 句柄:


{
    lapi_handle_t hndl;
    lapi_info_t info;
    lapi_extend_t extend_info;
    lapi_udp_t *addr_list;

    bzero(&info, sizeof(lapi_info_t));           /* clear lapi_info        */
    bzero(&extend_info, sizeof(lapi_extend_t));  /* clear lapi_extend_info */

    /* when using a user list, the user is responsible for allocating          */
    /* and freeing the list pointer                                            */
    addr_list = malloc(num_tasks);
    
    /* Note, since we need to know the number of tasks before LAPI is          */
    /* initialized, we can't use LAPI_Qenv.  getenv("MP_PROCS") will           */
    /* do the trick.                                                           */


    /* populate addr_list                                                      */
    /* use the AIX(r) inet_addr call to convert an IP address                     */
    /* from a dotted quad to a long                                            */
    task_0_ip_as_long = inet_addr(task_0_ip_as_string);
    addr_list[0].ip_addr = task_0_ip_as_long;
    addr_list[0].port_no = task_0_port_as_unsigned;

    task_1_ip_as_long = inet_addr(task_1_ip_as_string);
    addr_list[1].ip_addr = task_1_ip_as_long;
    addr_list[1].port_no = task_1_port_as_unsigned;
    .
    .
    .
    task_num_tasks-1_ip_as_long = inet_addr(task_num_tasks-1_ip_as_string);
    addr_list[num_tasks-1].ip_addr = task_num_tasks-1_ip_as_long;
    addr_list[num_tasks-1].port_no = task_num_tasks-1_port_as_unsigned;


    /* then assign to extend pointer */
    extend_info.add_udp_addrs = addr_list;

    info.add_info = &extend_info;
    
 
    LAPI_Init(&hndl, &info);
    .
    .
    .

    /* user's responsibility only in the case of user list */
    free(addr_list);

}

请参阅 LAPI 样本程序以获取独立方式初始化的完整示例。

要以独立方式初始化用户空间 (US) 通信的 LAPI 句柄:


export MP_MSG_API=lapi
export MP_EUILIB=us
export MP_PROCS=                    /* number of tasks in job   */
export MP_PARTITION=                /* unique job key           */
export MP_CHILD=                    /* unique task ID           */
export MP_LAPI_NETWORK=@1:164,sn0   /* LAPI network information */

run LAPI jobs as normal

请参阅 LAPI 样本文件的 standalone/us 目录中的 README.LAPI.STANDALONE.US 文件以获取完整详细信息。

位置

/usr/lib/liblapi_r.a