LAPI_Put Subroutine

Purpose

Transfers data from a local task to a remote task.

Library

Availability Library (liblapi_r.a)

C Syntax

#include <lapi.h>
 
int LAPI_Put(hndl, tgt, len, tgt_addr, org_addr, tgt_cntr, org_cntr, cmpl_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;
lapi_cntr_t  *cmpl_cntr;

FORTRAN Syntax

include 'lapif.h'
 
int LAPI_PUT(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 org_addr
INTEGER (KIND=LAPI_ADDR_TYPE) :: tgt_cntr
TYPE (LAPI_CNTR_T) :: org_cntr
TYPE (LAPI_CNTR_T) :: cmpl_cntr
INTEGER ierror

Description

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

Use this subroutine to transfer data from a local (origin) task to a remote (target) task. The origin counter will increment on the origin task upon origin buffer availability. The target counter will increment on the target and the completion counter will increment at the origin task upon message completion. Because there is no completion handler, message completion and target buffer availability are the same in this case.

This is a non-blocking call. The caller cannot assume that the data transfer has completed upon the return of the function. Instead, counters should be used to ensure correct buffer accesses 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. The value of this parameter must be in the range 0 <= tgt < NUM_TASKS.

len

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

tgt_addr

Specifies the address on the target task where data is to be copied into. If len is 0, The value of this parameter can be NULL (in C) or LAPI_ADDR_NULL (in FORTRAN).

org_addr

Specifies the address on the origin task from which data is to be copied. 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 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

{

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

    /* transfer data_len bytes from local address data_buffer.     */
    /* write the data starting at address data_buffer_list[tgt] on */
    /* task tgt. tgt_cntr, org_cntr, and compl_cntr can be NULL.   */

}

Return Values

LAPI_SUCCESS

Indicates that the function call completed successfully.

LAPI_ERR_DATA_LEN

Indicates that the value of 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 parameter 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 parameter 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