IBM Books

Command and Technical Reference, Volume 2

LAPI_Getv subroutine

Purpose

LAPI_Getv - Copies vectors of data from a remote process to the address space of the local process.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
int LAPI_Getv(hndl, tgt, tgt_vec, org_vec, tcntr, ocntr)
lapi_handle_t hndl;
uint tgt;
lapi_vec_t *tgtz_vec;
lapi_vec_t *org_vec;
lapi_cntr_t *tcntr;
lapi_cntr_t *ocntr;

FORTRAN Syntax

| include 'lapif.h'
| 
|LAPI_GETV(hndl, tgt, tgt_vec, org_vec, tcntr, ocntr, ierror)
|INTEGER hndl
|INTEGER tgt
|TYPE (LAPI_VEC_T) :: tgt_vec
|TYPE (LAPI_VEC_T) :: org_vec
|TYPE (LAPI_CNTR_T) :: tcntr, ocntr
|INTEGER ierror
| 

Parameters

hndl
IN Specifies the LAPI context.

tgt
IN Specifies the target process.

tgt_vec
IN Points to the target i/o vector description.

org_vec
IN Points to the origin i/o vector description.

tcntr
IN Specifies the address of the target counter. This parameter can be NULL.

ocntr
IN/OUT Specifies the address of the origin counter. This parameter can be NULL.

ccntr
IN/OUT Specifies the address of the completion counter. This parameter can be NULL.

ierror
OUT Specifies the FORTRAN return code. It is always the last parameter.

Description

This function transfers data from the target process address space from locations and lengths described in the tgt_vec to the origin process address space in locations and lengths described in the org_vec. Both structures, org_vec and tgt_vec, are located in the origin process address space, but the addresses of the actual vector locations in tgt_vec refer to addresses in the target address space.

This is a non-blocking call in that the calling program may not assume that the origin buffer can be changed, nor that contents of origin buffers (described in org_vec) on the origin process is ready for use. Further, the user may not assume that the structures, org_vec and tgt_vec, can be changed before the origin counter and target counter, respectively, are incremented. After the origin counter ocntr is incremented the origin buffers (described in org_vec) and org_vec can be reused by the origin process. After the target counter tcntr is incremented the target buffers (described in tgt_vec) and tgt_vec can be reused by the target process. If the any of the counters are NULL, the data transfer happens, but the corresponding counter increments do not take place.

The vector types org_vec->vec_type and tgt_vec->vec_type must be the same. The number of vectors specified in the num_vecs member must be the same on both the origin and target. If a strided vector is being transferred, the size of each block must not be greater than the stride size in bytes. The number of vectors to be transferred must be greater than zero. The length of any vector pointed to by tgt_vec must not be greater than the length of the corresponding vector pointed to by org_vec. The vector lengths specified in org_vec-> len, or org_vec->info in the strided transfer case, must be multiples of the machine word size in bytes. If any of these requirements are not satisfied, an error condition occurs.

LAPI does not check for any overlapping regions among vectors either at the origin or the target. If such overlapping regions exist on the target side, there may be a degradation in performance. If the overlapping regions exist on the origin side, the contents of origin buffer are undefined.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_PURGED_TASK
Returned early due to LAPI_Purge_totask() being called.

LAPI_ERR_BAD_PARAMETER
A parameter passed in was not valid.

Location

/usr/lib/liblapi_r.a

Prerequisite Information

Refer to the "Understanding the Communications Low-Level Application Programming Interface" section in PSSP: Administration Guide for additional LAPI information.

Related Information

Subroutines: LAPI_Amsendv, LAPI_Fence, LAPI_Generic amsendv, LAPI_Get, LAPI_Getcntr, LAPI_Putv, LAPI_Qenv, LAPI_Waitcntr

LAPI_Init subroutine

Purpose

LAPI_Init - Initializes the Low-Level Application Programming Interface (LAPI) subsystem.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
int LAPI_Init(hndl, lapi_info)
lapi_handle_t *hndl;
lapi_info_t *lapi_info;

FORTRAN Syntax

| include 'lapif.h'
| 
|LAPI_INIT(hndl, lapi_info, ierror)
|INTEGER hndl
|TYPE (LAPI_INFO_T) :: lapi_info
|INTEGER ierror
| 

Parameters

hndl
OUT Specifies a particular LAPI context. This parameter cannot be NULL.

lapi_info
IN/OUT Specifies a structure that provides the parallel job information that this LAPI context is associated with. This parameter cannot be NULL.

