LAPI_Util 子例程

#include <lapi.h>
 
int LAPI_Util(hndl, util_cmd)
lapi_handle_t hndl;
lapi_util_t *util_cmd;

include 'lapif.h'
 
LAPI_UTIL(hndl, util_cmd, ierror)
INTEGER hndl
TYPE (LAPI_UTIL_T) :: util_cmd
INTEGER ierror

此子例程用于多个不同的操作，这些操作由命令结构开头的命令类型值指示。 lapi_util_t 结构定义为:

typedef union {
    lapi_util_type_t    Util_type;  
    lapi_reg_dgsp_t     RegDgsp;    
    lapi_dref_dgsp_t    DrefDgsp;   
    lapi_resv_dgsp_t    ResvDgsp;   
    lapi_reg_ddm_t      DdmFunc;    
    lapi_add_udp_port_t Udp;        
    lapi_pack_dgsp_t    PackDgsp;   
    lapi_unpack_dgsp_t  UnpackDgsp;
    lapi_thread_func_t  ThreadFunc;
} lapi_util_t;

枚举类型 lapi_util_type_t 具有以下值:未针对命令类型 LAPI_REGISTER_DGSP， LAPI_RESERVE_DGSP或 LAPI_UNRESERVE_DGSP检查 hndl 。

LAPI_REGISTER_DGSP 使用 lapi_reg_dgsp_t 命令结构。

LAPI_RESERVE_DGSP 使用 lapi_resv_dgsp_t 命令结构。

LAPI_UNRESERVE_DGSP 使用 lapi_dref_dgsp_t 命令结构。

本机 LAPI 用户可以安装回调，而不会影响为 MPI_Accumulate注册的一个 MPI。 回调函数的函数原型为:

typedef long ddm_func_t (        /* return number of bytes processed */
        void      *in,           /* pointer to inbound data          */
        void      *inout,        /* pointer to destination space     */
        long      bytes,         /* number of bytes inbound          */
        int       operand,       /* CONTROL operand value            */
        int       operation      /* CONTROL operation value          */
);

LAPI_REG_DDM_FUNC 使用 lapi_reg_ddm_t 命令结构。 每个调用都将替换先前的函数指针 (如果有)。

LAPI_DGSP_PACK 使用 lapi_pack_dgsp_t 命令结构。

LAPI_DGSP_UNPACK 使用 lapi_unpack_dgsp_t 命令结构。

LAPI_ADD_UDP_DEST_PORT 使用 lapi_add_udp_port_t 命令结构。

LAPI_GET_THREAD_FUNC 使用 lapi_thread_func_t 命令结构。

Mutex lock function pointer

int (*lapi_mutex_lock_t)(lapi_handle_t hndl);

此函数获取与指定 LAPI 句柄关联的锁定。 如果锁定已由另一个线程挂起，那么调用将阻塞。 如果调用线程已持有锁定，那么可能会发生死锁。 您负责防止和检测死锁。

Parameters

INPUT

hndl

指定 LAPI 句柄。

Return values

0

指示已成功获取锁定。

EINVAL

如果由于 hndl 值不正确而导致锁定无效，那么将返回此值。

Mutex unlock function pointer

int (*lapi_mutex_unlock_t)(lapi_handle_t hndl);

此函数将释放与指定 LAPI 句柄关联的锁定。 线程应仅解锁其自己的锁定。

Parameters

INPUT

hndl

指定 LAPI 句柄。

Return values

0

指示锁定已成功释放。

EINVAL

如果由于 hndl 值不正确而导致锁定无效，那么将返回此值。

Mutex try lock function pointer

int (*lapi_mutex_trylock_t)(lapi_handle_t hndl);

此函数尝试获取与指定 LAPI 句柄关联的锁定， 但如果锁定已挂起，那么会立即返回 。

Parameters

INPUT

hndl

指定 LAPI 句柄。

Return values

0

指示已成功获取锁定。

EBUSY

指示正在挂起锁定。

EINVAL

如果由于 hndl 值不正确而导致锁定无效，那么将返回此值。

Mutex get owner function pointer

int (*lapi_mutex_getowner_t)(lapi_handle_t hndl, pthread_t *tid);

此函数获取当前持有与指定 LAPI 句柄关联的锁定的线程的 pthread 标识。 LAPI_NULL_THREAD_ID 指示在调用函数时未挂起锁定。

