NAME

       shmem_set_lock(3),  shmem_clear_lock(3), shmem_test_lock(3) - Releases, locks, and tests a
       mutual exclusion memory lock.

SYNOPSIS

       C or C++:
       #include <mpp/shmem.h>

       void shmem_clear_lock(volatile long *lock);

       void shmem_set_lock(volatile long *lock);

       int shmem_test_lock(volatile long *lock);

       Fortran:
       INCLUDE "mpp/shmem.fh"

       INTEGER lock, SHMEM_TEST_LOCK

       CALL SHMEM_CLEAR_LOCK(lock)

       CALL SHMEM_SET_LOCK(lock)

       I = SHMEM_TEST_LOCK(lock)

DESCRIPTION

       The shmem_set_lock routine sets a mutual exclusion lock after waiting for the lock  to  be
       freed  by  any other PE currently holding the lock. Waiting PEs are assured of getting the
       lock in a first-come, first-served manner.

       The shmem_clear_lock routine releases  a  lock  previously  set  by  shmem_set_lock  after
       ensuring that all local and remote stores initiated in the critical region are complete.

       The shmem_test_lock function sets a mutual exclusion lock only if it is currently cleared.
       By using this function, a PE can avoid blocking on a set lock. If the  lock  is  currently
       set,  the function returns without waiting.  These routines are appropriate for protecting
       a critical region from simultaneous update by multiple PEs.   They  accept  the  following
       arguments:

       lock   A  symmetric  data  object  that is a scalar variable or an array of length 1. This
              data object must be set to 0 on all processing elements (PEs) prior  to  the  first
              use.  lock must be of type integer. If you are using Fortran, it must be of default
              kind.

NOTES

       The term symmetric data object is defined on intro_shmem(3).

RETURN VALUES

       The shmem_test_lock function returns 0 if the lock was originally cleared  and  this  call
       was  able  to set the lock. A value of 1 is returned if the lock had been set and the call
       returned without waiting to set the lock.

SEE ALSO

       intro_shmem(3)