ierror
OUT FORTRAN return code. It is always the last argument.

Description

Use this subroutine to instantiate a new context of the LAPI subsystem and to initialize it. A handle to the newly-created LAPI context is returned in hndl. All subsequent LAPI calls can use hndl to specify the context of the LAPI operation. The lapi_info structure (lapi_info_t) needs to be zeroed out prior to filling in fields. |To do this, use this statement: bzero (lapi_info, size of |(lapi_info_t)). "Future support" fields should not be used since names of those fields may change.

typedef struct              {                /* Not in use currently */
        lapi_dev_t          protocol;        /* OUT - Which protocol is
                                                      initialized */
        lapi_lib_t          lib_vers;        /* IN -  LAPI library version -
                                                      user supplied */
        uint                epoch_num;       /* IN/ - first 15 bits used to
                                                      solve trickle traffic
                                                      problems in comm group */
        int                 info4;           /* IN -  Future support*/
        int                 info5;           /* Future support */
        int                 info6;           /* Future support */
        LAPI_err_hndlr      *err_hndlr;      /* IN - User registered error
                                                handler */
        comm_thread_info_t  *lapi_thread_attr;   /* support thread attr and init
                                                    function */
        void                *info_info3;     /* Future support */
        void                *info_info4;     /* Future support */
}      lapi_info_t;
void   (User func name)     (lapi handle t *hndl,    /* LAPI handle */
                            int *error code,         /* Error code */
                            lapi err t *err type,    /* GET/PUT/RMW/AM/INTERNAL*/
                            int *task id,            /* Current node */
                            int *src);               /* Source node */ 

Error code (*error_code) of LAPI _ERR_TIMEOUT is a recoverable error if the user chooses to ignore it in the user's error handler. All other error codes are currently terminal and the user should do clean up processing of user's process and terminate the process (exit()).

Note:
|Starting with PSSP 3.2, set lib_vers to |L2_LIB. Prior versions of PSSP assume that lib_vers is |L1_LIB. The user must register an error handler through the |lapi_info structure. You need to create a function with the |parameters defined for LAPI_err_hndlr. The epoch_num |variable is used by LAPI to distinguish a packet of one session from another |to avoid possible trickle traffic problem if the same epoch number is used |during back to back runs. It should be no greater than size of SHORT |(16bits). To set this during the run use the LAPI_Senv() |(EPOCH_NUM) function call. To retrieve the current epoch number use the |LAPI_Qenv() (EPOCH_NUM) function call. The lapi |_thread_att variable enables the user to pass to the communication |threads their own pthread attribute and also have the communication |thread. Except for LAPI_Address() and LAPI_Msg_string |(), the user cannot make any LAPI calls before calling LAPI_Init |(). |

Return Values

LAPI_SUCCESS
Indicates successful completion.

EBUSY
System error; the previous job is still running.

EINVAL
System error; an argument is not valid.

EPERM
System error; the caller is not authorized to perform the action.

ETIMEDOUT
System error; the switch network is not up.

ENODEV
System error; the adapter type and library do not match.

ENOSPC
System error; cannot attach to bus memory; out of memory or segment register.

CSS_KE_INTERNAL_ERROR
System error; kernel extension internal memory management encountered an error.

CSS_KE_UCODE ERROR
System error; adapter microcode is not responding.

LAPI_ERR_UNKNOWN DEVICE
The device is not supported.

LAPI_ERR_NOMORE_PORTS
There are no more communication ports available.

LAPI_ERR_INIT_FAILED
Initialization was unsuccessful.

LAPI_ERR_OPEN_FAILED
Opening of a communication device was unsuccessful.

LAPI_ERR_BAD_PARAMETER
A parameter passed in is not valid.

LAPI_ERR_NONZERO_INFO
Future support fields in lapi_info_t need to be set to zero.

LAPI_ERR_INVALID_OPTIONS
Was unsuccessful at getting network connections.

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Term

LAPI_Msg_string subroutine

Purpose

LAPI_Msg_string - Gets the Low-Level Application Programming Interface (LAPI) and system message string.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
LAPI_Msg_string(error_code, buf)
int error_code;
void * buf;

FORTRAN Syntax

 include 'lapif.h'
 
LAPI_MSG_STRING(error_code, buf, ierror)
INTEGER error_code
INTEGER buf(40)
INTEGER ierror

Parameters

