LAPI_Getv Subroutine

Purpose

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

Library

Availability Library (liblapi_r.a)

C Syntax

#include <lapi.h>
 
int LAPI_Getv(hndl, tgt, tgt_vec, org_vec, tgt_cntr, org_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;


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_GETV(hndl, tgt, tgt_vec, org_vec, tgt_cntr, org_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
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)

This subroutine is the vector version of the LAPI_Get call. Use LAPI_Getv to transfer vectors of data from the target task to the origin task. Both the origin and target vector descriptions are located in the address space of the origin task. But, 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 origin buffers on the origin 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 any of the following requirements are not met, an error condition occurs:

The vector types org_vec->vec_type and tgt_vec->vec_type must be the same.
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 that is pointed to by tgt_vec must be equal to the length of the corresponding vector that is pointed to by org_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 origin side, the contents of the origin buffer are undefined after the operation.

See LAPI_Amsendv for details about commuication using different LAPI vector types. (LAPI_Getv 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 once the data buffer on the target can be modified. If the value of 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 after data arrives at the origin. If the value of this parameter is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN), the origin counter is not updated.
OUTPUT
ierror: Specifies a FORTRAN return code. This is always the last parameter.

C Examples

To get a LAPI_GEN_IOVECTOR:

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

      /* task that calls LAPI_Getv 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 write to    */
      /* 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 transfer    */     
      /* from vec->info[i]                                            */
      /* For LAPI_GEN_IOVECTOR, num_vecs, vec_type, and len must be   */ 
      /* the same                                                     */

      LAPI_Getv(hndl, tgt, tgt_vec, org_vec, tgt_cntr, org_cntr);
      /* tgt_cntr and org_cntr can both be NULL           */

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

}

For examples of other vector types, see LAPI_Amsendv.

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 size.
LAPI_ERR_ORG_VEC_ADDR: Indicates that some org_vec->info[i] is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN). but the corresponding length (org_vec->len[i]) is not 0.
LAPI_ERR_ORG_VEC_LEN: Indicates that the total sum of all org_vec->len[i] (where [i] is in the range 0 <= i <= org_vec->num_vecs) 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 base 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's stride is less than its block size.
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