LAPI_Setcntr Subroutine

Purpose

Used to set a counter to a specified value.

Library

Availability Library (liblapi_r.a)

C Syntax

#include <lapi.h>
 
int LAPI_Setcntr(hndl, cntr, val)
lapi_handle_t hndl;
lapi_cntr_t  *cntr;
int           val;

FORTRAN Syntax

include 'lapif.h'
 
LAPI_SETCNTR(hndl, cntr, val, ierror)
INTEGER hndl
TYPE (LAPI_CNTR_T) :: cntr
INTEGER val
INTEGER ierror

Description

Type of call: Local counter manipulation

This subroutine sets cntr to the value specified by val. Because the LAPI_Getcntr/LAPI_Setcntr sequence cannot be made atomic, you should only use LAPI_Setcntr when you know there will not be any competing operations.

Parameters

INPUT
hndl: Specifies the LAPI handle.
val: Specifies the value to which the counter needs to be set.
INPUT/OUTPUT
cntr: Specifies the address of the counter to be set (in C) or the counter structure (in FORTRAN). The value of this parameter cannot be NULL (in C) or LAPI_ADDR_NULL (in FORTRAN).
OUTPUT
ierror: Specifies a FORTRAN return code. This is always the last parameter.

Restrictions

LAPI statistics are not reported for shared memory communication and data transfer, or for messages that a task sends to itself.

C Examples

To initialize a counter for use in a communication API call:

{
    lapi_cntr_t   my_tgt_cntr, *tgt_cntr_array;
    int           initial_value, expected_value, current_value;
    lapi_handle_t hndl;
    .
    .
    .
    /*
     * Note: the code below is executed on all tasks 
     */

    /* initialize, allocate and create structures */
    initial_value  = 0;
    expected_value = 1;

    /* set the cntr to zero */ 
    LAPI_Setcntr(hndl, &my_tgt_cntr, initial_value);
    /* set other counters   */
    .
    .
    .
    /* exchange counter addresses, LAPI_Address_init synchronizes */ 
    LAPI_Address_init(hndl, &my_tgt_cntr, tgt_cntr_array);
    /* more address exchanges */
    .
    .
    .
    /* Communication calls using my_tgt_cntr */
    LAPI_Put(....., tgt_cntr_array[tgt], ....);
    .
    .
    .
    /* Wait for counter to reach value */ 
    for (;;) {
        LAPI_Getcntr(hndl, &my_tgt_cntr, &current_value);
        if (current_value >= expected_value) {
            break; /* out of infinite loop */
        } else {
            LAPI_Probe(hndl);
        }
    }
    .
    .
    .
    /* Quiesce/synchronize to ensure communication using our counter is done */
    LAPI_Gfence(hndl);
    /* Reset the counter */
    LAPI_Setcntr(hndl, &my_tgt_cntr, initial_value);
    /* 
     * Synchronize again so that no other communication using the counter can 
     * begin from any other task until we're all finished resetting the counter.
     */
    LAPI_Gfence(hndl);

    /* More communication calls */
    .
    .
    .
}

Return Values

LAPI_SUCCESS: Indicates that the function call completed successfully.
LAPI_ERR_CNTR_NULL: Indicates that the cntr value 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).

Location

/usr/lib/liblapi_r.a