error_code
IN Specifies the return value of a previous LAPI call.

buf
OUT Specifies the buffer to store the message string.

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

Use this subroutine to return the message string representation of the return value for a specific LAPI call.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_BAD_PARAMETER
Indicates that a parameter was passed in that was not valid.

Location

/usr/lib/liblapi_r.a

Prerequisite Information

Refer to the "Understanding the Communications Low-Level Application Programming Interface" chapters in PSSP: Administration Guide for additional LAPI information.

Related Information

Subroutines: LAPI_Init, LAPI_Term

LAPI_Nopoll_wait subroutine

Purpose

LAPI_Nopoll_wait - Provides a counter value and a list of threads and state to be updated once the counter value is reached.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
void LAPI_Nopoll_wait(hndl, cntr_ptr, val, cur_cntr_val)
lapi_handle_t hndl;
lapi_cntr_t *cntr_ptr;
int val;
int *cur_cntr_val;
 

FORTRAN Syntax

| include 'lapif.h'
| 
|int LAPI_NOPOLL_WAIT(HNDL, CNTR_PTR, VAL, CUR_CNTR_VAL, IERROR)
|INTEGER hndl
|TYPE (LAPI_CNTR_T) :: cntr_ptr
|INTEGER val
|INTEGER cur_cntr_val
|INTEGER ierror

Parameters

hndl
IN Handle to the LAPI instance.

*cntr_ptr
IN/OUT Pointer to the lapi_cntr_t structure.

val
IN The relative counter value starting from 1 to be reached before returning.

*cur_cntr_val
IN Returns the current integer value of counter if not NULL.

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

This function first checks if the state of counter is WAIT. It returns immediately with a return error of LAPI_ERR_MULTIPLE_WAITERS if it is already in a WAIT state. Then it checks if the counter values for val and *cntr_ptr are the same and returns immediately if the value has been reached. Otherwise, it records in the lapi_cntr_t (*cntr_ptr) structure the value to be reached. There are two fields associated with the counter; *dest_list and *dest_status array of size val or NULL. *dest_list and *dest_status arrays record task IDs from which the calling thread is waiting for a response. These fields should only be set using LAPI_Setcntr_wstatus. This function will immediately return with a return value of LAPI_ERR_PURGED_TASK if the destinations are purged. If *dest_list is NULL then the behavior of LAPI_Purge_totask is to wake up all the threads that were sleeping in the LAPI_Nopoll_wait.

Note:
To use this function you must have the lib_vers field of lapi_info_t in LAPI_Init set to L2_LIB.

Return Values

LAPI_SUCCESS
Indicates the state was successfully reset.

LAPI_ERR_PURGED_TASK
Returned early due to LAPI_Purge_totask being called.

LAPI_ERR_MULTIPLE_WAITERS
More than one thread is waiting for the counter.

LAPI_ERR_BAD_PARAMETER
A parameter passed in was not valid.

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Purge_totask, LAPI_Resume_totask, LAPI_Setcntr_wstatus

LAPI_Probe subroutine

Purpose

LAPI_Probe - Transfers control to the communications subsystem to check for arriving messages and to make progress in polling mode.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
int LAPI_Probe(hndl)
lapi_handle_t hndl;
 

FORTRAN Syntax

 include 'lapif.h'
 
int LAPI_PROBE(HNDL, IERROR)
INTEGER hndl
INTEGER ierror

Parameters

hndl
IN Specifies the LAPI context.

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

Use this subroutine to transfer control to the communications subsystem to make progress on messages associated with the context hndl.

Note:
There is no guarantee about receipt of messages on the return from this function.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_BAD_PARAMETER
A parameter passed in was not valid.

Prerequisite Information

Refer to the "Understanding the Communications Low-Level Application Programming Interface" chapter in PSSP: Administration Guide for additional LAPI information.

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Getcntr, LAPI_Setcntr, LAPI_Waitcntr

LAPI_Purge_totask subroutine

Purpose

LAPI_Purge_totask - Allows a process to cancel messages to a given destination.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
int LAPI_Purge_totask(hndl, dest)
lapi_handle_t hndl;
task_t dest; 

FORTRAN Syntax

 include 'lapif.h'
 
int LAPI_PURGE_TOTASK(hndl, dest, ierror)
INTEGER hndl
INTEGER dest
INTEGER ierror

Parameters

hndl
IN Specifies the LAPI context.

dest
IN Specifies the destination instance ID to which pending messages need to be cancelled.

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