Parameters

INPUT

hndl

指定 LAPI 句柄。

输出

tid

是一个指针，用于保存要检索的 pthread 标识。

Return values

0

指示已成功检索锁定所有者。

EINVAL

如果由于 hndl 值不正确而导致锁定无效，那么将返回此值。

Condition wait function pointer

int (*lapi_cond_wait_t)(lapi_handle_t hndl, lapi_cond_t *cond);

此函数等待条件变量 (cond)。 在进行调用之前，用户必须持有与 LAPI 句柄 (hndl) 关联的锁定。 在返回调用时， LAPI 保证锁定仍处于挂起状态。 必须向同一条件变量上的并发 lapi_cond_wait_t 操作提供相同的 LAPI 句柄。

Parameters

INPUT

hndl

指定 LAPI 句柄。

连接

是要等待的条件变量的指针。

Return values

0

指示已向条件变量发出信号。

EINVAL

指示由 hndl 或 cond 指定的值无效。

Condition timed wait function pointer

int (*lapi_cond_timedwait_t)(lapi_handle_t hndl, 
                             lapi_cond_t *cond, 
                             struct timespec *timeout);

此函数等待条件变量 (cond)。 在进行调用之前，用户必须持有与 LAPI 句柄 (hndl) 关联的锁定。 在返回调用时， LAPI 保证锁定仍处于挂起状态。 必须向同一条件变量上的并发 lapi_cond_timedwait_t 操作提供相同的 LAPI 句柄。

Parameters

INPUT

hndl

指定 LAPI 句柄。

连接

是要等待的条件变量的指针。

超时

是一个指向指定超时的绝对时间结构的指针。

Return values

0

指示已向条件变量发出信号。

ETIMEDOUT

指示已经过 timeout 指定的时间。

EINVAL

指示由 hndl cond指定的值。 或 timeout 无效。

Condition signal function pointer

int (*lapi_cond_wait_t)(lapi_handle_t hndl, lapi_cond_t *cond);
typedef int (*lapi_cond_signal_t)(lapi_handle_t hndl, lapi_cond_t *cond);

此函数对条件变量 (cond) 发出信号，以唤醒在条件上阻塞的线程。 如果有多个线程在条件变量上等待，那么将随机决定要唤醒的线程。

Parameters

INPUT

hndl

指定 LAPI 句柄。

连接

是指向要发出信号的条件变量的指针。

Return values

0

指示已向条件变量发出信号。

EINVAL

指示由 hndl 或 cond 指定的值无效。

Initialize condition function pointer

int (*lapi_cond_init_t)(lapi_handle_t hndl, lapi_cond_t *cond);

此函数用于初始化条件变量。

Parameters

INPUT

hndl

指定 LAPI 句柄。

连接

是指向要初始化的条件变量的指针。

Return values

0

指示已成功初始化条件变量。

再次

指示系统缺少必要的资源 (内存除外) 来初始化另一个条件变量。

ENOMEM

指示没有足够的内存来初始化条件变量。

EINVAL

如果 hndl 值无效，那么将返回此值。

Destroy condition function pointer

int (*lapi_cond_destroy_t)(lapi_handle_t hndl, lapi_cond_t *cond);

此函数会破坏条件变量。

Parameters

INPUT

hndl

指定 LAPI 句柄。

连接

是指向要销毁的条件变量的指针。

Return values

0

指示已成功销毁条件变量。

EBUSY

指示实现在被引用 (例如在 lapi_cond_wait_t 或 lapi_cond_timedwait_t 中被另一个线程使用时) 时检测到试图破坏 cond 所引用的对象。

EINVAL

指示由 hndl 或 cond 指定的值无效。

