LAPI_Xfer 子例程

#include <lapi.h>
 
int LAPI_Xfer(hndl, xfer_cmd)
lapi_handle_t hndl;
lapi_xfer_t *xfer_cmd;
 

typedef struct {
    uint            src;          /* Target task ID    */
    uint            reason;       /* LAPI return codes */
    ulong           reserve[6];   /* Reserved          */
} lapi_sh_info_t;


typedef void (scompl_hndlr_t)(lapi_handle_t *hndl, void *completion_param,
                              lapi_sh_info_t *info);
 

include 'lapif.h'
 
LAPI_XFER(hndl, xfer_cmd, ierror)
INTEGER hndl
TYPE (fortran_xfer_type) :: xfer_cmd
INTEGER ierror

此子例程提供以下函数:

• 远程地址字段将展开为类型为 lapi_long_t，这对于 64 位地址而言足够长。 这允许一个 32 位任务将数据发送到 64 位地址，这在客户机/服务器程序中可能很重要。
• LAPI_Xfer 允许将源计数器替换为发送完成回调。
• LAPI_Xfer 用于使用 LAPI 的数据收集/散点程序 (DGSP) 接口传输数据。

lapi_xfer_t 结构定义为:

typedef union {
        lapi_xfer_type_t   Xfer_type;
        lapi_get_t         Get;
        lapi_am_t          Am;
        lapi_rmw_t         Rmw;
        lapi_put_t         Put;
        lapi_getv_t        Getv;
        lapi_putv_t        Putv; 
        lapi_amv_t         Amv;
        lapi_amdgsp_t      Dgsp;
} lapi_xfer_t;

虽然 lapi_xfer_t 结构仅适用于 LAPI_Xfer的 C 版本，但下表包含 C 数据类型的 FORTRAN 等效项。

表 1 列出了 C 的 lapi_xfer_type_t 结构的值以及 FORTRAN 的显式 Xfer_type 值。

表 2 显示了 LAPI_Amsend 子例程的参数， C lapi_am_t 结构的字段及其数据类型以及等效的 FORTRAN 数据类型之间的对应关系。 lapi_am_t 字段按它们在 lapi_xfer_t 结构中的出现顺序列示在 表 2 中。当可自由使用原始数据缓冲区时，如果 shdlr 不是 NULL 指针 (在 C 中) 或 LAPI_ADDR_NULL (在 FORTRAN 中) ，那么将使用发送完成数据 (sinfo) 来调用发送完成处理程序 (shdlr) 的指针。 否则，行为与 LAPI_Amsend的行为相同。

表 3 显示了 LAPI_Amsendv 子例程的参数， C lapi_amv_t 结构的字段及其数据类型以及等效的 FORTRAN 数据类型之间的对应关系。 lapi_amv_t 字段按它们在 lapi_xfer_t 结构中的出现顺序列示在 表 3 中。

表 4 显示 C lapi_amdgsp_t 结构的字段与它们的数据类型之间的对应关系，它们在 LAPI_Xfer中的使用方式以及等效的 FORTRAN 数据类型。 lapi_amdgsp_t 字段按它们在 lapi_xfer_t 结构中的出现顺序列示在 表 4 中。

定义了以下伪指令标志:

USE_TGT_VEC_TYPE

指示 LAPI 使用目标矢量的矢量类型 (特克特韦茨)。 换言之， tgt_vec 将解释为类型 lapi_vec_t; 否则，将解释为类型 lapi_lvec_t。 lapi_lvec_t 类型使用 lapi_long_t。 lapi_vec_t 类型使用 void * 或 long。 如果使用一种类型代替另一种类型，那么将出现不正确的结果。

BUFFER_BOTH_CONTIOUS

指示 LAPI 将所有要传输的数据视为连续数据，这可以提高性能。 如果在发送非连续数据时设置此标志，那么数据很可能已损坏。

定义了以下提示标志:

LAPI_NOT_USE_BULK_XFER

指示 LAPI 不使用批量传输，而不与任务的当前设置相关。

LAPI_USE_BULK_XFER

指示 LAPI 使用批量传输，而不依赖于该任务的当前设置。

如果这两个提示标志都未设置，那么 LAPI 将使用为任务定义的行为。 如果设置了这两个提示标志，那么 LAPI_NOT_USE_BULK_XFER 将优先。

表 5 显示了 LAPI_Get 子例程的参数， C lapi_get_t 结构的字段及其数据类型以及等效的 FORTRAN 数据类型之间的对应关系。 lapi_get_t 字段按它们在 lapi_xfer_t 结构中的出现顺序列示在 表 5 中。当源数据缓冲区完全到达时，如果 chndlr 不是 NULL 指针 (在 C 中) 或 LAPI_ADDR_NULL (在 FORTRAN 中) ，那么将使用完成数据 (cinfo) 来调用指向完成处理程序 (chndlr) 的指针。 否则，行为与 LAPI_Get的行为相同。

表 6 显示了 LAPI_Getv 子例程的参数， C lapi_getv_t 结构的字段及其数据类型以及等效的 FORTRAN 数据类型之间的对应关系。 lapi_getv_t 字段按它们在 lapi_xfer_t 结构中的出现顺序列示在 表 5 中。flags 字段接受 USE_TGT_VEC_TYPE (请参阅 lapi_amdgsp_t flags 字段) ，以指示将 tgt_vec 解释为类型 lapi_vec_t; 否则，将其解释为类型 lapi_lvec_t。 请注意，相应的字段是 LAPI_Getv 调用中的 lapi_vec_t 。