This function cancels messages and resets the state corresponding to messages in flight or submitted to be sent to a particular target task. This is an entirely local operation. For correct behavior a similar invocation is expected on the destination (if it exists). This function cleans up all the state associated with pending messages to the indicated target task. It is assumed that before the indicated task starts communicating with this task again, it also purges this instance (or that it was terminated and initialized again). It will also wake up all threads that are in LAPI_Nopoll_wait depending on how the arguments are passed to the LAPI_Nopoll_wait function. The behavior of LAPI_Purgue_totask is undefined if LAPI Global functions are utilized.

If you want to avoid any possible trickle traffic that may exist in the network, you should also call LAPI_Senv(hndl,EPOCH_NUM,new epoch_num) function to ensure LAPI does not receive any old message that may exist from the purged task. This resets the global state so all nodes that are still up need to make the same call, otherwise communication packets will be dropped. Also the node coming up must utilize the new epoch_num as part of initializing the lapi_info_t structure for the LAPI_Init call. If LAPI_Purge_totask is used, then once the purged task comes up the user must call LAPI_Resume_totask to be able to send messages to the re-initialized task. Also, if LAPI_Purge_totask was called and subsequent LAPI communication calls were made to the task that was purged, those calls will return with the following error code: LAPI_ERR_PURGED_TASK .

Note:
This function should not be used when the parallel application is running under the POE/LL environment. The library level must be L2_LIB to call this function.

Return Values

LAPI_SUCCESS
Indicates the state was successfully reset.

LAPI_ERR_BAD_PARAMETER
A parameter passed in was not valid.

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Init, LAPI_Nopoll_wait, LAPI_Resume_totask, LAPI_Setcntr_wstatus

LAPI_Put subroutine

Purpose

LAPI_Put - Puts data into the target address on a target process.

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, cmpl_cntr, ierror)
|INTEGER hndl
|INTEGER tgt
|INTEGER (KIND=LAPI_INT_TYPE) len
|INTEGER (KIND=LAPI_ADDR_TYPE) :: tgt_addr
|INTEGER org_addr
|TYPE (LAPI_CNTR_T) :: tgt_cntr
|TYPE (LAPI_CNTR_T) :: org_cntr
|TYPE (LAPI_CNTR_T) :: cmpl_cntr
|INTEGER ierror

Parameters

hndl
IN Contains a handle that specifies a particular Low-Level Application Programming Interface (LAPI) context.

tgt
IN Specifies the target task number. This parameter is valid from 0 <= tgt < LAPI_Qenv(,NUM_TASKS,).

len
IN Specifies the number of bytes to be transferred. This parameter is valid from 0 <= len <= LAPI_Qenv(,MAX_DATA_SZ,).

tgt_addr
IN Specifies the address on the target process where data is to be copied into. This parameter can be NULL only if len is equivalent to 0.

org_addr
IN Specifies the address on the origin process where data is to be copied from. This parameter can be NULL only if len is equivalent to 0.

tgt_cntr
IN Specifies the target counter address. The target counter is incremented after data arrives at the target. If the parameter is NULL, this counter will not be updated.

org_cntr
IN/OUT Specifies the origin counter address. The origin counter is incremented after data is copied out of the origin address. If the parameter is NULL, this counter will not be updated.

cmpl_cntr
IN/OUT Specifies the address of the completion counter that is a reflection of the tgt_cntr. This counter is incremented at the origin after the tgt_cntr is incremented. If the parameter is NULL, the counter will not be updated.

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

Use this subroutine to transfer the len number of bytes from the org_addr virtual address on the origin to the tgt target process at the tgt_address address over the port identified by hndl. After the data is copied out of the memory at org_addr, the org_cntr is incremented. After the data arrives at the tgt, the tgt_cntr is incremented. If either counter address is NULL, the data transfer occurs, but the corresponding counter increment does not take place.

This is a nonblocking call in that the calling program cannot assume that the origin buffer can be changed, nor that the contents of the memory pointed to by tgt_addr on tgt is ready for use. However, after the origin waits for the org_cntr update to complete, the origin can modify the org_addr origin buffer. Similarly, the target can modify the data in the tgt_addr target buffer after it has waited for the tgt_cntr update to complete on the target. This call can be made synchronous if the origin waits for the cmpl_cntr update to complete.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_BAD_PARAMETER
Indicates that a parameter was passed in that was not valid.

