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)