表 7 显示了 LAPI_Put 子例程的参数， C lapi_put_t 结构的字段及其数据类型以及等效的 FORTRAN 数据类型之间的对应关系。 lapi_put_t 字段按它们在 lapi_xfer_t 结构中的出现顺序列示在 表 7 中。当可自由使用原始数据缓冲区时，如果 shdlr 不是 NULL 指针 (在 C 中) 或 LAPI_ADDR_NULL (在 FORTRAN 中) ，那么将使用发送完成数据 (sinfo) 来调用发送完成处理程序 (shdlr) 的指针。 否则，行为与 LAPI_Put的行为相同。

表 8 显示了 LAPI_Putv 子例程的参数， C lapi_putv_t 结构的字段及其数据类型以及等效的 FORTRAN 数据类型之间的对应关系。 lapi_putv_t 字段按它们在 lapi_xfer_t 结构中的出现顺序列示在 表 7 中。flags 字段接受 USE_TGT_VEC_TYPE (请参阅 lapi_amdgsp_t flags 字段) 以指示将 tgt_vec 解释为 lapi_vec_t; 否则，将其解释为 lapi_lvec_t。 请注意，在 LAPI_Putv 调用中，相应的字段为 lapi_vec_t 。

表 9 显示了 LAPI_Rmw 子例程的参数， C lapi_rmw_t 结构的字段及其数据类型以及等效的 FORTRAN 数据类型之间的对应关系。 lapi_rmw_t 字段按它们在 lapi_xfer_t 结构中的出现顺序列示在 表 7 中。当可自由使用原始数据缓冲区时，如果 shdlr 不是 NULL 指针 (在 C 中) 或 LAPI_ADDR_NULL (在 FORTRAN 中) ，那么将使用发送完成数据 (sinfo) 来调用发送完成处理程序 (shdlr) 的指针。 size 值必须是 32 或 64，指示您是否希望 in_val 和 prev_tgt_val 字段分别指向 32 位或 64 位数量。 否则，行为与 LAPI_Rmw的行为相同。

1. 要使用 LAPI_Xfer 界面运行 LAPI_Get 中显示的样本代码:

   {
   
         lapi_xfer_t xfer_struct;
   
         /* initialize the table buffer for the data addresses */
      
         /* get remote data buffer addresses */
         LAPI_Address_init(hndl,(void *)data_buffer,data_buffer_list);
         .    
         . 
         .
         /* retrieve data_len bytes from address data_buffer_list[tgt] on */
         /* task tgt. write the data starting at address data_buffer.     */
         /* tgt_cntr and org_cntr can be NULL.                            */ 
   
         xfer_struct.Get.Xfer_type = LAPI_GET_XFER;
         xfer_struct.Get.flags = 0;
         xfer_struct.Get.tgt = tgt;
         xfer_struct.Get.tgt_addr = data_buffer_list[tgt];
         xfer_struct.Get.org_addr = data_buffer;
         xfer_struct.Get.len = data_len;
         xfer_struct.Get.tgt_cntr = tgt_cntr;
         xfer_struct.Get.org_cntr = org_cntr;
       
         LAPI_Xfer(hndl, &xfer_struct);  
   
   }

2. 要使用 LAPI_Xfer 接口从 LAPI_Amsendv 实现 LAPI_STRIDED_VECTOR 示例:

   
   {
       lapi_xfer_t   xfer_struct;                        /* info for LAPI_Xfer call */
       lapi_vec_t    vec;                                /* data for data transfer  */
       .
       .
       .
       vec->num_vecs = NUM_VECS;        /* NUM_VECS = number of vectors to transfer */ 
                                        /* must match that of the target vector     */
       vec->vec_type = LAPI_GEN_STRIDED_XFER;              /* same as target vector */
   
      
       vec->info[0]  = buffer_address;    /* starting address for data copy         */
       vec->info[1]  = block_size;        /* bytes of data to copy                  */
       vec->info[2]  = stride;            /* distance from copy block to copy block */
       /* data will be copied as follows:                                           */
       /* block_size bytes will be copied from buffer_address                       */
       /* block_size bytes will be copied from buffer_address+stride                */
       /* block_size bytes will be copied from buffer_address+(2*stride)            */
       /* block_size bytes will be copied from buffer_address+(3*stride)            */
       .
       .
       .
       /* block_size bytes will be copied from buffer_address+((NUM_VECS-1)*stride) */
       .
       .
       .
       xfer_struct.Amv.Xfer_type = LAPI_AMV_XFER;
       xfer_struct.Amv.flags     = 0;
       xfer_struct.Amv.tgt       = tgt;
       xfer_struct.Amv.hdr_hdl   = hdr_hdl_list[tgt];
       xfer_struct.Amv.uhdr_len  = uhdr_len;  /* user header length */
       xfer_struct.Amv.uhdr      = uhdr;
   
   
       /* LAPI_AMV_XFER allows the use of a send completion handler */
       /* If non-null, the shdlr function is invoked at the point   */
       /* the origin counter would increment.  Note that both the   */
       /* org_cntr and shdlr can be used.                           */
       /* The user's shdlr must be of type scompl_hndlr_t *.        */
       /* scompl_hndlr_t is defined in /usr/include/lapi.h          */
       xfer_struct.shdlr = shdlr; 
   
       /* Use sinfo to pass user-defined data into the send         */
       /* completion handler, if desired.                           */
       xfer_struct.sinfo     = sinfo;       /* send completion data */
       
       xfer_struct.org_vec   = vec;
       xfer_struct.tgt_cntr  = tgt_cntr;
       xfer_struct.org_cntr  = org_cntr;
       xfer_struct.cmpl_cntr = cmpl_cntr;
   
   
       LAPI_Xfer(hndl, &xfer_struct);
       .
       .
       .
   }
   

有关头处理程序定义的更多信息，请参阅 LAPI_Amsendv 子例程。