LAPI_ERR_PURGED_TASK
Returned early due to LAPI_Purge_totask being called.

Location

/usr/lib/liblapi_r.a

Prerequisite Information

Refer to the "Understanding the Communications Low-Level Application Programming Interface" chapter in PSSP: Administration Guide for additional LAPI information.

Related Information

Subroutines: LAPI_Fence, LAPI_Get, LAPI_Getcntr, LAPI_Getv, LAPI_Putv, LAPI_Qenv, LAPI_Waitcntr

LAPI_Putv subroutine

Purpose

LAPI_Putv - Puts vectors of data from the origin process address space into the target process address space.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
int LAPI_Putv(hndl, tgt, tgt_vec, org_vec, tcntr, ocntr, ccntr)
 
lapi handle t hndl;
uint tgt;
lapi_vec_t *tgt_vec;
lapi_vec_t *org_vec;
lapi_cntr_t *tcntr;
lapi_cntr_t *ocntr;
lapi_cntr_t *ccntr;

FORTRAN Syntax

| include 'lapif.h'
| 
|LAPI_PUTV(hndl, tgt, tgt_vec, org_vec, tcntr, ocntr, ccntr, ierror)
|org_cntr, cmpl_cntr, ierror)
|INTEGER hndl
|INTEGER tgt
|TYPE (LAPI_VEC_T) :: tgt_vec
|TYPE (LAPI_VEC_T) :: org_vec
|TYPE (LAPI_CNTR_T) :: tcntr, ocntr, ccntr
|INTEGER ierror

Parameters

hndl
IN Specifies the LAPI context.

tgt
IN Specifies the task ID of the target process.

tgt_vec
IN Points to the target i/o vector description.

org_vec
IN Points to the origin i/o vector description.

tcntr
IN Specifies the address of the target counter. This parameter can be NULL.

ocntr
IN/OUT Specifies the address of the origin counter. This parameter can be NULL.

ccntr
IN/OUT Specifies the address of the completion counter. This parameter can be NULL.

ierror
OUT Specifies the FORTRAN return code. It is always the last parameter.

Description

This function transfers data from the origin process address space from locations and lengths described in the org_vec to the target process address space in locations and lengths described in the tgt_vec. Both structures, org_vec and tgt_vec, are located in the origin process address space, but the addresses of the actual vector locations in tgt_vec refer to addresses in the target address space.

This is a non-blocking call in that the calling program may not assume that the origin buffer can be changed, nor that contents of target buffers (described in tgt_vec) on the target process is ready for use. Further, you may not assume that the structures org_vec and tgt_vec can be changed before the origin counter and target counter, respectively, are incremented. After the origin counter ocntr is incremented the origin buffers (described in org_vec) and org_vec can be reused by the origin process. After the target counter is incremented the target buffers (described in tgt_vec) and tgt_vec can be reused by the target process. If a completion counter ccntr is provided the ccntr is incremented at the origin, after the tcntr has been incremented at the target. If the any of the counter addresses are NULL, the data transfer happens, but the corresponding counter increments do not take place.

The vector types org_vec->vec_type and tgt_vec->vec_type must be the same. The number of vectors specified in the num_vecs member must be the same on both the origin and target. If a strided vector is being transferred, the size of each block must not be greater than the stride size in bytes. The number of vectors to be transferred must be greater than zero. The length of any vector pointed to by org_vec must not be greater than the length of the corresponding vector pointed to by tgt_vec. The vector lengths specified in org_vec-> len, or org_vec->info in the strided transfer case, must be multiples of the machine word size in bytes. If any of these requirements are not satisfied, an error condition occurs.

LAPI does not check for any overlapping regions among vectors either at the origin or the target. If such overlapping regions exist on the origin side, there may be a degradation in performance. If the overlapping regions exist on the target side, the contents of target buffer are undefined.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_PURGED_TASK
Returned early due to LAPI_Purge_totask being called.

LAPI_ERR_BAD_PARAMETER
A parameter passed in was not valid.

Location

/usr/lib/liblapi_r.a

Prerequisite Information

Refer to the "Understanding the Communications Low-Level Application Programming Interface" chapters in PSSP: Administration Guide for additional LAPI information.

Related Information

Subroutines: LAPI_Amsendv, LAPI_Fence, LAPI_Generic amsendv, LAPI_Get, LAPI_Getcntr, LAPI_Getv, LAPI_Qenv, LAPI_Waitcntr

