LAPI_Putv Subroutine

Purpose

Transfers vectors of data from a local task to a remote task.

Library

Availability Library (liblapi_r.a)

C Syntax

#include <lapi.h>
 
int LAPI_Putv(hndl, tgt, tgt_vec, org_vec, tgt_cntr, org_cntr, cmpl_cntr)
 
lapi_handle_t  hndl;
uint           tgt;
lapi_vec_t    *tgt_vec;
lapi_vec_t    *org_vec;
lapi_cntr_t   *tgt_cntr;
lapi_cntr_t   *org_cntr;
lapi_cntr_t   *cmpl_cntr;


typedef struct  {
    lapi_vectype_t  vec_type;   /* operation code        */
    uint            num_vecs;   /* number of vectors     */
    void            **info;     /* vector of information */
    ulong           *len;       /* vector of lengths     */
} lapi_vec_t;

FORTRAN Syntax

include 'lapif.h'
 
LAPI_PUTV(hndl, tgt, tgt_vec, org_vec, tgt_cntr, org_cntr , cmpl_cntr, ierror)
INTEGER hndl
INTEGER tgt
INTEGER (KIND=LAPI_ADDR_TYPE) :: tgt_vec
TYPE (LAPI_VEC_T) :: org_vec
INTEGER (KIND=LAPI_ADDR_TYPE) :: tgt_cntr
TYPE (LAPI_CNTR_T) :: org_cntr
TYPE (LAPI_CNTR_T) :: cmpl_cntr
INTEGER ierror

The 32-bit version of the LAPI_VEC_T type is defined as:

TYPE LAPI_VEC_T
   SEQUENCE
   INTEGER(KIND = 4)  :: vec_type
   INTEGER(KIND = 4)  :: num_vecs
   INTEGER(KIND = 4)  :: info
   INTEGER(KIND = 4)  :: len
END TYPE LAPI_VEC_T

The 64-bit version of the LAPI_VEC_T type is defined as:

TYPE LAPI_VEC_T
   SEQUENCE
   INTEGER(KIND = 4)  :: vec_type
   INTEGER(KIND = 4)  :: num_vecs
   INTEGER(KIND = 8)  :: info
   INTEGER(KIND = 8)  :: len
END TYPE LAPI_VEC_T

Description

Type of call: point-to-point communication (non-blocking)

LAPI_Putv is the vector version of the LAPI_Put call. Use this subroutine to transfer vectors of data from the origin task to the target task. The origin vector descriptions and the target vector descriptions are located in the address space of the origin task. However, the values specified in the info array of the target vector must be addresses in the address space of the target task.

The calling program cannot assume that the origin buffer can be changed or that the contents of the target buffers on the target task are ready for use upon function return. After the origin counter (org_cntr) is incremented, the origin buffers can be modified by the origin task. After the target counter (tgt_cntr) is incremented, the target buffers can be modified by the target task. If you provide a completion counter (cmpl_cntr), it is incremented at the origin after the target counter (tgt_cntr) has been incremented at the target. If the values of any of the counters or counter addresses are NULL (in C) or LAPI_ADDR_NULL (in FORTRAN), the data transfer occurs, but the corresponding counter increments do not occur.

If a strided vector is being transferred, the size of each block must not be greater than the stride size in bytes.

The length of any vector pointed to by org_vec must be equal to the length of the corresponding vector pointed to by tgt_vec.

LAPI does not check for any overlapping regions among vectors either at the origin or the target. If the overlapping regions exist on the target side, the contents of the target buffer are undefined after the operation.

See LAPI_Amsendv for more information about using the various vector types. (LAPI_Putv does not support the LAPI_GEN_GENERIC type.)

Parameters

INPUT
hndl: Specifies the LAPI handle.
tgt: Specifies the task ID of the target task. The value of this parameter must be in the range 0 <= tgt < NUM_TASKS.
tgt_vec: Points to the target vector description.
org_vec: Points to the origin vector description.
INPUT/OUTPUT
tgt_cntr: Specifies the target counter address. The target counter is incremented upon message completion. If this parameter is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN), the target counter is not updated.
org_cntr: Specifies the origin counter address (in C) or the origin counter (in FORTRAN). The origin counter is incremented at buffer availability. If this parameter is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN), the origin counter is not updated.
cmpl_cntr: Specifies the completion counter address (in C) or the completion counter (in FORTRAN) that is a reflection of tgt_cntr. The completion counter is incremented at the origin after tgt_cntr is incremented. If this parameter is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN), the completion counter is not updated.
OUTPUT
ierror: Specifies a FORTRAN return code. This is always the last parameter.

C Examples

To put a LAPI_GEN_IOVECTOR:

