omp_lock(3)

NAME
     omp_init_lock, omp_destroy_lock, omp_set_lock, omp_unset_lock,
     omp_test_lock, OMP_INIT_LOCK, OMP_DESTROY_LOCK, OMP_SET_LOCK,
     OMP_UNSET_LOCK, OMP_TEST_LOCK  - Set of procedures to manipulate locks

SYNOPSIS
     C/C++:
          #integer <omp_init_lock>
          void omp_init_lock(var)

          #integer <omp_destroy_lock>
          void omp_destory_lock(var)

          #integer <omp_set_lock>
          void omp_set_lock(var)

          #integer <omp_unset_lock>
          void omp_unset_lock(var)

          #integer <omp_test_lock>
          int omp_test_lock(var)

     Fortran:
          CALL OMP_INIT_LOCK(var)

          CALL OMP_DESTROY_LOCK(var)

          CALL OMP_SET_LOCK(var)

          CALL OMP_UNSET_LOCK(var)

          LOGICAL OMP_TEST_LOCK(var)

STANDARDS
     OpenMP Fortran API
     OpenMP C/C++ API

DESCRIPTION
     The following descriptions contain information for Fortran and C/C++.

     omp_init_lock, OMP_INIT_LOCK
          This subroutine initializes a lock associated with the lock
          variable var for use in subsequent calls.

          The initial state is unlocked.  The lock variable must only be
          accessed through these routines.  In this and the following lock
          routines, var should be a scalar integer variable in C and of
          type integer in Fortran and must have a size large enough to hold
          an address.  For example, for 64-bit addressable systems, the
          variable must at least by declared as INTEGER*8.

     omp_destory_lock, OMP_DESTROY_LOCK
          This procedure disassociates the given lock variable var from any
          locks.

     omp_set_lock, OMP_SET_LOCK
          This procedure constrins the executing thread to wait until the
          specified lock is available.  The thread is granted ownership of
          the lock when it is available.

     omp_unset_lock, OMP_UNSET_LOCK
          This procedure releases the executing thread from ownership of
          the lock.  The behavior is undefined if the thread does not own
          that lock.

     omp_test_lock, OMP_TEST_LOCK
          This function tries to set the lock associated with the lock
          variable var.  It returns non-zero (TRUE) if the lock is
          successfully set; otherwise, it returns zero (FALSE).

EXAMPLES
     For the OpenMP directives to be honored by the compiler, you must
     specify -mp on your compiler command line explicitly.  In addition,
     -MP:open_mp=ON, which is the default setting, must be in effect.

     In the following Fortran 90 example, the argument to the lock routines
     should be of size POINTER:

                PROGRAM LOCK_USAGE
                EXTERNAL OMP_TEST_LOCK
                LOGICAL OMP_TEST_LOCK

                INTEGER LCK         ! THIS VARIABLE SHOULD BE POINTER SIZED

                CALL OMP_INIT_LOCK(LCK)
          !$OMP PARALLEL SHARED(LCK) PRIVATE(ID)
                ID = OMP_GET_THREAD_NUM()
                CALL OMP_SET_LOCK(LCK)
                PRINT *, 'MY THREAD ID IS ', ID
                CALL OMP_UNSET_LOCK(LCK)

                DO WHILE (.NOT. OMP_TEST_LOCK(LCK))
                  CALL SKIP(ID)     ! WE DO NOT YET HAVE THE LOCK
                                    ! SO WE MUST DO SOMETHING ELSE
                END DO

                CALL WORK(ID)       ! WE NOW HAVE THE LOCK
                                    ! AND CAN DO THE WORK
                CALL OMP_UNSET_LOCK( LCK )
          !$OMP END PARALLEL

                CALL OMP_DESTROY_LOCK( LCK )

                END

SEE ALSO
     omp_nested(3) to manipulate or report status of nested parallelism,

     omp_threads(3) for runtime library procedures used to set, call or
     return numbers of threads