LAPI_Qenv subroutine

Purpose

LAPI_Qenv - Queries the Low-Level Application Programming Interface (LAPI) interface for parallel job information.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapif.h>
 
int LAPI_Qenv(hndl, query, ret_val)
lapi_handle_t hndl;
lapi_query_t query;
int *ret_val;

FORTRAN Syntax

 include 'lapif.h'
 
LAPI_QENV(hndl, query, ret_val, ierror)
INTEGER hndl
INTEGER query
INTEGER ret_val
INTEGER ierror

Parameters

hndl
IN Specifies the LAPI context.

query
IN Specifies the type of query requested as defined by lapi_query_t in lapi.h.

ret_val
OUT Specifies the integer value of the query request. This parameter cannot be NULL.

ierror
OUT Specifies the FORTRAN return code. It is always the last parameter.

Description

Use this subroutine to query the LAPI interface for information about a specific LAPI instance. lapi_query_t defines the types of LAPI queries available.

typedef enum {  TASK_ID=0,      /* Query task id of current task in
                                   job */
                NUM_TASKS,      /* Query number of tasks in job */
                MAX_UHDR_SZ,    /* Query max. user header size for
                                   AM */
                MAX_DATA_SZ,    /* Query max. data length that can
                                   be sent */
                ERROR_CHK,      /* Query & Set parameter checking
                                   on(nonzero)/off(0) */
                TIMEOUT,        /* Query & Set current comm.
                                   timeout setting in seconds */
                MIN_TIMEOUT,    /* Query minimum comm. timeout
                                   setting */
                MAX_TIMEOUT,    /* Query maximum comm. timeout
                                   setting */
                INTERRUPT_SET,  /* Query & Set interrupt
                                   on(nonzero)/off(0) */
                MAX_PORTS,      /* Query max. available comm. ports */
                MAX_PKT_SZ,     /* Query the payload size of 1 packet */
                NUM_REX_BUFS,   /* Query number of retransmission buffers */
                REX_BUF_SZ,     /* Query size of each retransmission buffer
                                   in bytes */
                LOC_ADDRTBL_SZ, /* Query size of (number of entries in) address */
                EPOCH_NUM,      /* Query & Set epoch number set by user */
                LAST_QUERY} lapi_query_t;

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_BAD_PARAMETER
Indicates that a parameter was passed in that was not valid.

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Amsend, LAPI_Get, LAPI_Put

LAPI_Resume_totask subroutine

Purpose

LAPI_Resume_totask - Re-enables sending messages to the task.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapi.h>
 
int LAPI_Resume_totask(hndl, dest)
lapi_handle_t hndl;
task_t dest; 

FORTRAN Syntax

 include 'lapif.h'
 
int LAPI_RESUME_TOTASK(hndl, dest, ierror)
INTEGER hndl
INTEGER dest
INTEGER ierror

Parameters

hndl
IN Specifies the LAPI context.

dest
IN Specifies the destination instance ID with which to resume communication.

ierror
OUT Specifies the FORTRAN return code. It is always the last parameter.

Description

This function re-enables messages to be sent to the purged task. If a task goes down and this task calls LAPI_Purged_totask() it must call LAPI_Resume_totask() to resume communication with that task. The purged node must also either restart LAPI or run a corresponding purge/resume sequence for communication to resume.

Note:
This function should not be used when the parallel application is running under the POE/LL environment. The library level must be set to L2_LIB to call this function.

Return Values

LAPI_SUCCESS
Indicates the state was successfully reset.

LAPI_ERR_BAD_PARAMETER
A parameter passed in was not valid.

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Init, LAPI_Nopoll_wait, LAPI_Purge_totask

LAPI_Rmw subroutine

Purpose

LAPI_Rmw - Provides the synchronization primitives.

Library

Availability Library (liblapi_r.a)

C Syntax

| #include <lapi.h>
| 
|int LAPI_Rmw(hndl, op, tgt, tgt_var, in_val, prev_tgt_val, org_cntr)
| 
|lapi_handle_t hndl;
|RMW_ops_t op;
|uint tgt;
|int *tgt_var;
|int *in_val;
|int *prev_tgt_val;
|TYPE (LAPI_CNTR_T) :: org_cntr;

FORTRAN Syntax