{
      
      /* retrieve a remote data buffer address for data to transfer,  */ 
      /* such as through LAPI_Address_init                            */

      /* task that calls LAPI_Putv sets up both org_vec and tgt_vec   */
      org_vec->num_vecs = NUM_VECS;
      org_vec->vec_type = LAPI_GEN_IOVECTOR;
      org_vec->len      = (unsigned long *) 
      malloc(NUM_VECS*sizeof(unsigned long));
      org_vec->info     = (void **) malloc(NUM_VECS*sizeof(void *));

      /* each org_vec->info[i] gets a base address on the origin task */
      /* each org_vec->len[i] gets the number of bytes to transfer    */
      /* from org_vec->info[i]                                        */

      tgt_vec->num_vecs = NUM_VECS;
      tgt_vec->vec_type = LAPI_GEN_IOVECTOR;
      tgt_vec->len      = (unsigned long *) 
      malloc(NUM_VECS*sizeof(unsigned long));
      tgt_vec->info     = (void **) malloc(NUM_VECS*sizeof(void *));

      /* each tgt_vec->info[i] gets a base address on the target task           */
      /* each tgt_vec->len[i] gets the number of bytes to write to vec->info[i] */
      /* For LAPI_GEN_IOVECTOR, num_vecs, vec_type, and len must be the same    */ 

      LAPI_Putv(hndl, tgt, tgt_vec, org_vec, tgt_cntr, org_cntr, compl_cntr);
      /* tgt_cntr, org_cntr and compl_cntr can all be NULL */

      /* data will be transferred as follows:              */
      /* org_vec->len[0] bytes will be retrieved from      */ 
      /* org_vec->info[0] and written to tgt_vec->info[0]  */
      /* org_vec->len[1] bytes will be retrieved from      */
      /* org_vec->info[1] and written to tgt_vec->info[1]  */
      .
      .
      .
      /* org_vec->len[NUM_VECS-1] bytes will be retrieved */
      /* from org_vec->info[NUM_VECS-1] and written to    */
      /* tgt_vec->info[NUM_VECS-1]                        */

}

See the example in LAPI_Amsendv for information on other vector types.

Return Values

LAPI_SUCCESS: Indicates that the function call completed successfully.
LAPI_ERR_HNDL_INVALID: Indicates that the hndl passed in is not valid (not initialized or in terminated state).
LAPI_ERR_ORG_EXTENT: Indicates that the org_vec's extent (stride * num_vecs) is greater than the value of LAPI constant LAPI_MAX_MSG_SZ.
LAPI_ERR_ORG_STRIDE: Indicates that the org_vec stride is less than block.
LAPI_ERR_ORG_VEC_ADDR: Indicates that the org_vec->info[i] is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN), but its length (org_vec->len[i]) is not 0.
LAPI_ERR_ORG_VEC_LEN: Indicates that the sum of org_vec->len is greater than the value of LAPI constant LAPI_MAX_MSG_SZ.
LAPI_ERR_ORG_VEC_NULL: Indicates that the org_vec is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN).
LAPI_ERR_ORG_VEC_TYPE: Indicates that the org_vec->vec_type is not valid.
LAPI_ERR_STRIDE_ORG_VEC_ADDR_NULL: Indicates that the strided vector address org_vec->info[0] is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN).
LAPI_ERR_STRIDE_TGT_VEC_ADDR_NULL: Indicates that the strided vector address tgt_vec->info[0] is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN).
LAPI_ERR_TGT: Indicates that the tgt passed in is outside the range of tasks defined in the job.
LAPI_ERR_TGT_EXTENT: Indicates that tgt_vec's extent (stride * num_vecs) is greater than the value of LAPI constant LAPI_MAX_MSG_SZ.
LAPI_ERR_TGT_PURGED: Indicates that the subroutine returned early because LAPI_Purge_totask() was called.
LAPI_ERR_TGT_STRIDE: Indicates that the tgt_vec stride is less than block.
LAPI_ERR_TGT_VEC_ADDR: Indicates that the tgt_vec->info[i] is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN), but its length (tgt_vec->len[i]) is not 0.
LAPI_ERR_TGT_VEC_LEN: Indicates that the sum of tgt_vec->len is greater than the value of LAPI constant LAPI_MAX_MSG_SZ.
LAPI_ERR_TGT_VEC_NULL: Indicates that tgt_vec is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN).
LAPI_ERR_TGT_VEC_TYPE: Indicates that the tgt_vec->vec_type is not valid.
LAPI_ERR_VEC_LEN_DIFF: Indicates that org_vec and tgt_vec have different lengths (len[ ]).
LAPI_ERR_VEC_NUM_DIFF: Indicates that org_vec and tgt_vec have different num_vecs.
LAPI_ERR_VEC_TYPE_DIFF: Indicates that org_vec and tgt_vec have different vector types (vec_type).

Location

/usr/lib/liblapi_r.a