LAPI_Xfer Subroutine

Purpose

Serves as a wrapper function for LAPI data transfer functions.

Library

Availability Library (liblapi_r.a)

C Syntax

#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);
 

FORTRAN Syntax

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

Description

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

The LAPI_Xfer subroutine provides a superset of the functionality of these subroutines: LAPI_Amsend, LAPI_Amsendv, LAPI_Put, LAPI_Putv, LAPI_Get, LAPI_Getv, and LAPI_Rmw. In addition, LAPI_Xfer provides data gather/scatter program (DGSP) messages transfer.

In C, the LAPI_Xfer command is passed a pointer to a union. It examines the first member of the union, Xfer_type, to determine the transfer type, and to determine which union member was passed. LAPI_Xfer expects every field of the identified union member to be set. It does not examine or modify any memory outside of the identified union member. LAPI_Xfer treats all union members (except status) as read-only data.

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_am_t details

lapi_amv_t details

lapi_amdgsp_t details

When the origin data buffer is free to be modified, the send completion handler (shdlr) is called with the send completion data (sinfo), if shdlr is not a NULL pointer (in C) or LAPI_ADDR_NULL (in FORTRAN).

See Using lapi_am_dgsp_t for scatter-side DGSP processing for more information.

The lapi_amdgsp_t flags field

One or more flags can be set using the | (bitwise or) operator. User directives are always followed and could result in incorrect results if used improperly. Appropriate hints might improve performance, but they may be ignored by LAPI. Inappropriate hints might degrade performance, but they will not cause incorrect results.

These hints may or may not be honored by the communication library.

Using lapi_am_dgsp_t for scatter-side DGSP processing

Beginning with AIX® 5.2, LAPI allows additional information to be returned from the header handler through the use of the lapi_return_info_t datatype. See RSCT for AIX 5L™: LAPI Programming Guide for more information about lapi_return_info_t. In the case of transfer type lapi_am_dgsp_t, this mechanism can be used to instruct LAPI to run a user DGSP to scatter data on the receive side.

To use this mechanism, pass a lapi_return_info_t * pointer back to LAPI through the msg_len member of the user header handler. The dgsp_handle member of the passed structure must point to a DGSP description that has been registered on the receive side. See LAPI_Util and RSCT for AIX 5L: LAPI Programming Guide for details on building and registering DGSPs.

lapi_get_t details

lapi_getv_t details

When the origin data buffer has completely arrived, the pointer to the completion handler (chndlr) is called with the completion data (cinfo) if chndlr is not a NULL pointer (in C) or LAPI_ADDR_NULL (in FORTRAN). Otherwise, the behavior is identical to that of LAPI_Getv.

lapi_put_t details

lapi_putv_t details

When the origin data buffer is free to be modified, the pointer to the send completion handler (shdlr) is called with the send completion data (sinfo), if shdlr is not a NULL pointer (in C) or LAPI_ADDR_NULL (in FORTRAN). Otherwise, the behavior is identical to that of LAPI_Putv.

lapi_rmw_t details

Parameters

INPUT

hndl

Specifies the LAPI handle.

xfer_cmd

Specifies the name and parameters of the data transfer function.

OUTPUT

ierror

Specifies a FORTRAN return code. This is always the last parameter.

Return Values

LAPI_SUCCESS

Indicates that the function call completed successfully.

LAPI_ERR_DATA_LEN

Indicates that the value of udata_len or len is greater than the value of LAPI constant LAPI_MAX_MSG_SZ.

LAPI_ERR_DGSP

Indicates that the DGSP that was passed in is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN) or is not a registered DGSP.

LAPI_ERR_DGSP_ATOM

Indicates that the DGSP has an atom_size that is less than 0 or greater than MAX_ATOM_SIZE.

LAPI_ERR_DGSP_BRANCH

Indicates that the DGSP attempted a branch that fell outside the code array.

LAPI_ERR_DGSP_CTL

Indicates that a DGSP control instruction was encountered in a non-valid context (such as a gather-side control or scatter-side control with an atom size of 0 at gather, for example).

LAPI_ERR_DGSP_OPC

Indicates that the DGSP op-code is not valid.

LAPI_ERR_DGSP_STACK

Indicates that the DGSP has greater GOSUB depth than the allocated stack supports. Stack allocation is specified by the dgsp->depth member.

LAPI_ERR_HDR_HNDLR_NULL

Indicates that the hdr_hdl passed in is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN).

LAPI_ERR_HNDL_INVALID

Indicates that the hndl passed in is not valid (not initialized or in terminated state).

LAPI_ERR_IN_VAL_NULL

Indicates that the in_val pointer is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN).

LAPI_ERR_MEMORY_EXHAUSTED

LAPI is unable to obtain memory from the system.

LAPI_ERR_OP_SZ

Indicates that the lapi_rmw_t size field is not set to 32 or 64.

LAPI_ERR_ORG_ADDR_NULL

Indicates either that the udata parameter passed in is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN) and udata_len is greater than 0, or that the org_addr passed in is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN) and len is greater than 0.

Note: if Xfer_type = LAPI_DGSP_XFER, the case in which udata is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN) and udata_len is greater than 0 is valid, so an error is not returned.

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 value 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_RMW_OP

Indicates the op 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_ADDR_NULL

Indicates that ret_addr is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN).

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_VAR_NULL

Indicates that the tgt_var address is NULL (in C) or that the value of tgt_var is LAPI_ADDR_NULL (in FORTRAN).

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_UHDR_LEN

Indicates that the uhdr_len value passed in is greater than MAX_UHDR_SZ or is not a multiple of the processor's doubleword size.

LAPI_ERR_UHDR_NULL

Indicates that the uhdr passed in is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN), but uhdr_len is not 0.

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).

LAPI_ERR_XFER_CMD

Indicates that the Xfer_cmd is not valid.

C Examples

Location

/usr/lib/liblapi_r.a