| include 'lapif.h'
| 
|LAPI_RMW(hndl, op, tgt, tgt_var, in_val, prev_tgt_val, org_cntr, ierror)
|INTEGER hndl
|INTEGER op
|INTEGER tgt
|INTEGER (KIND=LAPI_ADDR_TYPE) :: tgt_var
|INTEGER in_val
|INTEGER prev_tgt_val
|TYPE (LAPI_CNTR_T) :: org_cntr
|INTEGER ierror

Parameters

hndl
IN Contains a handle that specifies a particular Low-Level Application Programming Interface (LAPI) context.

op
IN Specifies the operation to be performed.

tgt
IN Specifies the target task where the Read-Modify-Write (RMW) variable resides. This parameter is valid from 0 <= tgt < LAPI_Qenv(,NUM_TASKS,).

tgt_var
IN Specifies the target RMW variable address. This parameter cannot be NULL.

in_val
IN Specifies the value input to the op. This parameter cannot be NULL.

prev_tgt_val
IN/OUT Specifies the location at the origin in which the previous tgt_var on the target process is stored before the RMW op is executed. This parameter can be NULL.

org_cntr
IN/OUT Specifies the origin counter address. The origin counter is incremented after data is copied out of the origin address. If the parameter is NULL, this counter will not be updated.

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

Use this subroutine to synchronize two independent operations, such as two processes sharing a common data structure. The operation is performed at the tgt target process and is atomic. The operation takes an in_val from the origin and performs one of four selected op operations on a tgt_var variable at the tgt target, and then replaces the tgt_var target variable with the results of the op operation. The prev_tgt_val original value of the tgt_var target variable is returned to the origin.

The valid operations for op are:

The operations are performed over the context referred to by hndl. The outcome of the execution of these calls is as if the following code was executed atomically:

*prev_tgt_val = *tgt_var;
*tgt_var = f(*tgt_var, *in_val);

where:

f(a,b) = a + b for FETCH_AND_ADD

f(a,b) = a | b for FETCH_AND_OR (bitwise or)

f(a,b) = b for SWAP

For COMPARE_AND_SWAP, in_val is treated as a pointer to an array of two integers, and the op is the following atomic operation:

if(*tgt_var == in_val[0])  {
   *prev_tgt_val = TRUE;
*tgt_var = in_val[1];
} else {
   *prev_tgt_val = FALSE;
}

All the calls are nonblocking. To test for completion, use the LAPI_Getcntr and LAPI_Waitcntr functions. There is no tgt_cntr on RMW calls and they do not provide any indication of completion on the tgt process.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_PURGED_TASK
Returned early due to LAPI_Purge_totask being called.

LAPI_ERR_BAD_PARAMETER
Indicates that addresses were passed in that were not valid.

Location

/usr/lib/liblapi_r.a

Prerequisite Information

Refer to the "Understanding the Communications Low-Level Application Programming Interface" chapter in PSSP: Administration Guide for additional LAPI information.

Related Information

Subroutines: LAPI_Getcntr, LAPI_Qenv, LAPI_Setcntr, LAPI_Waitcntr

|LAPI_Rmw64 subroutine

|Purpose

|LAPI_Rmw64 - Provides the synchronization |primitives. | |

|Library

|Availability Library (liblapi_r.a)

|C Syntax

| #include <lapi.h>
| 
|int LAPI_Rmw64(hndl, op, tgt, tgt_var, in_val, prev_tgt_val, org_cntr)
| 
|lapi_handle_t hndl;
|Rmw64_ops_t op;
|uint tgt;
|long long *tgt_var;
|long long *in_val;
|long long *prev_tgt_val;
|lapi_cntr_t *org_cntr;

|FORTRAN Syntax

| include 'lapif.h'
| 
|LAPI_Rmw64(hndl, op, tgt, tgt_var, in_val, prev_tgt_val, org_cntr, ierror)
|INTEGER hndl
|INTEGER op
|INTEGER tgt
|INTEGER (KIND=LAPI_ADDR_TYPE) tgt_var
|INTEGER (KIND=LAPI_LONG_LONG_TYPE) :: in_val, prev_tgt_val
|TYPE (LAPI_CNTR_T) :: org_cntr
|INTEGER ierror

|Parameters

|

|hndl
|IN Contains a handle that specifies a particular Low-Level |Application Programming Interface (LAPI) context.

|op
|IN Specifies the operation to be performed. |

|tgt
|IN Specifies the target task where the Read-Modify-Write (Rmw64) |variable resides. This parameter is valid from 0 <= |tgt < LAPI_Qenv(,NUM_TASKS,). |