1. 要创建和注册 DGSP ，请执行以下操作:

   
   {
         /*
         ** DGSP code array.  DGSP instructions are stored
         ** as ints (with constants defined in lapi.h for
         ** the number of integers needed to store each
         ** instruction).  We will have one COPY and one ITERATE
         ** instruction in our DGSP.  We use LAPI's constants
         ** to allocate the appropriate storage.
         */
         int code[LAPI_DGSM_COPY_SIZE+LAPI_DGSM_ITERATE_SIZE];
   
         /* DGSP description */
         lapi_dgsp_descr_t dgsp_d;
   
         /*
         ** Data structure for the xfer call.
         */
         lapi_xfer_t   xfer_struct;
   
      
         /* DGSP data structures */
         lapi_dgsm_copy_t     *copy_p;   /* copy instruction    */
         lapi_dgsm_iterate_t  *iter_p;   /* iterate instruction */
         int                  *code_ptr; /* code pointer        */
   
         /* constant for holding code array info */
         int                   code_less_iterate_size;
   
         /* used for DGSP registration */
         lapi_reg_dgsp_t     reg_util;
   
   
         /*
         ** Set up dgsp description
         */
   
         /* set pointer to code array */
         dgsp_d.code = &code[0];
   
         /* set size of code array */
         dgsp_d.code_size = LAPI_DGSM_COPY_SIZE + LAPI_DGSM_ITERATE_SIZE;
   
         /* not using DGSP gosub instruction */
         dgsp_d.depth = 1;
   
         /*
         ** set density to show internal gaps in the
         ** DGSP data layout
         */
         dgsp_d.density = LAPI_DGSM_SPARSE;
   
         /* transfer 4 bytes at a time */
         dgsp_d.size = 4;
   
         /* advance the template by 8 for each iteration */
         dgsp_d.extent = 8;
   
         /*
         ** ext specifies the memory 'footprint' of
         ** data to be transferred. The lext specifies
         ** the offset from the base address to begin
         ** viewing the data.  The rext specifies the
         ** length from the base address to use.
         */
         dgsp_d.lext = 0;
         dgsp_d.rext = 4;
         /* atom size of 0 lets LAPI choose the packet size */
         dgsp_d.atom_size = 0;
   
         /*
         ** set up the copy instruction
         */
         copy_p = (lapi_dgsm_copy_t *)(dgsp_d.code);
         copy_p->opcode = LAPI_DGSM_COPY;
   
         /* copy 4 bytes at a time */
         copy_p->bytes = (long) 4;
   
         /* start at offset 0 */
         copy_p->offset = (long) 0;
   
         /* set code pointer to address of iterate instruction */
         code_less_iterate_size =  dgsp_d.code_size - LAPI_DGSM_ITERATE_SIZE;
         code_ptr = ((int *)(code))+code_less_iterate_size;
   
         /*
         ** Set up iterate instruction
         */
         iter_p = (lapi_dgsm_iterate_t *) code_ptr;
         iter_p->opcode = LAPI_DGSM_ITERATE;
         iter_p->iter_loc = (-code_less_iterate_size);
   
         /* Set up and do DGSP registration */
         reg_util.Util_type = LAPI_REGISTER_DGSP;
         reg_util.idgsp = &dgsp_d;
         LAPI_Util(hndl, (lapi_util_t *)&reg_util);
   
         /* 
         ** LAPI returns a usable DGSP handle in 
         ** reg_util.dgsp_handle
         ** Use this handle for subsequent reserve/unreserve
         ** and Xfer calls.  On the receive side, this
         ** handle can be returned by the header handler using the 
         ** return_info_t mechanism.  The DGSP will then be used for
         ** scattering data.
         */
         
   }
   

2. 要保留 DGSP 句柄:

   
   {
   	
         reg_util.dgsp_handle = dgsp_handle;
   
         /* 
         ** dgsp_handle has already been created and
         ** registered as in the above example
         */
   
         reg_util.Util_type = LAPI_RESERVE_DGSP;
         LAPI_Util(hndl, (lapi_util_t *)&reg_util);
   
         /*
         ** LAPI's internal reference count to dgsp_handle
         ** will be incremented.  DGSP will
         ** remain available until an unreserve is
         ** done for each reserve, plus one more for
         ** the original registration.
         */
   
   }
   

3. 要取消保留 DGSP 句柄:

   
   {
   	
         reg_util.dgsp_handle = dgsp_handle;
   
         /* 
         ** dgsp_handle has already created and
         ** registered as in the above example, and
         ** this thread no longer needs it.
         */
   
         reg_util.Util_type = LAPI_UNRESERVE_DGSP;
         LAPI_Util(hndl, (lapi_util_t *)&reg_util);
   
         /*
         ** An unreserve is required for each reserve,
         ** plus one more for the original registration.
         */
   
   }