LAPI_Get Subroutine

Purpose

Copies data from a remote task to a local task.

Library

Availability Library (liblapi_r.a)

C Syntax

#include <lapi.h>
 
int LAPI_Get(hndl, tgt, len, tgt_addr, org_addr, tgt_cntr, org_cntr)
lapi_handle_t hndl;
uint          tgt;
ulong         len;
void         *tgt_addr;
void         *org_addr;
lapi_cntr_t  *tgt_cntr;
lapi_cntr_t  *org_cntr;

FORTRAN Syntax

include 'lapif.h'
 
LAPI_GET(hndl, tgt, len, tgt_addr, org_addr, tgt_cntr, org_cntr, ierror)
INTEGER hndl
INTEGER tgt
INTEGER (KIND=LAPI_LONG_TYPE) :: len		
INTEGER (KIND=LAPI_ADDR_TYPE) :: tgt_addr
INTEGER (KIND=LAPI_ADDR_TYPE) :: org_addr
INTEGER (KIND=LAPI_ADDR_TYPE) :: tgt_cntr
TYPE (LAPI_CNTR_T) :: org_cntr
INTEGER ierror

Description

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

Use this subroutine to transfer data from a remote (target) task to a local (origin) task. Note that in this case the origin task is actually the receiver of the data. This difference in transfer type makes the counter behavior slightly different than in the normal case of origin sending to target.

The origin buffer will still increment on the origin task upon availability of the origin buffer. But in this case, the origin buffer becomes available once the transfer of data is complete. Similarly, the target counter will increment once the target buffer is available. Target buffer availability in this case refers to LAPI no longer needing to access the data in the buffer.

This is a non-blocking call. The caller cannot assume that data transfer has completed upon the return of the function. Instead, counters should be used to ensure correct buffer addresses as defined above.

Note that a zero-byte message does not transfer data, but it does have the same semantic with respect to counters as that of any other message.

Parameters

INPUT

hndl

Specifies the LAPI handle.

tgt

Specifies the task ID of the target task that is the source of the data. The value of this parameter must be in the range 0 <= tgt < NUM_TASKS.

len

Specifies the number of bytes of data to be copied. This parameter must be in the range 0 <= len <= the value of LAPI constant LAPI_MAX_MSG_SZ.

tgt_addr

Specifies the target buffer address of the data source. If len is 0, The value of this parameter can be NULL (in C) or LAPI_ADDR_NULL (in FORTRAN).

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

org_addr

Specifies the local buffer address into which the received data is copied. If len is 0, The value of this parameter can be NULL (in C) or LAPI_ADDR_NULL (in FORTRAN).

ierror

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

C Examples

{
    /* initialize the table buffer for the data addresses */
    
    /* get remote data buffer addresses                   */
    LAPI_Address_init(hndl,(void *)data_buffer,data_buffer_list);
    .    
    . 
    .    
    LAPI_Get(hndl, tgt, (ulong) data_len, (void *) (data_buffer_list[tgt]),
             (void *) data_buffer, tgt_cntr, org_cntr);  

    /* 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. */ 
}

Return Values

LAPI_SUCCESS

Indicates that the function call completed successfully.

LAPI_ERR_DATA_LEN

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

LAPI_ERR_HNDL_INVALID

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

LAPI_ERR_ORG_ADDR_NULL

Indicates that the org_addr passed in is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN), but len is greater than 0.

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 the tgt_addr passed in is NULL (in C) or LAPI_ADDR_NULL (in FORTRAN), but len is greater than 0.

LAPI_ERR_TGT_PURGED

Indicates that the subroutine returned early because LAPI_Purge_totask() was called.

Location

/usr/lib/liblapi_r.a