|tgt_var
|IN Specifies the target Rmw64 variable address. This |parameter cannot be NULL.

|in_val
|IN Specifies the value input to the op. This |parameter cannot be NULL. |

|prev_tgt_val
|IN/OUT Specifies the location at the origin in which the previous |tgt_var on the target process is stored before the Rmw64 op |is executed. This parameter can be NULL.

|org_cntr
|IN/OUT Specifies the origin counter address. The origin |counter is incremented after data is copied out of the origin address. |If the parameter is NULL, this counter will not be updated.

|ierror
|OUT Specifies a FORTRAN return code. It is always the last |argument. |

|Description

|The LAPI_Rmw64 subroutine, which is similar to LAPI_Rmw, |is used to synchronize two independent operations, such as two processes |sharing a common data structure. The operation is performed at the |tgt target process and is atomic. The operation takes an |in_val from the origin and performs one of four selected op |operations on a tgt_var variable at the tgt target, and then |replaces the tgt_var target variable with the results of the |op operation. The prev_tgt_val original value of the |tgt_var target variable is returned to the origin.

|The valid operations for op are: |

|The operations are performed over the context referred to by |hndl. The outcome of the execution of these calls is as if the |following code was executed atomically:

|*prev_tgt_val = *tgt_var;
|*tgt_var = f(*tgt_var, *in_val);

|where:

|f(a,b) = a + b for FETCH_AND_ADD

|f(a,b) = a | b for FETCH_AND_OR (bitwise or)

|f(a,b) = b for SWAP

|For COMPARE_AND_SWAP, in_val is treated as a pointer to |an array of two integers, and the op is the following atomic |operation:

|if(*tgt_var == in_val[0])  {
|   *prev_tgt_val = TRUE;
|*tgt_var = in_val[1];
|} else {
|   *prev_tgt_val = FALSE;
|}

|This subroutine can also be used on a 32-bit machine. If used on a |32-bit machine, long long type is treated as two integers when it is |sent to the target to perform COMPARE_AND_SWAP.

|All the calls are nonblocking. To test for completion, use the |LAPI_Getcntr and LAPI_Waitcntr functions. There is no |tgt_cntr on |Rmw64 calls and they do not provide any indication of completion on the |tgt process.

|Return Values

|

|LAPI_SUCCESS
|Indicates successful completion.

|LAPI_ERR_PURGED_TASK
|Returned early due to LAPI_Purge_totask being called.

|LAPI_ERR_BAD_PARAMETER
|Indicates that addresses were passed in that were not valid. |

|Location

|/usr/lib/liblapi_r.a

|Prerequisite Information

|Refer to the "Understanding the Communications Low-Level Application |Programming Interface" chapter in PSSP: Administration |Guide for additional LAPI information.

|Related Information

|Subroutines: LAPI_Getcntr, LAPI_PROBE, |LAPI_Qenv, LAPI_Setcntr, LAPI_Waitcntr

|New in PSSP 3.4, L3_LIB must be set for the |LAPI_Rmw64 subroutine.

LAPI_Senv subroutine

Purpose

LAPI_Senv - Sets the Low-level Application Programming Interface (LAPI) environment for the specified context.

Library

Availability Library (liblapi_r.a)

C Syntax

 #include <lapif.h>
 
int LAPI_Senv(hndl, query, set_val)
lapi_handle_t hndl;
lapi_query_t query;
int set_val;

FORTRAN Syntax

 include 'lapif.h'
 
LAPI_SENV(hndl, query, set_val, ierror)
INTEGER hndl
INTEGER query
INTEGER set_val
INTEGER ierror

Parameters

hndl
IN Specifies the LAPI context.

query
IN Specifies the type of query requested as defined by lapi_query_t in lapi.h.

set_val
IN Specifies the integer value of the query request.

ierror
OUT Specifies a FORTRAN return code. It is always the last argument.

Description

Use this subroutine to set the LAPI environment for a specific LAPI instance. lapi_query_t defines the types of LAPI set environment variables, as prescribed in the LAPI_Qenv() call. Only the subset INTERRUPT_SET, TIMEOUT, ERROR_CHK and EPOCH_NUM may be set.

Return Values

LAPI_SUCCESS
Indicates successful completion.

LAPI_ERR_BAD_PARAMETER
Indicates that a parameter was passed in that was not valid.

Location

/usr/lib/liblapi_r.a

Related Information

Subroutines: LAPI_Qenv


[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]