LAPI_Msgpoll Subroutine

Purpose

Allows the calling thread to check communication progress.

Library

Availability Library (liblapi_r.a)

C Syntax

#include <lapi.h>
 
int LAPI_Msgpoll(hndl, cnt, info)
lapi_handle_t     hndl;
uint              cnt;
lapi_msg_info_t  *info;

      
typedef struct {
    lapi_msg_state_t  status;      /* Message status returned from LAPI_Msgpoll */
    ulong             reserve[10]; /* Reserved                                  */
} lapi_msg_info_t;

FORTRAN Syntax

include 'lapif.h'
 
LAPI_MSGPOLL(hndl, cnt, info, ierror)
INTEGER hndl
INTEGER cnt
TYPE (LAPI_MSG_STATE_T) :: info
INTEGER ierror

Description

Type of call: local progress monitor (blocking)

The LAPI_Msgpoll subroutine allows the calling thread to check communication progress. With this subroutine, LAPI provides a means of running the dispatcher several times until either progress is made or a specified maximum number of dispatcher loops have executed. Here, progress is defined as the completion of either a message send operation or a message receive operation.

LAPI_Msgpoll is intended to be used when interrupts are turned off. If the user has not explicitly turned interrupts off, LAPI temporarily disables interrupt mode while in this subroutine because the dispatcher is called, which will process any pending receive operations. If the LAPI dispatcher loops for the specified maximum number of times, the call returns. If progress is made before the maximum count, the call will return immediately. In either case, LAPI will report status through a data structure that is passed by reference.

The lapi_msg_info_t structure contains a flags field (status), which is of type lapi_msg_state_t. Flags in the status field are set as follows:

LAPI_DISP_CNTR: If the dispatcher has looped cnt times without making progress
LAPI_SEND_COMPLETE: If a message send operation has completed
LAPI_RECV_COMPLETE: If a message receive operation has completed
LAPI_BOTH_COMPLETE: If both a message send operation and a message receive operation have completed
LAPI_POLLING_NET: If another thread is already polling the network or shared memory completion

Parameters

INPUT
hndl: Specifies the LAPI handle.
cnt: Specifies the maximum number of times the dispatcher should loop with no progress before returning.
info: Specifies a status structure that contains the result of the LAPI_Msgpoll() call.
OUTPUT
ierror: Specifies a FORTRAN return code. This is always the last parameter.

C Examples

To loop through the dispatcher no more than 1000 times, then check what progress has been made:

{

    lapi_msg_info_t msg_info;
    int cnt = 1000;
    .  
    .
    .
    LAPI_Msgpoll(hndl, cnt, &msg_info);

    if ( msg_info.status & LAPI_BOTH_COMPLETE ) {
        /* both a message receive and a message send have been completed */
    } else if ( msg_info.status & LAPI_RECV_COMPLETE ) {
        /* just a message receive has been completed                     */
    } else if ( msg_info.status & LAPI_SEND_COMPLETE ) {
        /* just a message send has been completed                        */
    } else {
        /* cnt loops and no progress                                     */
    }


}

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_MSG_INFO_NULL: Indicates that the info pointer is NULL (in C) or that the value of info is LAPI_ADDR_NULL (in FORTRAN).

Location

/usr/lib/liblapi_r.a